catch
catch element
Handles events thrown by a VoiceXML application or the interpreter.
Syntax
<catch
cond = "ECMAScript_Expression"
count = "integer"
event = "event1 event2 ..."
/>
Attributes
cond |
A condition evaluated to determine if the catch element should handle the specified event. |
count |
Used by the VoiceXML interpreter in the event handler selection process, allowing the developer to handle multiple occurrences of the catch event in a unique manner. The default value is 1. |
event |
A space delimited list of one or more events to handle. |
Parents
catch, form, initial, menu, object, record, subdialog, transfer, vxml
Children
assign, audio, break, clear, data, disconnect, enumerate, exit, foreach, goto, if, log element, mark, prompt, reprompt, return, script, submit, throw, value, var
Remarks
The catch element defines a handler for user-defined or predefined system events. The element contains content to execute in response to the event.
Event names are matched by prefix, so a catch element defined to handle error.badfetch will handle error.badfetch.http.404, error.badfetch.http.500, error.badfetch.http.304, etc.
When writing a generic event handler, you can determine the name of the event by checking the _event variable. When defining custom events, use descriptive event names. For example, "error.tellmeu.password.retries.exceeded" is an event name that describes a user's inability to login to an application named "tellmeu." The event could be caught by a generic error event handler.
The variable _message is available within the scope of an event handler to allow access to additional information about the event specified when the event was thrown via the message attribute of the throw element or by the Platform. If a message was not specified, the value of _message is null.
Examples
The following examples use the catch element to catch normal system events - noinput and nomatch.
<?xml version="1.0"?>
<vxml version="2.1"
xmlns="http://www.w3.org/2001/vxml">
<form id="get_password">
<var name="tries" expr="0"/>
<field name="password">
<prompt>
What is the code word?
</prompt>
<grammar src="dow-voice.grxml" mode="voice" type="application/srgs+xml"/>
<grammar src="dow-dtmf.grxml" mode="dtmf" type="application/srgs+xml"/>
<help>It is a day of the week.</help>
<catch event="nomatch" count="1">
<reprompt/>
</catch>
<catch event="noinput" count="1">
<reprompt/>
</catch>
<catch event="noinput" count="2">
Sorry, I didn't hear you
<reprompt/>
</catch>
<catch event="noinput" count="3">
<disconnect />
</catch>
<filled>
<if cond="'tuesday' == password.toLowerCase()">
Access granted.
<exit />
</if>
<assign name="tries" expr="tries+1"/>
<if cond="tries >= 3">
You seem to be having trouble with your password.
<exit />
<else/>
<clear namelist="password"/>
</if>
</filled>
</field>
</form>
</vxml>
The following example demonstrates catching user-defined events. The _event variable is used to determine precisely which event was caught.
<?xml version="1.0"?>
<vxml version="2.1"
xmlns="http://www.w3.org/2001/vxml">
<!-- throw event.myapp.repeat when the user says "repeat" -->
<link event="event.myapp.repeat">
<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>
repeat
</item>
</one-of>
</rule>
</grammar>
</link>
<!-- throw event.myapp.quit when the user says "quit" -->
<link event="event.myapp.quit">
<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>
quit
</item>
</one-of>
</rule>
</grammar>
</link>
<!-- handle all user-defined application-specific events -->
<catch event="event.myapp">
<if cond="/quit$/.test(_event)">
<log>event.myapp.quit</log>
<exit />
<elseif cond="/repeat/.test(_event)"/>
<log>event.myapp.repeat</log>
<reprompt/>
<else/>
<log>Don't know how to handler event <value expr="_event"/></log>
</if>
</catch>
<form id="get_fruit">
<field name="fruit">
<prompt>
Pick a fruit, or say quit at any time.
</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>
</one-of>
<tag>out.fruit = "apple";</tag>
</item>
<item>
<one-of>
<item>
orange
</item>
</one-of>
<tag>out.fruit = "orange";</tag>
</item>
<item>
<one-of>
<item>
pear
</item>
</one-of>
<tag>out.fruit = "pear";</tag>
</item>
</one-of>
</rule>
</grammar>
<!-- catch both noinput and nomatch -->
<!-- but check _event and respond appropriately -->
<catch event="noinput nomatch">
<if cond="_event == 'noinput'">
I'm sorry. I didn't hear you.
<else/>
I'm sorry. I didn't get that.
</if>
Please say apple, orange, or pear.
</catch>
<filled>
You said <value expr="fruit"/>
<clear/>
</filled>
</field>
</form>
</vxml>