VoiceXML: Tutorial

A <subdialog> element invokes a “called” dialog (known as the subdialog) identified by its src attribute. The subdialog executes in a new execution context. The subdialog proceeds until the execution of a <return> element which causes the subdialog to return. When the subdialog returns, its execution context is deleted, and execution resumes in the calling dialog with any appropriate <filled> elements. An execution context includes all declarations and state information for the dialog, the dialog’s document, and the application root (if present). Subdialogs can permit the reuse of a common dialog such as this example of prompting a user for credit card information, or build libraries of reusable applications.

The <subdialog> element may contain elements common to all form items, and may also contain <param> elements. The <param> elements of a <subdialog> specify the parameters to pass to the subdialog. These parameters must be declared in the subdialog using <var> elements; it is a semantic error to attempt to set a form item variable or an undeclared variable using <param>. When a subdialog initializes, its variables are initialized in document order to the corresponding <param> value, if they don't have an expr attribute. Thus <param> elements can only initialize <var> elements without expr attributes.

In the example below, the birthday of an individual is used to validate their driver's license. The src attribute of the subdialog refers to a form that is within the same document. The <param> element is used to pass the birthday value to the subdialog.

The driver’s license value is returned to calling dialog, along with a status variable in order to indicate whether the license is valid or not.

This example also illustrates the convenience of using <param> as a means for forwarding data to the subdialog as a means of instantiating values in the subdialog without using server side scripting. An alternate solution that uses scripting, is shown below.

Document with form that calls a subdialog

name	The result returned from the subdialog, an ECMAScript object whose properties are the ones defined in the namelistattribute of the <return> element.
expr	The initial value of the form item variable; default is ECMAScript undefined. If initialized to a value, then the form item will not be visited unless the form item variable is cleared.
cond	A boolean condition that must also evaluate to true in order for the form item to be visited.
modal	Controls which grammars are active during the subdialog. If true (the default) all grammars active in the calling dialog are disabled. If false, they remain active.
namelist	Same as namelist in <submit>, except that the default is to submit nothing. Only valid when fetching another document.
src	The URI of the <subdialog>.

Document containing the subdialog (generated by /cgi-bin/getlib)

In the above example, a server side script had to generate the document and embed the birthday value.

When a subdialog is interpreted, the only active grammars are those in dialog-scope of the subdialog and the default grammars defined by the interpreter context (e.g. help, cancel). The set of active grammars remains limited for all subsequent dialogs until a <return> is executed. For example, if subdialog A transitions to dialog B, then the interpretation of B considers only active grammars in its dialog scope and the default grammars.

One last example is shown below that illustrates a subdialog to capture general credit card information. First the subdialog is defined in a separate document; it is intended to be reusable across different applications. It returns a status, the credit card number, and the expiry date; if a result cannot be obtained, the status is returned with value "no_result".

An application that includes a calling dialog is shown below. It obtains the name of a software product and operating system using a mixed initiative dialog, and then solicits credit card information using the subdialog.

The following example jumps to a local subdialog, fruit_picker, that asks the user to pick a piece of fruit. Once the user selects a fruit, the value is returned to the calling dialog via the namelist attribute. The calling dialog accesses the value as a property of the object named by the name attribute of the subdialog element. To see that the subdialog and its caller do not share execution contexts, run the example, check the debug log, and observe that the calling_dialog variable is reinitialized to the value "none" within the context of the subdialog even though it is set to "main" in the calling dialog before the subdialog is executed.

<?xml version="1.0"?>
<vxml version="2.0">

   <var name="calling_dialog" expr="'none'" />
   <var name="user" expr="'unknown'" />

   <form id="main">
   <block>
      <assign name="calling_dialog" expr="'main'"/>
      <assign name="user" expr="'noah'"/>
   </block>
   <subdialog src="#fruit_picker" name="oResult">
      <param name="customer" expr="document.user"/>
      <catch event="event.failed">
         <audio>fruit picker failed</audio>
      </catch>
      <filled>
        <audio>fruit picker returned <value expr="oResult.fruit"/></audio>
        <log>back in <value expr="calling_dialog"/></log>
        <exit />
      </filled>
   </subdialog>
   </form>

   <form id="fruit_picker">
      <var name="customer"/>

      <var name="aFruits" expr="new Array('apples', 'oranges', 'bananas', 'pears')"/>

      <block>
         <!-- 
         calling_dialog will evaluate to 'none' because the subdialog 
         doesn't share the execution context of the calling dialog
         -->
         <log>calling dialog is <value expr="calling_dialog"/></log>
      </block>

      <field name="fruit">
         
         <prompt>
         <audio>What kind of fruit would you like, <value expr="customer"/></audio>
         </prompt>
   
         <grammar type="application/x-gsl" mode="voice">
         <![CDATA[
         [
            [apple apples] {<fruit "apple">}
            [orange oranges] {<fruit "orange">}
            [banana bananas] {<fruit "banana">}
            [pear pears] {<fruit "pear">}
         ]
         ]]>
         </grammar>
   
         <catch event="noinput nomatch">
            <audio>Sorry <value expr="customer"/>.</audio>
            <audio>I don't think we have any of those available.</audio>
            <audio>Our limited selection includes the following:</audio>
            <foreach item="f" array="aFruits">
               <audio><value expr="f"/></audio>
            </foreach>
            <audio>Please pick one.</audio>
         </catch>
   
         <catch event="noinput">
            <audio>Sorry <value expr="customer"/>. I didn't hear you.</audio>
            <reprompt/>
         </catch>
   
         <catch event="noinput nomatch" count="2">
            <audio>Bailing.</audio>
            <return event="event.failed" />
         </catch>
   
         <filled>
            <log>Recognized <value expr="fruit"/></log>
            <return namelist="fruit"/>
         </filled>

      </field>
   </form>

</vxml>

VoiceXML

Document with form that calls a subdialog

Document containing the subdialog (generated by /cgi-bin/getlib)