Root Documents
Passing Variables
Root documents can be used to pass variables from one VoiceXML page to another VoiceXML page. Root documents are specified per VoiceXML script and are themselves a VoiceXML script. Any variables defined in the root document will be carried between all your documents. Any assignments to those variables in a given script are preserved so long as the next document that gets transitioned to also includes the same root document.
Root documents are specified using the “application” attribute of the VoiceXML tag. The following example uses three VoiceXML files (1 root document and 2 child documents that use the root document):
From this example, Page1.vxml accesses the variable “foo” from the root document Root.vxml, assigns it the value, “bar”, and transitions to Page2.vxml. Once inside of Page2.vxml, the root document is referenced again, which allows Page2.vxml to use the variable “foo”. Since the root document preserves the assignment of the variable from Page1.vxml, Page2.vxml returns a prompt of “The value foo is set to bar.”
Global Catch Handlers
You can also use the root document to set global catch handlers and global default properties for your application. Suppose you want your entire application to allow the user to have 3 seconds in between their entering of data. It would be tedious to enter this code in your application at every point the user enters data. Also, if you had a generic message for when the user enters no input or incorrect data, you could set up your “noinput” and “nomatch” catch handlers globally in your root document. The following example demonstrates this point:
From this example, the root document Root.vxml sets a global default property for “interdigittimeout” to be 3 seconds long. This means that if there are no properties set locally within your application for “interdigittimeout”, the “interdigittimeout” for the user to input digits would be 3 seconds. The root document also sets up global catch handlers for “noinput” and “nomatch” events for your application. This means that if there are no error handlers set for “noinput” and “nomatch” locally, the application would use the “noinput” and “nomatch” catch handlers set in your root document. 2 global variables, “username” and “age”, are set up for this example as well.
When the application starts at Page1.vxml, “username” is assigned the value of string “Big Dog”. The user is then prompted for an age to be inputted. Since there is no property set for “interdigittimeout” within Page1.vxml, the application uses the “interdigittimeout” property from the root document. This means that the user has 3 seconds between the input of each digit before the application begins to process the digits that were entered. Also, if the user does not enter any digits, the application uses the “noinput” catch handler from the root document since there is no error handler set for “noinput” within Page1.vxml. Let's assume you enter “12” for your age. Finally, the application transitions to Page2.vxml, which returns a prompt of “Your name is Big Dog. Your age is 12.” Thus, if you have multiple VoiceXML scripts linked together, you can use a root document to store global variables, properties, or catch handlers that would be used by these VoiceXML scripts.
Leaf to Root Transitioning
Instead of transitioning from root to leaf documents, you can also transition from a leaf document back to the root document. For example:
From this example, when the application, Page1.vxml, is started, it accesses the variable, “foo”, from the root document, root.vxml, and assigns it the value of string, “bar”. Page1.vxml then transtions to Page2.vxml, which creates a new variable, “leaf”, and assigns it the value of string, “rab”. Page2.vxml then returns the prompt, “The value of foo is set to bar.” After the prompt, Page2.vxml transitions to the root document, root.vxml, which references the variable, “leaf”, from Page2.vxml and returns the prompt, “The value leaf is set to rab.” Thus, it is possible for root documents to reference variables from leaf documents as long as the leaf documents reference the root document.
Things to Remember
If you do a transition across a page that does not use the root document, the root context becomes destroyed. Once you make this transition and move to another page that references the root document, the root document will be reloaded and the context will be initialized. So, if you want a variable to be stored as you are making transitions through your application, you must reference the root document in each of your VXML pages. Here is an example that demonstrates this point:
From this example, the root document Root.vxml sets the value of variable “foo” to “bar”. When the application starts at Page1.vxml, the variable “foo” is assigned the value “rab” and preserved in the root document. The application next transitions to Page2.vxml, where the root document is not referenced. Here, the value “rab” that was assigned to “foo” becomes lost. When the application transitions to Page3.vxml and references the root document, the variable “foo” takes the value that was set for it in the root document and thus, Page3.vxml returns a prompt of “The value of foo is: bar.”
Keep in mind that for each new call, the root document is loaded separately. So, for each call that is made, the root document will be fetched from the cache and reloaded as a new starting context.
Last updated