return
return element
Returns control and data or an event to the dialog that called the subdialog.
Syntax
<return
event = "string"
eventexpr = "ECMAScript_Expression"
message = "string"
messageexpr = "ECMAScript_Expression"
namelist = "var-1 var-2 ... var-n"
/>
Attributes
event |
The event to throw to the subdialog element on the top of the subdialog stack. |
eventexpr |
An ECMAScript expression that evaluates to an event name. This attribute is a Tellme extension. |
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. |
namelist |
A space-delimited list of variables returned to the calling dialog. |
Parents
block, catch, error, filled, foreach, help, if, noinput, nomatch, prompt
Children
None.
Remarks
If the event attribute is specified, the VoiceXML interpreter attempts to execute a matching event handlers contained within the subdialog in the calling dialog. If the namelist attribute is specified, the VoiceXML interpreter executes the filled element of the subdialog element in the calling dialog. Any variables listed in the namelist attribute are returned as properties of the object named by the name attribute of the subdialog element.
Currently, the Tellme platform does not support returning object properties or explicitly scoped variables. To return data contained in properties, copy the value into a local variable, and return the local variable.
The event and namelist attributes are mutually exclusive.
The message and messageexpr attributes are mutually exclusive.
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 calls a subdialog that requests a five-digit account number and a four-digit password from the user. The caller passes in a parameter indicating the maximum number of retries allowed before failing.
<?xml version="1.0"?>
<vxml version="2.1"
xmlns="http://www.w3.org/2001/vxml">
<var name="maxtries" expr="2"/>
<var name="uid"/>
<var name="pin"/>
<form id="main">
<subdialog name="oCredentials" src="login.vxml">
<!-- override the default max retries by passing in a parameter -->
<param name="maxtries" expr="document.maxtries"/>
<catch event="event.canceled">
<!-- user bailed -->
<exit />
</catch>
<catch event="event.invalid">
<!-- uid/password were invalid maxtries times -->
<exit />
</catch>
<filled>
<!-- credentials are valid. use them later -->
<assign name="uid" expr="oCredentials.uid"/>
<assign name="pin" expr="oCredentials.pin"/>
<goto next="#main_menu"/>
</filled>
</subdialog>
</form>
<!-- application-specific logic goes here -->
<form id="main_menu">
<block>
t b d main menu
<exit />
</block>
</form>
</vxml><?xml version="1.0"?>
The following example implements a login subdialog composed of three subdialogs. The first requests the account number, the second requests the password, and the third validates the account number and password. The validation is simulated. Replace it with a server-side script that looks up the user's account number and password in database.
<?xml version="1.0"?>
<vxml version="2.1"
xmlns="http://www.w3.org/2001/vxml">
<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>
<var name="tries" expr="0"/> <!-- # attempts -->
<var name="maxtries" expr="3"/> <!-- # default max attempts -->
<var name="uid"/>
<var name="pin"/>
<form id="init">
<var name="maxtries"/> <!-- caller can override max attempts -->
<block>
<if cond="maxtries != null && 'number' == typeof(maxtries)">
<log>overriding default maxtries
<value expr="document.maxtries"/>
with <value expr="maxtries"/></log>
<assign name="document.maxtries" expr="maxtries"/>
</if>
<goto next="#login"/>
</block>
</form>
<form id="login">
<block>
<!-- increment attempt counter -->
<assign name="tries" expr="tries+1"/>
<log>tries=<value expr="tries"/>,
maxtries=<value expr="maxtries"/></log>
</block>
<subdialog name="oRes1" src="#get_uid">
<catch event="event.canceled">
<return event="event.canceled"/>
</catch>
<filled>
<assign name="uid" expr="oRes1.uid"/>
</filled>
</subdialog>
<subdialog name="oRes2" src="#get_pin">
<catch event="event.canceled">
<return event="event.canceled"/>
</catch>
<filled>
<assign name="pin" expr="oRes2.pin"/>
</filled>
</subdialog>
<!--
The following subdialog fakes credential checking by asking the user
if their user id and password is valid.
A *real* validator would subdialog to a server-side script via https,
passing the uid pin variables via the namelist.
The server script would return a simple VoiceXML document containing
a return with event "event.valid" or "event.invalid"
depending upon whether the uid/password were valid.
For example,
<subdialog src="https://www.mycompany.com/myapp/credentials.cgi"
method="post" namelist="uid pin">
* appropriate event-catching logic goes here
as shown in #fake_check_credentials *
</subdialog>
-->
<subdialog src="#fake_check_credentials">
<param name="uid" expr="document.uid"/>
<param name="pin" expr="document.pin"/>
<catch event="event.valid">
<return namelist="uid pin"/>
</catch>
<catch event="event.invalid">
Sorry. Your account number and password don't match.
<log>in check invalid catch: tries=<value expr="tries"/>,
maxtries=<value expr="maxtries"/></log>
<if cond="tries >= maxtries">
<return event="event.invalid"/>
<else/>
<clear namelist="uid pin"/>
Let's try again
<goto next="#login"/>
</if>
</catch>
</subdialog>
</form>
<!-- fake credential validation -->
<form id="fake_check_credentials">
<var name="uid"/>
<var name="pin"/>
<block>
Pretend you're a validating credentials server.
validating <value expr="uid"/> and <value expr="pin"/>.
</block>
<field type="boolean" name="yesno">
<prompt>Let yourself in? Say no to test retry counter.
Say yes to test valid case.</prompt>
<catch event="noinput nomatch">
<reprompt/>
</catch>
<filled>
<if cond="yesno">
<return event="event.valid"/>
<else/>
<return event="event.invalid"/>
</if>
</filled>
</field>
</form>
<!-- collect the user's account number -->
<form id="get_uid">
<link event="event.oncancel">
<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">
cancel
</item>
</one-of>
</rule>
</grammar>
</link>
<catch event="event.oncancel">
<return event="event.canceled"/>
</catch>
<field name="uid">
<prompt>
Account number?
</prompt>