<subdialog>

Allows you to invoke a subdialog within the main dialog. When you invoke a subdialog, the subdialog executes until it encounters a <return> element. When a <return> element is encountered, execution of the subdialog terminates and control is returned to the main dialog.

Specifying a <param> element within a <subdialog> element allows you to pass parameter values to a subdialog. It is important to understand that you must specify a <var> element to declare each parameter within the target form of your subdialog.

Note: A semantic error will be generated if you use the <param> element to set a form item variable or an undeclared variable in a target form. Additionally, a <var> element that contains an expr attribute in its target form overwrites the value of the parameter that was passed to the form.

Attributes

This section describes the attributes you can set for this element.

Attribute name	Data type	Default
cond	CDATA	optional
enctype	CDATA	application/ x-www-form-urlencoded
expr	CDATA	optional
fetchaudio	CDATA	optional
fetchhint	(prefetch | safe)	optional
fetchtimeout	CDATA	optional
httpheaderlist	ECMAScript expression	optional
maxage	CDATA	optional
maxstale	CDATA	optional
method	(GET | POST)	GET
name	NMTOKEN	optional
namelist	CDATA	optional
src	CDATA	optional
srcexpr	CDATA	optional

enctype

The enctype attribute specifies the MIME-type encoding for a submitted document. The values you can set for this attribute are:

• application/x-www-form-urlencoded (default)—Data is submitted as specified in the HTML 4.01 Specification. Since this encoding can triple the size of data being submitted and is inefficient in performing encoding on binary data, it is not recommended for binary data such as recordings. Nuance recommends using the multipart/form-data encoding instead.
• multi-part/form-data—Data is submitted as a multipart MIME document (as defined in RFC 2388). Note that each key has its own part, including separate headers. Nuance recommends using this encoding when submitting binary data such as recordings. 

application/octet-stream—Data is submitted as a direct stream of values. Note that keys are not submitted. You can use this encoding to submit a single recording to a file URL, which effectively saves the recording to the specified file. Note that it is possible to separate values on the remote side when submitting multiple items.

fetchaudio

The fetchaudio attribute specifies the URI of the audio file to play while waiting for a document to be fetched. If you do not specify a setting for the fetchaudio attribute, the <property> element defines a value for the fetchaudio property. If the fetchaudio property is not set (default), no audio is played during a fetch.

fetchhint

The fetchhint attribute determines when content is retrieved from the server. The settings for the fetchhint attribute are prefetch and safe. The prefetch setting indicates that files or dialogs are downloaded when a page is loaded. The safe setting indicates that files or dialogs are downloaded only when they are actually needed.

If you do not specify a setting for the fetchhint attribute, the <property> element determines the setting by defining a value for the appropriate *fetchhint property, for example:

<property name="documentfetchhint" value="safe"/>

fetchtimeout

The fetchtimeout attribute specifies the amount of time to wait for the content to be fetched before throwing an error.badfetch event.

The value may be specified in seconds (s) or milliseconds (ms). If no unit is specified, the value is interpreted as milliseconds by default. If no value is specified, the fetchtimeout defaults to the value set an applicable <property> element, or to the value set for the browser.loading.fetchtimeout property in the Management Station if no <property> applies. If no other default applies, the platform default of 10000 milliseconds is used.

httpheaderlist

The httpheaderlist attribute enables sending custom values in HTTP headers. It specifies an ECMAScript expression that evaluates to an array of headername, headervalue pairs.

Use this mechanism to customize HTTP requests submitted to servers by the Voice Browser service on behalf of VoiceXML applications. It sends runtime information so servers can understand the context of requests and format appropriate responses. Your VoiceXML application (or the voice application server itself) can insert custom values for any purpose. This example assigns httpheaderlist to someHeaders:

var someHeaders = [

     {headername: "Content-Type", headervalue: "text/html; charset=UTF-8"},

     {headername: "custom-hrd1",  headervalue: "custom-value1"}

     ];

One use of custom headers is to identify the current state of the call and enable the VoiceXML application to initiate a relevant action. Another use is to integrate a web server that provides data to the VoiceXML application: for example, to pass information to a server that validates credit cards.

Note: Use this attribute cautiously, and test thoroughly. Do not specify confidential data in the headers unless protected via TLS. In addition, your tests should ensure the server can respond to the custom values. It's best to create new, custom header/value pairs and avoid setting any standard pairs (because the values you specify will override tested defaults).

You must specify headers as an array of header/value pairs. This example creates two custom headers and values and uses httpheaderlist to insert them into a request:

<script><![CDATA[

     function GetHeaders()      {

     var myHeaders = [

          {headername: "CustomHdr1",  headervalue: "Hdr1Value"},

          {headername: "CustomHdr2",  headervalue: "Hdr2Value1 , Hdr2Value2"},

          {headername: "Content-Type", headervalue: "text/html; charset=UTF-8"},

          ];

     return myHeaders;      }

     ]]></script>

     .....

     <form id="get_quote">

          <block>

               <subdialog name="quote" srcexpr="'http://myserver/account.html"

                    httpheaderlist="GetHeaders()"/>

               <assign name="document.quote" expr="quote.documentElement"/>

               ......

          </block>

     </form>

     ......

maxage

The maxage attribute specifies the maximum amount of time a fetched resource may remain in the locale cache without requiring a server revalidation. If a value for the maxage attribute is not specified, revalidation will occur after the expiration of the freshness lifetime (as defined in RFC 2616).

maxstale

The maxstale attribute specifies the maximum amount of time a stale file remains valid before a refetch is required. If a value for the maxstale attribute is not specified, the stale document is refetched.

method

The method attribute allows you to specify a GET or POST method for an HTTP request. The default method for an HTTP request is GET.

namelist

The namelist attribute specifies the list of variables that are submitted in a query string or a request body.

src

The src attribute specifies the URI of the subdialog.

Note: Only one of the src or srcexpr attributes may be specified.

srcexpr

The srcexpr attribute is an ECMAScript expression that specifies the URI of the subdialog.

Note: Only one of the srcexpr or src attributes may be specified.

Form item attributes

Being a form item, the <subdialog> element also supports the common form items described in this section.

cond

The cond attribute specifies a Boolean expression. This Boolean expression must evaluate to true before the form item is available for selection within the Form Interpretation Algorithm (FIA).

expr

The expr attribute specifies the initial value of the form item variable. The default value of the expr attribute is undefined. If you set the expr attribute to a value other than the default, you will need to clear this value before the content of the form item element can be executed.

name

The name attribute specifies the name of the form item's guard variable. The Form Interpretation Algorithm (FIA) initializes this variable with the value specified by the expr attribute. If the form item comes up for selection at a later time, it will be populated by the pre-defined type for that element.

Note: The resulting value is returned by the namelist attribute of the called dialog. These values can be accessed as properties off the guard variable. For example, if the <return> element specifies namelist="foo bar" and the <subdialog> element specifies name="sub", then you can access the results of the called dialog using "sub.foo" and "sub.bar". 

Children

• Parsed character data
• <audio>
• <catch>
• <enumerate>
• <error>
• <filled>
• <help>
• <noinput>
• <nomatch>
• <param>
• <prompt>
• <property>
• <value>

Parents

• <form>

Sample code

The example below refers to the “getdriverslicense” subdialog, which is defined within the same document.

<form>

    <subdialog name="result" src="#getdriverslicense">

        <param name="birthday" expr="'2000-02-10'"/>

        <filled>

            <submit next="http://myservice.example.com/cgi-bin/process"/>

        </filled>

    </subdialog>

</form>