Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Throwing and Catching Events
Setting up an application context for a multidocument application is useful not only for defining global variables and grammars but also for setting up application-wide event handlers to deal with errors and user-defined events.
You’ve already seen basic event handling in action. When a user does not respond, asks for help, or doesn’t respond in a way an application understands, the interpreter responds with a platform-specific default, such as "I did not understand what you said."
Previous examples showed how a developer can override this default behavior by providing <noinput>, <help>, or <nomatch> elements at the field, form, document, or application level. Now let’s look under the hood a bit and see how these predefined elements are actually part of a built-in throw-catch event framework that underlies all Voice XML platforms.
Consider for example, the case of no response. If we provide a <noinput> element such as the following, the user will be alerted with "Hey, what’s up, cat got your tongue?":
<noinput>Hey, what’s up, cat got your tongue?</noinput>
But behind the scenes what’s happening is that the platform is throwing a noinput event that is being caught by our <noinput> element, which is actually a convenient shorthand for the following:
<catch event="noinput">Hey, what’s up, cat got your tongue?</catch>
Seeing it written this way reveals that Voice XML is event-based, much like programming frameworks such as java Swing.
By default, Voice XML—compliant platforms provide implicit catch handlers for the noinput, help, nomatch, cancel, exit, and error events. If handlers are provided by the developer, they override the defaults.
Table 1 summarizes the default system behavior of catch handlers for predefined system events. Where audio is specified, it will be platform dependent.
Table 1. Voice XML Default Catch Handlers
|
Vent Type |
Audio Provided |
Action |
|
cancel |
No |
No reprompt |
|
error |
Yes |
Exit interpreter |
|
exit |
No |
Exit interpreter |
|
help |
Yes |
Reprompt |
|
noinput |
No |
Reprompt |
|
nomatch |
Yes |
Reprompt |
|
maxspeechtimeout |
Yes |
Reprompt |
|
connection.disconnect |
No |
Exit interpreter |
Behind the scenes, the platform is throwing these predefined events and looking for catch handlers. In the case of noinput, the platform does the equivalent of the following:
<throw event="nomatch"/>
We as developers can take advantage of this and throw our own events, as in the following:
<throw event="com.zorkon.confusion"/>
And respond to the event using the following:
<catch event="com.zorkon.confusion> <prompt>Zorkon is sorry you are confused</prompt> </catch>
Listing 4 puts this all together.
Listing 4 Working with multiple catch handlers
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2001/vxml
http://www.w3.org/TR/voicexml20/vxml.xsd">
<catch event="nomatch noinput" count="5">
<prompt>Security violation! The f b i is being notified.</prompt>
</catch>
<form id="getData">
<catch event="nomatch noinput" count="4">
<prompt>You are now in big, big, trouble. </prompt>
</catch>
<field name="user_id" type="digits">
<prompt>What is your numeric user I D</prompt>
</field>
<field name="password">
<prompt>What is the code word?</prompt>
<grammar version="1.0" root="root">
<rule id="root" scope="public">bingo</rule>
</grammar>
<help>It is the name of a popular multi-player game.</help>
<catch event="nomatch noinput" count="3">
<prompt>Security violation! You are in big trouble.</prompt>
</catch>
</field>
</form></vxml>
The following sample dialog illustrates the triggering of the multiple catch handlers:
S: What is your numeric user I D U: 1224 S: What is the code word? U: sassafrass S: I did not understand what you said <default platform response> S: What is the code word? U: monkey S: I did not understand what you said <default platform response> S: What is the code word? U: zorro S: Security violation! You are in big trouble. <catch with count = 3> S: What is the code word? U: mellow yellow S: You are now in big, big, trouble. <catch with count = 4> S: What is the code word? U: haricot vert S: Security violation! The f b i is being notified. <catch with count = 5>
In the preceding dialogue, when a nomatch event is thrown, the scope in which the event is handled and its enclosing scopes are examined to find the best qualified catch element.
All catches in the current scope and all enclosing scopes (form item, form, document, application root document, interpreter context), are ordered first by scope (starting with the current scope), and then within each scope by document order. For catches with event names that match the event being thrown, the one with the matching count is selected.
When dealing with multiple events, it’s possible to write one catch handler by using the catch element’s special variable _event, which contains the name of the event that was thrown. For example, the following catch element handles two types of events:
<catch event="event.zorkon.foo event.zorkon.bar"> <if cond="_event==’event.zorkon.foo’"> <!-- Play event.zorkon.foo audio --> <audio src="foo.wav"/> <else/> <!-- Play event.zorkon.bar audio --> <audio src="bar.wav"/> </if> <!-- Continue with common handling for either event --> </catch>
Here, the _event variable is checked to select the audio to play based on the thrown event. The foo.wav file will be played for event.zorkon.foo events. The bar.wav file will be played for event.zorkon.bar events. The remainder of the catch element might also contain executable content that is common to both event types.
Additionally, the catch element’s anonymous variable scope also includes the special variable _message, which contains the value of the message string from the corresponding <throw> element. For example, if we throw with the following:
<throw event="com.zorkon.event.foo" message="strange input received"/>
We can retrieve the message text in a catch block using the following:
<catch event="com.zorkon.event.foo"> . . . <value expr="_message"> . . . </catch>