link

link element

Specifies one or more grammars and a destination to go to or an event to throw when one is matched.

Syntax

<link 
dtmf = "string"
event = "event"
eventexpr = "ECMAScript_Expression"
expr = "ECMAScript_Expression"
fetchaudio = "URI"
fetchaudioexpr = "ECMAScript_Expression"
fetchhint = "string"
fetchtimeout = "string"
maxage = "seconds"
maxstale = "seconds"
message = "string"
messageexpr = "ECMAScript_Expression"
next = "URI"
/>

Attributes

dtmf	The DTMF sequence for this link. When user input matches the DTMF sequence, the next, expr, event, or eventexpr attribute is executed. DTMF property apply to recognition of the sequence. Whitespace is optional: "123# is equivalent to "1 2 3 #". The attribute can be used at the same time as other grammars.
event	Specifies an event to throw when a link element's grammar is matched. You can specify only one event.
eventexpr	An ECMAScript expression that evaluates to the name of the event to throw.
expr	An ECMAScript expression that evaluates to the URL of the document to jump to if the user's utterance matches the link element's grammar.
fetchaudio	The URI of the audio clip to play while the interpreter fetches the resource. For complete details on the proper use of this attribute, read the fetchaudio tutorial.
fetchaudioexpr	An ECMAScript expression that evaluates to the URI used for fetchaudio. This attribute is a Tellme extension.
fetchhint	Defines when the interpreter context may retrieve documents from the server. prefetchDocuments may be prefetched. safeDocuments may only be fetched when needed, never before.
fetchtimeout	The time in seconds (s) or milliseconds (ms) for the VoiceXML interpreter to wait for content to be returned by the HTTP server before throwing an error.badfetch event. The fetchtimeout value is rounded down to the nearest whole second (e.g., 5700ms or 5.7s would be rounded down to 5s). If fetchtimeout has a value less than 1 second, it is reset to the default value. The default value is 15s.
maxage	Sends the max-age Cache-Control HTTP header along with the request for the specified resource. The header indicates that the document is willing to use content whose age is no greater than the specified time in seconds, unless maxstale is also provided. Voice application developers should use extreme caution when setting this attribute. If used improperly, it could have an adverse affect on the performance of your application. You should only consider using this attribute in requests for frequently changing content (e.g. dynamically generated content) hosted on a misconfigured HTTP server that you do not control. To reduce load, some HTTP servers are configured to indicate to clients that content expires some arbitrary time in the future. In that case, set the maxage attribute to 0. If you do control the HTTP server, you should instead configure the HTTP server to omit the expires header and possibly to send the Cache-Control: no-cache header. The former requires the VoiceXML interpreter to check with the server before using any cached content. The latter requires the VoiceXML interpreter to not cache the fetched resource.
maxstale	Instructs the VoiceXML interpreter to send a max-stale Cache-Control header along with the HTTP request for the specified resource. The header indicates that the document is willing to use content that has exceeded its expiration time by no more than the specified number of seconds. Voice application developers should use extreme caution when setting this attribute. If used improperly, your application may present stale content to users. If you do control the HTTP server, you should instead configure the HTTP server to send an expires header with a time in the distant future.
message	Additional information about the event being thrown. The string is available as the value of the _message variable within the scope of the event handler.
messageexpr	An ECMAScript expression that evaluates to a message string.
next	The URI of the document or anchor within the current document to jump to if the user's utterance matches the grammar specified by the grammar element.

Parents

field, form, initial, vxml

Children

grammar

Remarks

A link grammar doesn't specify a return value. The VoiceXML interpreter automatically jumps to the URI or fires the event specified by the next, expr, or event attributes when there is a recognition match.

Prior to Revision 3, a link grammar must be defined inline. Externally referenced link grammars are supported in Revision 3 and later.

The next, expr, event, and eventexpr attributes are mutually exclusive.

The message and messageexpr attributes are mutually exclusive.

The fetchaudio and fetchaudioexpr attributes are mutually exclusive. If both of these attributes are specified an error.badfetch event is thrown.

If any of the fetchtimeout, fetchhint, maxage, or maxstale attributes is not specified for a link element, then the value of the fetchtimeout, documentfetchhint, documentmaxage, or documentmaxstale property, respectively, is used.

In Revision 3 or later, if hotword bargein is enabled, a link grammar will only be matched if the grammar specifies a semantic result (i.e. specifies a right-hand-side).

Examples

The following example demonstrates a simple shopping cart. It uses link elements to handle the utterances "start over", "tellme menu", and "checkout."

<?xml version="1.0"?>
<vxml version="2.1"
 xmlns="http://www.w3.org/2001/vxml">
   <!-- throw startover event when user says "start over" --> 
   <link event="event.myapp.startover">
   
   <grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0"
         xml:lang="en-US">
      <rule id="root_rule" scope="public">
         <one-of>
            <item>
               start
               over
            </item>
         </one-of>
      </rule>

   </grammar>

   </link>

   <link event="event.myapp.checkout">
   
   <grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0"
         xml:lang="en-US">
      <rule id="root_rule" scope="public">
         <one-of>
            <item>
               checkout
            </item>
         </one-of>
      </rule>

   </grammar>

   </link>

   <!-- leave the store without buying -->
   <link next="#exit">
   
   <grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0"
         xml:lang="en-US">
      <rule id="root_rule" scope="public">
         <one-of>
            <item>
               exit
            </item>
            <item>
               leave
            </item>
         </one-of>
      </rule>

   </grammar>

   </link>

   <!-- generate a help event when user says "help" -->
   <link event="help">
   
   <grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0"
         xml:lang="en-US">
      <rule id="root_rule" scope="public">
         <one-of>
            <item weight="1.0">
               help
            </item>
         </one-of>
      </rule>

   </grammar>

   
   <grammar mode="dtmf"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0">
      <rule id="root_rule" scope="public">
         <one-of>
            <item>
               0
            </item>
         </one-of>
      </rule>

   </grammar>

   </link>

   <!-- handle the event that results when the user says "start over" -->
   <catch event="event.myapp.startover">
      <goto next="#confirm_start_over"/>
   </catch>

   <!-- handle the event that results when the user says "checkout" -->
   <catch event="event.myapp.checkout">
      <goto next="#checkout"/>
   </catch>


   <script><![CDATA[
   var ghCart = {}; // simple shopping cart

   // add the item to the shopping cart
   function AddItem(hCart, sItem)
   {
      var iCount = (hCart[sItem] || 0);
      hCart[sItem] = iCount + 1;
   }

   // return an array of (name, count) tuples of the items in the cart
   function GetItems(hCart)
   {
      var aItems = [];

      for (var sItem in hCart)
      {
         var iCount = hCart[sItem];
         aItems.push({"name" : sItem, "count" : iCount});
      }    

      return aItems;
   }
   ]]></script>

   <form id="main">
   <block>
      Welcome to ack me fruit traders
      <!-- initialize the shopping cart -->
      <script>ghCart = {}</script>
      <goto next="#pick_fruit"/>
   </block>
   </form>

   <form id="pick_fruit">

   <field name="fruit">
      <prompt>
      Pick a fruit, or say checkout at any time.
      </prompt>

      
      <grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0"
         xml:lang="en-US">
            <rule id="root_rule" scope="public">
                  <one-of>
                        <item>
                              <one-of>
                                    <item>
                                          apple
                                    </item>
                              </one-of>
                              <tag>out.fruit = "apple";</tag>
                        </item>
                        <item>
                              <one-of>
                                    <item>
                                          orange
                                    </item>
                              </one-of>
                              <tag>out.fruit = "orange";</tag>
                        </item>
                        <item>
                              <one-of>
                                    <item>
                                          pear
                                    </item>
                              </one-of>
                              <tag>out.fruit = "pear";</tag>
                        </item>
                        <item>
                              <one-of>
                                    <item>
                                          banana
                                    </item>
                              </one-of>
                              <tag>out.fruit = "banana";</tag>
                        </item>
                  </one-of>
            </rule>

      </grammar>


      <noinput>
         I'm sorry. I didn't hear you.
         <reprompt/>
      </noinput>

      <help>
         Say apple, orange, pear, or banana. 
            To check out say checkout.
      </help>

      <nomatch>
         I'm sorry. I didn't get that.
         <reprompt/>
      </nomatch>

      <filled>
         Adding <value expr="fruit"/> to your shopping cart.
         <script>AddItem(ghCart, fruit)</script>
         <clear namelist="fruit"/>
         <reprompt/>
      </filled>

      </field>
   </form>

   <!-- verifies that the user wants to dump their cart and start over -->
   <form id="confirm_start_over">

      <field name="yesno" type="boolean">
      <prompt>
      Are you sure you want to start over?
      </prompt>

      <catch event="nomatch noinput">
         Sorry. I didn't get that. 
            Say 'yes' to start over; say 'no' to continue shopping.
         <reprompt/>
      </catch>

      <filled>
         <if cond="yesno">
            <goto next="#main"/>
         <else/>
            <goto next="#pick_fruit"/>
         </if>
      </filled>

      </field>
   </form>

   <!-- checks out the user by reading back the contents of their cart -->
   <form id="checkout">
      <block>
         <var name="aItems" expr="GetItems(ghCart)"/>
         <if cond="aItems.length &gt; 0">
            Here's the list of items in your cart
            <foreach item="oItem" array="aItems">
               <value expr="oItem.count"/>
               <value expr="oItem.name"/>
            </foreach>
         </if> 
         <exit />
      </block>
   </form>

   <form id="exit">
   <block>
      <exit />
   </block>
   </form>
</vxml>