<catch>
Catches an event.
Syntax
<catch
event="event1 ..."
count="integer"
cond="js_expression"
>
Executable Content
</catch>
Description
Container for event handling code. Like <block>, you can put non-interactive executable code (procedural logic) in a <catch> element to handle an event.
| Attribute |
Description |
event
|
Name of the event(s) to catch. Optional.
New in VoiceXML 2.0. You can catch all events by omitting this attribute.
|
count
|
Minimum number of times the event must have occurred during a form or menu invocation. Lets you handle different occurrences of the same event differently. Optional (default is 1).
|
cond
|
JavaScript boolean expression that must also evaluate to true for an event to be caught. Optional (default is true).
|
Although you can define your own events, there is a set of predefined events. The VoiceXML interpreter provides a standard set of default event handlers for the predefined events.
If multiple handlers for a given event are defined in, or inherited by, the element in which the event occurs, one handler is chosen based on count, scope, and document order. See Chapter 3, Event Handling.
|
|
Tips:
|
| • | Because you can throw events from within a <catch>, be sure to avoid infinite loops. For example, the following handler would result in an infinite loop: |
<catch event="foobar">
<throw event="foobar"/>
</catch>
|
|
| • | You can use a <submit> within a <catch> for a hang up event to notify the server that the call has ended (connection.disconnect.hangup in VoiceXML 2.0; telephone.disconnect.hangup in VoiceXML 1.0). Because the call is no longer connected, any VoiceXML document returned from the server will be ignored and the interpreter will exit. Similarly, if you use a <goto> within a <catch> for this event, it will be ignored and the interpreter will exit. |
|
|
| • | Within an event handler, the _event variable contains the name of the event currently being handled; the _message variable contains the message string that provides additional information about the event. If no message was supplied when the event was thrown, the _message variable is undefined. |
|
|
| • | The method by which event handlers are inherited from ancestor elements is called as if by copy semantics in the VoiceXML 2.0 specification. It helps to think of appropriate event-handler literally being copied into the scope of where the event was thrown. So variable references are resolved relative to the scope of the element where the event was thrown, and URL references are resolved relative to the document from which the event was thrown. For example, if you have a <catch> handler in an application root document, which is in a different directory as the main document which threw the event, URLs in the handler will be resolved to the directory of the main document. The change to URL resolution to the originating document is considered 2.0 behavior and applies only when the <vxml> tag's version attribute is set to "2.0" or greater. |
|
|
| • | In a VoiceXML 2.0 document, <catch> with an empty event attribute (<catch event="">) is no longer allowed. To catch all events use <catch> or <catch event=".">. If the version is set to 1.0 the empty event attribute can catch all events; however it is suggested you to use the new <catch> syntax since it works in both versions of the interpreter. |
|
|
| • | 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
See other catch and throw examples under <throw> and <rethrow>.
<?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">
<property name="universals" value="help" />
<form id="stars">
<catch event="nomatch">
<prompt>
Sorry, I did not hear a number more than ten.
</prompt>
<reprompt/>
</catch>
<block name="numbergame">
You can create games with numbers by using JavaScript
</block>
<field name="mynumber" type="number">
<prompt>
Tell me a number and I can repeat it for you.
You can say help for information.
</prompt>
<catch event="help">
<prompt>
Please say a number more than 10 and less than infinity.
</prompt>
</catch>
<filled>
<if cond="mynumber > 10">
<prompt>
The number you said is <value expr="mynumber"/>
</prompt>
<else/>
<clear namelist="mynumber"/>
<throw event="nomatch"/>
</if>
</filled>
</field>
</form>
</vxml>
[Show Frames] [FIRST] [PREVIOUS] [NEXT]
