VoiceXML

 

Variables and Expressions Page 3 of 7

 

VoiceXML variables are in all respects equivalent to ECMAScript variables. The variable naming convention is as in ECMAScript, but names beginning with the underscore character (“_”) are reserved for internal use.

Declaring Variables

Variables are declared by <var> elements:

<var name="home_phone"/> 
<var name="pi" expr="3.14159"/> 
<var name="city" expr="'Hayward'"/> 

They are also declared by form items:

<field name="num_tickets" type="number"> 
   <prompt>How many tickets do you wish to purchase?</prompt> 
</field> 

Variables declared without an explicit initial value are initialized to the ECMAScript undefined value. Variables must be declared before being used.

In a form, the variables declared by <var> and those declared by form items are initialized when the form is entered. The initializations are guaranteed to take place in document order, so that this, for example, is legal:

<form id="test"> 
   <var name="one" expr="1"/> 
   <field name="two" expr="one+1" type="number"></field> 
   <var name="three" expr="two+1"/> 
   <field name="go_on" type="boolean"> 
     <prompt>Say yes or no to continue</prompt> 
   </field> 
   <filled> 
       <goto next="#tally"/> 
   </filled> 
</form> 

When the user visits this <form>, the form’s initialization first declares the variable one and sets its value to 1. Then it declares the field item variable two and gives it the value 2. Then the initialization logic declares the variable three and gives it the value 3. The form interpretation algorithm then enters its main interpretation loop and begins at the go_on field.

Variable Scopes

Variables can be declared in following scopes:

session These are read-only variables that pertain to an entire user session. They are declared and set by the interpreter context. New session variables cannot be declared by VoiceXML documents.
application These are declared with <var> elements that are children of the application root document's <vxml> element. They are initialized when the application root document is loaded. They exist while the application root document is loaded, and are visible to the root document and any other loaded application leaf document.
document These variables are declared with <var> elements that are children of the document’s <vxml> element. They are initialized when the document is loaded. They exist while the document is loaded, and are visible only within that document.
dialog Each dialog (<form> or <menu>) has a dialog scope that exists while the user is visiting that dialog, and which is visible to the element of that dialog. Dialog variables are declared by <var> child elements of <form>, by <var> elements inside executable content (e.g. <block> content or catch element content), and by the various form item elements. The child <var> elements of <form> are initialized when the form is first visited. The <var> elements inside executable content are initialized when the executable content is executed. The form item variables are initialized when the form item is collected.
(anonymous) Each <block>, <filled>, and catch element defines a new anonymous scope to contain variables declared in that element.

The following diagram shows the scope hierarchy:


Figure 8: The scope hierarchy.

The curved arrows in this diagram show that each scope contains a variable whose name is the same as the scope that refers to the scope itself. This allows you for example in the anonymous, dialog, and document scopes to refer to a variable Xin the document scope using document.X.

Referencing Variable

Variables are referenced in cond and expr attributes:

<if cond="city == 'LA'"> 
   <assign name="city" expr="'Los Angeles'"/> 
<elseif cond="city == 'Philly'"/> 
   <assign name="city" expr="'Philadelphia'"/> 
<elseif cond="city =='Constantinople'"/> 
   <assign name="city" expr="'Istanbul'"/> 
</if> 

<assign name="var1" expr="var1 + 1"/> 

<if cond="i > 1"> 
   <assign name="i" expr="i-1"/> 
</if> 

The expression language used in cond and expr is precisely ECMAScript. Note that the condoperators “>”, “<”, “>=”, “<=”, and “&&” must be escaped in XML (to “&gt;” and “&lt;” and so on). For clarity, examples in this document do not use XML escapes.

Variable references match the closest enclosing scope according to the scope chain given above. You can prefix a reference with a scope name for clarity or to resolve ambiguity. For instance to save the value of a form field item variable for use later on in a document:

<assign name="document.ssn" expr="dialog.ssn"/> 

If the application root document has a variable x, it is referred to as application.x in non-root documents, and either application.x or document.x in the application root document.