subdialog
subdialog element
Jumps to and executes an encapsulated dialog.
Syntax
<subdialog
cond = "ECMAScript_Expression"
enctype = "encoding_type"
expr = "ECMAScript_Expression"
fetchaudio = "URI"
fetchaudioexpr = "ECMAScript_Expression"
fetchhint = "string"
fetchtimeout = "string"
maxage = "seconds"
maxstale = "seconds"
method = "string"
name = "string"
namelist = "string"
src = "URI"
srcexpr = "ECMAScript_Expression"
/>
Attributes
cond |
An ECMAScript expression that evaluates to true or false.
FalseThe element is not executed.
TrueThe element is executed.
|
enctype |
The MIME encoding type of the submitted data. To specify the following encodings, you must set the value of the method attribute to "POST", and you must use the namelist attribute to specify the variables to be submitted.
application/x-www-form-urlencodedThe data is submitted using the encoding described in Section 2.2 of RFC 1738. This results in name/value pairs sent to the server as name1=value1&name2=value2... with space characters replaced by "+" and reserved characters (like "#") replaced by "%HH" where HH is the ASCII code of the character in hexadecimal. Line breaks are encoded as "%0D%0A" - a carriage return followed by a line feed.
multipart/form-dataThe data is submitted using the encoding described in RFC 2388. The encoding provides an efficient means for sending large quantities of binary data or text containing non-ASCII characters. When submitting a variable that references recorded audio, the enctype is automatically set to "multipart/form-data".
|
expr |
An ECMAScript expression that supplies the initial value for the form item variable associated with this element. If the expression evaluates to something other than null or ECMAScript undefined, the element will not be visited until the form item variable is explicitly cleared. |
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 effect 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-Controlheader 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. |
method |
The HTTP method used to send the request.
GETThe request is submitted using the GET method.
POSTThe request is submitted using the POST method.
|
name |
The name of the ECMAScript object that holds the value(s) returned from the subdialog. |
namelist |
A space-separated list of variables to be submitted via HTTP to the specified document. |
src |
The URI of the document (or anchor within the current document) containing the subdialog. |
srcexpr |
An ECMAScript expression that evaluates to the URI containing the subdialog. |
Parents
Children
audio, catch, enumerate, error, filled, help, noinput, nomatch, param, prompt, property, value
Remarks
The subdialog element allows you to call a self-contained VoiceXML dialog. In addition to passing parameters to the called dialog via param elements, the called dialog can return values to the caller via the return element. Whether or not you return data from a subdialog, you should always include the return element in the dialog called by the subdialog element to properly return to the execution context of the caller.
Just before the subdialog is executed the VoiceXML interpreter suspends the execution context of the caller including all event handlers, grammars, links, scripts, and variables in any scope (dialog, document, application). The VoiceXML interpreter creates a new execution context for the subdialog while it executes. This context is destroyed when the subdialog returns. To share data between the caller and the subdialog, use the param and return elements.
The namelist, method, and enctype attributes are only relevant if the subdialog element navigates to a server-side script (e.g. CGI).
You typically place a subdialog in a separate VoiceXML document that does not reference the application root document of the application containing the calling dialog. If you were to reference the application root from the document containing the subdialog, all variables in the application root are reinitialized each time the subdialog is called.
The src and srcexpr 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 subdialog element, then the value of the fetchtimeout, documentfetchhint, documentmaxage, or documentmaxstale property, respectively, is used.
Prior to Revision 3, the interpreter ignores any undeclared variables in the namelist attribute. In Revision 3 and later, the interpreter throws error.semantic if any of the variables is undeclared.
Examples
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.1"
xmlns="http://www.w3.org/2001/vxml">
<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">
fruit picker failed
</catch>
<filled>
fruit picker returned <value expr="oResult.fruit"/>
<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>
What kind of fruit would you like, <value expr="customer"/>
</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>
<item>
apples
</item>
</one-of>
<tag>out.fruit = "apple";</tag>
</item>
<item>
<one-of>
<item>
orange
</item>
<item>
oranges
</item>
</one-of>
<tag>out.fruit = "orange";</tag>
</item>
<item>
<one-of>
<item>
banana
</item>
<item>
bananas
</item>
</one-of>
<tag>out.fruit = "banana";</tag>
</item>
<item>
<one-of>
<item>
pear
</item>
<item>
pears
</item>
</one-of>
<tag>out.fruit = "pear";</tag>
</item>
</one-of>
</rule>
</grammar>
<catch event="noinput nomatch">
Sorry <value expr="customer"/>.
I don't think we have any of those available.
Our limited selection includes the following:
<foreach item="f" array="aFruits">
<value expr="f"/>
</foreach>
Please pick one.
</catch>
<catch event="noinput">
Sorry <value expr="customer"/>. I didn't hear you.
<reprompt/>
</catch>
<catch event="noinput nomatch" count="2">
Bailing.
<return event="event.failed" />
</catch>
<filled>
<log>Recognized <value expr="fruit"/></log>
<return namelist="fruit"/>
</filled>
</field>
</form>
</vxml>