# <link>

Description

A `<link>` element may have one or more grammars. The grammars are in the scope of the element containing this `<link>` element. When the user input matches one of the linked grammars, it activates the `<link>` to either throw an event, or transition to another document or dialog (i.e., form or menu).

Syntax

    <link
        next="URI"
        expr="ECMAScript_Expression"
        event="event"
        eventexpr="ECMAScript_Expression"
        dtmf="DTMF_sequence"
        fetchaudio="URI"
        fetchaudiodelay="time_interval"
        fetchaudiominimum="time_interval"
        fetchhint="safe"
        fetchtimeout="time_interval"
        maxage="integer"
        maxstale="integer"
        message="string"
        messageexpr="ECMAScript_Expression">
      child_elements
    </link>

Attributes

Attribute | Description
next | The URI of the dialog (i.e. form or menu) or document to transition to when the user input matches one of the link grammars. Exactly one of next, expr, event, or eventexpr must be specified.
expr | An ECMAScript expression to be evaluated and used as the URI of the dialog (i.e. form or menu) or document to transition to when the user input matches one of the link grammars. Exactly one of next, expr, event, or eventexpr must be specified.
event | The name of the event to be thrown when the user input matches one of the link grammars. Exactly one of next, expr, event, or eventexpr must be specified.
eventexpr | An ECMAScript expression to be evaluated and used as the name of the event to be thrown when the user input matches one of the link grammars. Exactly one of next, expr, event, or eventexpr must be specified.
dtmf | The DTMF sequence for this link. It is equivalent to a simple DTMF grammar. This attribute can be used at the same time as other grammars: the link is activated when user input matches either a link grammar or this DTMF sequence. Optional.
fetchaudio | The URI of audio to play while waiting for the document to be fetched. Optional.
fetchaudiodelay | The length of time to wait at the start of the fetch delay before playing `fetchaudio`. Optional.
fetchaudiominimum | The minimum length of time to play `fetchaudio`, once started, even if the document arrives in the meantime. Optional.
fetchhint | Defines when the next document should be fetched. Optional. safe - only load the next document when needed
fetchtimeout | The length of time to wait for the next document to be fetched before throwing an `error.badfetch` event. Optional.
maxage | Indicates that this document is willing to use a cached copy of the next document only while the age of the cached copy is less than or equal to the number of seconds specified by this attribute. Optional.
maxstale | Indicates that this document is willing to use a cached copy of the next document that has exceeded its expiration time by as much as the number of seconds specified by this attribute. Optional.
message | A message string providing additional context about the event being thrown. The message will be available as a variable within the scope of the `<catch>` element. Optional. (Can only be used if event or eventexpr is specified; only one of message and messageexpr can be specified.)
messageexpr | An ECMAScript expression to be evaluated and used as a message string, as documented under `message`, above. Optional. (Can only be used if event or eventexpr is specified; only one of message and messageexpr can be specified.)

Attribute Notes

- The event specified by `event`/`eventexpr` is thrown based on the scope of the active dialog (ie. `<field>`,
  `<menu>`, etc., where the user was when the link grammar was matched).
- All attribute values that are ECMAScript expressions are evaluated based on variables from the scope of the active dialog (ie. `<field>`, `<menu>`, etc., where the user was when the link grammar was matched).
- An `error.badfetch` event is thrown if more or less than one of `next`, `expr`, `event`, and `eventexpr` are specified.

Parents

<field>, <form>, <initial>, <vxml>

Children

<dtmf>, <grammar>

Extensions

- Added `fetchaudiodelay` attribute.
- Added `fetchaudiominimum` attribute.
- Added `<dtmf>` as a child, to be used like `<grammar>`.

Limitations/Restrictions

None.

Example

    <?xml version="1.0"?>
    <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
      <link event="goodbye" dtmf="*"/>
      <catch event="goodbye">
        Thank you for calling. Goodbye.
        <exit/>
      </catch>
      <form>
        <field name="field1" type="boolean">
          <prompt>Please press the star.</prompt>
        </field>
      </form>
    </vxml>