throw

throw element

Generates a system or user-defined event to catch with an event handler.

Syntax

<throw
event = "event"
eventexpr = "ECMAScript_Expression"
message = "string"
messageexpr = "ECMAScript_Expression"
/>

Attributes

Parents

block, catch, error, filled, foreach, help, if, noinput, nomatch, prompt

Children

None.

Remarks

The throw element generates a system or user-defined event to be caught by an event handler (see catch). When you throw an event, the VoiceXML interpreter looks for the corresponding event handler within that element. An element inherits event handlers from higher elements, so if the particular event handler isn't found, the VoiceXML interpreter looks for it within the containing dialog (see form), vxml, and application root document.

The event and eventexpr attributes are mutually exclusive.

The message and messageexpr attributes are mutually exclusive.

Examples

The following example demonstrates throwing a user-defined event, event.password.invalid, and catching it at document scope.

<?xml version="1.0"?>
<vxml version="2.1"
 xmlns="http://www.w3.org/2001/vxml">

<var name="iMaxTries" expr="3"/> <!-- max allowed password tries -->

<form id="get_password">
   <var name="iTries" expr="0"/>
   <var name="hint" expr="'It is a day of the week.'"/>
   <var name="fatal" 
      expr="'We are having technical difficulties validating your credentials. Try back later.'"/>

 <catch event="event.password.invalid">
   <!-- increment the attempt counter; if the count is exceeded, disconnect -->
   <assign name="iTries" expr="iTries+1"/>
   <if cond="iMaxTries == iTries">
     <value expr="fatal"/>
     <disconnect/>
   <else/>
      <!-- 
        clear is unnecessary on a nomatch, 
        but we use the same code to handle a bad filled
      -->
      <clear namelist="password"/>
      <reprompt/>
   </if>
 </catch>

 <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><value expr="hint"/></help>

   <!-- exec this on the first and second noinput/nomatch -->
   <!-- each event has its own counter -->
   <catch event="noinput">
     I'm sorry. I didn't hear you.
     <reprompt />
   </catch>

   <!-- exec this on the third nomatch -->
   <catch event="nomatch">
      <throw event="event.password.invalid"/>
   </catch>

   <!-- silently disconnect on the third noinput -->
   <catch event="noinput" count="3">
      <disconnect/>
   </catch>

   <filled>
   <if cond="'tuesday' == password">
       <value expr="password"/> is correct!
       <goto next="#access_granted"/>
   <else/>
       <throw event="event.password.invalid"/>
   </if>
   </filled>
   
 </field>
  </form>

  <form id="access_granted">
  <block>
       <!-- we go home here; a *real* app would proceed via goto or submit -->
       <exit />     
  </block>
  </form>
</vxml>

The following example demonstrates the use of the message attribute, and the corresponding _message variable.

<?xml version="1.0"?>
<vxml version="2.1"
 xmlns="http://www.w3.org/2001/vxml">

<catch event="com.mycomp.myapp.event1">
  <log><value expr="_event"/> : <value expr="_message"/></log>
  <goto next="#form2"/>
</catch>

<catch event="com.mycomp.myapp">
  <log><value expr="_event"/> : <value expr="_message"/></log>
  <exit />
</catch>

<form id="form1">
   <block>
      <throw event="com.mycomp.myapp.event1"
         message="form1" />
   </block>
</form>

<form id="form2">
   <block>
      <throw event="com.mycomp.myapp.event2"
         messageexpr="'form2 : ' + new Date()" />
   </block>
</form>

</vxml>