<data>

Use this element to fetch any XML data from a document server without transitioning to a new VoiceXML document.

Implemented according to the VoiceXML 2.1 specification. See www.w3.org/TR/voicexml21/

The Voice Platform supports ECMAScript e4x syntax and the W3C DOM (Document Object Model) for accessing XML data.

For e4x information, see:

lxr.mozilla.org/mozilla/source/js/rhino/examples/E4X/e4x_example.js (syntax example)

www.ecma-international.org/publications/standards/Ecma-357.htm

For DOM information, see:

www.w3.org/TR/voicexml21/#sec-data

www.w3.org/TR/voicexml21/#sec-data-dom

Attributes

This section describes the attributes you can set for this element.

Name	Data type	Default
blocking	(true \| false)	true
enctype	CDATA	application/x-www-form-urlencoded
fetchaudio	URI	optional
fetchhint	(prefetch \| safe)	prefetch
fetchtimeout	CDATA	optional
httpheaderlist	ECMAScript expression	optional
maxage	CDATA	optional
maxstale	CDATA	optional
method	(GET \| POST)	GET
name	NMTOKEN	optional
namelist	CDATA	optional
src	CDATA	optional (src or srcexpr can be specified, but not both)
srcexpr	CDATA	optional (src or srcexpr can be specified, but not both)
syntax (Nuance extension)	CDATA	Required

blocking

Whether to keep control until the sending operation is complete. If true, the send operation will have completed by the time control is returned to the VoiceXML application. If false, the send operation happens in the background, the application is not blocked, and processing continues to the next element.

enctype

The enctype attribute specifies the media encoding type of the submitted document. The values you can set are:

application/x-www-form-urlencoded (default)—Data is submitted as specified in the HTML 4.01 Specification. Since this encoding can triple the size of data being submitted and is inefficient in performing encoding on binary data, it is not recommended for binary data such as recordings. In such cases, Nuance recommends using the multipart/form-data encoding instead.
multi-part/form-data—Data is submitted as a multipart MIME document (as defined in RFC 2388). Note that each key has its own part, including separate headers. Nuance recommends using this encoding when submitting binary data such as recordings.
application/octet-stream—Data is submitted as a direct stream of values. Note that keys are not submitted. You can use this encoding to submit a single recording to a file URL, which effectively saves the recording to the specified file. Note that it is possible to separate values on the remote side when submitting multiple items.

fetchaudio

The fetchaudio attribute specifies the URI of the audio file to play while waiting for the data to be fetched. If you do not specify the file, a value derived from the innermost relevant fetchaudio <property> element is used. If the fetchaudio property is not set (default), no audio is played during a fetch. See fetchaudio for details on resource fetching properties.

fetchhint

The fetchhint attribute determines when content is retrieved from the server. The settings for the fetchhint attribute are:

prefetch—Files or dialogs are downloaded when a page is loaded.
safe—Files or dialogs are downloaded only when they are actually needed.

A value of prefetch is only possible when the src attribute is used and namelist is empty. This is because when the ECMA expr is used, the interpreter must wait until it reaches that point in the code to evaluate that expr value. Similarly, if a namelist is used, the interpreter must wait to evaluate that ECMA value as well.

If you do not specify a setting for the fetchhint attribute, a value derived from the innermost relevant datafetchhint <property> element is used. See datafetchhint for more information.

fetchtimeout

The fetchtimeout attribute specifies the amount of time to wait for the content to be fetched before throwing an error.badfetch event.

The value may be specified in seconds (s) or milliseconds (ms). If no unit is specified, the value is interpreted as milliseconds by default. If no value is specified, the fetchtimeout defaults to the value set an applicable <property> element, or to the value set for the browser.loading.fetchtimeout property in the Management Station if no <property> applies. If no other default applies, the platform default of 10000 milliseconds is used.

httpheaderlist

The httpheaderlist attribute enables sending custom values in HTTP headers. It specifies an ECMAScript expression that evaluates to an array of headername, headervalue pairs.

Use this mechanism to customize HTTP requests submitted to servers by the Voice Browser service on behalf of VoiceXML applications. It sends runtime information so servers can understand the context of requests and format appropriate responses. Your VoiceXML application (or the voice application server itself) can insert custom values for any purpose. This example assigns httpheaderlist to someHeaders:

var someHeaders = [

     {headername: "Content-Type", headervalue: "text/html; charset=UTF-8"},

     {headername: "custom-hrd1",  headervalue: "custom-value1"}

];

One use of custom headers is to identify the current state of the call and enable the VoiceXML application to initiate a relevant action. Another use is to integrate a web server that provides data to the VoiceXML application: for example, to pass information to a server that validates credit cards.

Note: Use this attribute cautiously, and test thoroughly. Do not specify confidential data in the headers unless protected via TLS. In addition, your tests should ensure the server can respond to the custom values. It's best to create new, custom header/value pairs and avoid setting any standard pairs (because the values you specify will override tested defaults).

You must specify headers as an array of header/value pairs. This example creates two custom headers and values and uses httpheaderlist to insert them into a request:

<script><![CDATA[

     function GetHeaders()      {

     var myHeaders = [

          {headername: "CustomHdr1",  headervalue: "Hdr1Value"},

          {headername: "CustomHdr2",  headervalue: "Hdr2Value1 , Hdr2Value2"},

          {headername: "Content-Type", headervalue: "text/html; charset=UTF-8"},

];

     return myHeaders;      }

     ]]></script>

     .....

     <form id="get_quote">

          <block>

               <data name="quote" srcexpr="'http://myserver/account.html"

                    httpheaderlist="GetHeaders()"/>

               <assign name="document.quote" expr="quote.documentElement"/>

               ......

          </block>

     </form>

     ......

maxage

The maxage attribute specifies the maximum amount of time a fetched resource may remain in the locale cache without requiring a server revalidation. If the value is a number only, the units are assumed to be seconds. The document doesn’t use stale content, unless maxstale is also provided. If maxage is not specified, a value derived from the datamaxage property, if present, is used. See datamaxage for more information.

maxstale

The maxstale attribute specifies the maximum amount of time a stale file remains valid before a refetch is required. If the value is a number only, the units are assumed to be seconds. If maxstale is not specified, a value derived from the datamaxstale property, if present, is used. See datamaxstale for information.

method

The method attribute specifies a GET (default) or POST method for an HTTP request.

name

The name attribute specifies the name of variable that exposes the XML document being returned. The name will be exposed using ECMAScript e4x syntax, or the W3C standard DOM (Document Object Model). In order to conform to the VoiceXML 2.1Specification, Voice Platform requires that you also set the Nuance-extension syntax attribute on <data> when the name attribute is set to e4x. If you use the name attribute without the syntax attribute, the W3C standard DOM is assumed by default.

The following example retrieves a stock quote. The XML file quote.xml fetched by the <data> element contains:

<?xml version="1.0" encoding="UTF-8"?>

<quote xmlns="http://www.example.org">

  <ticker>F</ticker>

  <name>Ford Motor Company</name>

  <change>1.00</change>

  <last>30.00</last>

</quote>

The e4x syntax is:

...

<data name=”MyQuote”, src=”quote.xml” syntax=”e4x”/>

<script>var price = MyQuote.quote.last; </script>

...

The equivalent DOM syntax is:

...

<data name="quote" src="quote.xml"/>

<script><![CDATA[var price = quote.documentElement.getElementsByTagNameNS("http://www.example.org", "last").item(0).firstChild.data;

]]></script>

...

For more information about either syntax, see the links listed under the main <data> element description at the beginning of this section.

namelist

The namelist attribute specifies the list of variables to submit. The default is no variables submitted. If a namelist is supplied, it may contain individual variable references which are submitted with the same qualification used in the namelist. Declared VoiceXML and ECMAScript variables can be referenced.

src

The src attribute specifies the URI of the XML data to retrieve.

Exactly one of src or srcexpr must be specified, otherwise an error.badfetch event is thrown. If the content cannot be retrieved, the interpreter throws an error as specified for fetch failures.

srcexpr

The screpxr attribute is equivalent src except that here, the URI is dynamically determined by evaluating the given ECMAScript expression when the data needs to be fetched. If srcexpr cannot be evaluated, an error.semantic event is thrown.