<subdialog>
Invokes another dialog as a subdialog of the current one.
Syntax
<subdialog
name="string"
expr="js_expression"
cond="js_expression"
src="URI"
srcexpr="js_expression"
method="get"|"post"
enctype=MIME_type
namelist="variable1 ..."
fetchhint="prefetch"|"safe"
fetchtimeout="time_interval"
fetchaudio="URI"
maxage="time_interval"
maxstale="time_interval"
>
Child Elements
</subdialog>
Description
Input item that invokes a subdialog, which is a reusable dialog that is specially coded to pass back values with a <return> element. When control returns from the subdialog, the returned values are available as properties of the <subdialog> input variable.
You pass values into the subdialog by including <param> child elements. The subdialog must contain a <var> declaration for each parameter passed to it. If the <var> contains an initializing expr attribute, that initializing value is ignored and the value passed with the <param> element is used instead.
When a subdialog is invoked, it runs in a new execution context. This means that all variables and state information in the subdialog's document are reinitialized (including the application root document, if one is used). Any changes that the subdialog makes to application-scoped variables apply only in the subdialog context. When the subdialog returns, its context is destroyed and the context of the calling dialog is in the same state it was in before the subdialog call. The only way for the subdialog to return information to its calling dialog is with a <return> element.
If the subdialog invokes other dialogs, those dialogs are also run in the new execution context. The new context terminates and the old context resumes only when the subdialog or another dialog it has invoked calls <return> to pass back the results.
Note: As a BeVocal extension, the BeVocal VXML Interpreter treats <subdialog> as executable content. This allows a subdialog to be invoked from within any tag which allows executable content, such as a <block> form item.
If the <subdialog> is inside of a <form> element, then upon return, execution proceeds to any applicable <filled> elements in the calling context. If you use subdialog in an executable context, such as within an <if> element, the <filled> element does not work. Instead, you should use <assign> directly after the subdialog call.
| Attribute |
Description |
name
|
Name of the input variable used to store the results of the subdialog.
The input variable has dialog (form) scope; its name must be unique among all VoiceXML and JavaScript variables within the form's scope.
You can access the return values as properties of the input variable using the syntax:
name.returnVariableName
|
expr
|
JavaScript expression that assigns the initial value of the input variable. Optional (default is undefined).
If you set the input variable to a value other than undefined, you'll need to clear it before the <subdialog> can execute.
|
cond
|
JavaScript boolean expression that also must evaluate to true for the <subdialog> to execute. Optional (default is true).
If not specified, the value of the input variable alone determines whether or not the <subdialog> can execute.
|
src
|
URI of the subdialog.
You can use the #DialogName syntax to refer to another dialog in the current document. Even in this case, the subdialog is run in a new context.
Note that the method, enctype, namelist, caching, fetchtimeout, and fetchaudio parameters apply only if src points to a different document (as opposed to starting with "#" to invoke a subdialog in the current document).
|
srcexpr
|
A JavaScript expression yielding the URI of the subdialog
|
method
|
The query request method, either get or post. Optional (default is get).
|
enctype
|
MIME encoding of the submitted document. Optional (default is application/x-www-form-urlencoded).
The supported types are:
| • | application/x-www-form-urlencode |
| • | multipart/form-data |
The type multipart/form-data is more efficient when submitting large amounts of binary data.
|
namelist
|
Space-separated list of variables to submit. Optional (default is to submit nothing).
This attribute can specify any variable currently in scope, both VoiceXML variables and JavaScript variables, including shadow variables and other variables that have not been explicitly declared.
A variable set to a JavaScript object is submitted as the individual component values; see Submitting Complex JavaScript Objects.
|
fetchhint
|
Specifies whether the interpreter can attempt to optimize dialog interpretation by prefetching the resource. See Prefetching Resources. Optional.
|
fetchtimeout
|
Specifies the interval to wait for the resource to be returned before throwing a error.badfetch event. See Handling Fetching Delays. Optional.
|
fetchaudio
|
Specifies the URI of background audio to be played during fetching. Note that this attribute and related properties affect whether queued prompts are played first. See Background Audio for important details. Optional.
|
maxage
|
New in VoiceXML 2.0. Specifies the maximum acceptable age, in seconds, of the cached resource. See Maximum Age. Optional.
|
maxstale
|
New in VoiceXML 2.0. Specifies the maximum acceptable time, in seconds, during which an expired cached resource can still be used. See Maximum Stale Time. Optional.
|
(VoiceXML 1.0 only) The following attributes can be used in applications in which the version attribute of the <vxml> tag is set to 1.0.
| Attribute |
Description |
caching
|
VoiceXML 1.0 only. Specifies the caching policy for the resource being fetched. See Caching. Optional.
Used in place of the VoiceXML 2.0 attributes maxage and maxstale.
|
modal
|
VoiceXML 1.0 only. Boolean value that must be false to enable <link> grammars from the calling context. Optional (default is true).
Lets you alter default behavior so that <link> grammars from the calling context can be active while the subdialog executes.
Note: In VoiceXML 2.0, all subdialogs are modal. To ensure portability, your VoiceXML applications should avoid using this attribute.
|
By default, no grammars from the calling dialog's context are active, except any default grammars defined by the VoiceXML interpreter. However, if the modal attribute is false, <link> elements in the calling dialog's context are active. When a grammar from the calling context is triggered during execution of a subdialog, the subdialog context terminates and control returns to the calling context.
If an event is thrown during execution of a subdialog and no event handler for the event is found in the subdialog context, the interpreter's response depends on whether the subdialog is modal.
| • | If the subdialog is modal, a fatal error occurs, causing the interpreter to exit. |
| • | If the subdialog is non-modal, the interpreter causes the subdialog's context to return. It then rethrows the event in the calling context and starts its search for the event handler in that context. |
|
|
Tip:
|
| • | If a JavaScript expression contains any of the characters "<", ">", or "&", that character must be replaced with the corresponding escape sequence "<", ">", or "&". For more information, see JavaScript Quick Reference. |
|
Usage
See Also
Examples
<?xml version="1.0" ?>
<!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
"http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
<form id="main">
<block>We're about to call the sub dialog</block>
<subdialog name="result" src="#subbie">
<param name="hello" value="goodbye"/>
<param name="goodbye" value="goodbye"/>
</subdialog>
<block>
We're back from the sub dialog.
Result dot hello equals <value expr="result.hello"/>
Result dot goodbye equals <value expr="result.goodbye"/>
</block>
</form>
<form id="subbie"> <!-- This is the subdialog -->
<!-- Variables are given values by parameters to the subdialog -->
<var name="hello" expr="'hello'"/> <!-- This initial value is ignored -->
<var name="goodbye"/>
<block>
This is the sub dialog.
hello equals <value expr="hello"/>
goodbye equals <value expr="goodbye"/>
<return namelist="hello goodbye"/>
</block>
</form>
</vxml>
[Show Frames] [FIRST] [PREVIOUS] [NEXT]
