| VoiceXML 2.1 Development Guide | Home | Frameset Home |
<data> element is a new addition to the VoiceXML2.1 specification that allows the developer to fetch content from an XML source without having to use any server side logic, and without having to transition to a new dialog. The XML data fetched by the <data> element is bound to ECMAScript through the named variable that exposes a read-only subset of the W3C Document Object Model (DOM). <data> element shares the same scoping rules as the <var> element. If a <data> element has the same 'name' value as a pre-declared variable in the same scope, the variable is assigned a reference to the DOM exposed by the <data> element.access-control allow element for the fetched content is entirely optional; content that does not have this element specified can still be retrieved on the Voxeo platform.| enctype | Data Type: CDATA | Default: Optional |
| The enctype attribute specifies the MIME type encoding for any data submitted via the namelist attribute. The possible vales for this attribute are ‘x-www-form-urlencoded’, (default), or ‘multipart/form-data’, (for binary data submissions, such as recorded audio). | ||
| fetchaudio | Data Type: CDATA | Default: Optional |
| The fetchaudio attribute specifies the URI of the .wav file to play to the caller in the event of an extended document fetch. Essentially, while the fetch is being made, it allows the developer to play some filler music to the caller rather than presenting only silence. | ||
| fetchhint | Data Type: (prefetch|safe) | Default: prefetch |
Fetchhint is used to specify when the resource should be fetched during application execution. The possible values and their descriptions are:
Note that the Voxeo platform will always prefetch content, regardless of what this attribute value is set to. As such, specifying a value is somewhat redundant. | ||
| fetchtimeout | Data Type: CDATA | Default: 5s |
| The ‘fetchtimeout’ attribute is used to indicate how long, (in seconds or milliseconds), the interpreter should attempt to fetch the content before throwing an error.badfetch exception. See Appendix C for further information. | ||
| maxage | Data Type: CDATA | Default: Optional |
| The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable age, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes. | ||
| maxstale | Data Type: CDATA | Default: Optional |
| The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable staleness, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes. | ||
| method | Data Type: (GET|POST) | Default: Optional (GET) |
| The method attribute specifies the HTTP method to use when sending the request. If unspecified, then the value of ‘GET’, (default) is assumed, unless the submission of multipart/form-data is encountered, in which case the implied method will be ‘POST’. | ||
| name | Data Type: ID | Default: Required |
| The name attribute specifies the name of the ECMAScript form item variable. Each name assigned to an data element must be unique, else a fatal error.badfetch will be thrown. | ||
| namelist | Data Type: NMTOKEN | Default: Optional |
| The namelist attribute specifies a space-separated list of variables to send to the URI indicated by the src or srcexpr attributes. Note that if the namelist attribute is left unspecified, then no variables will be submitted to the destination URI. | ||
| src | Data Type: URI | Default: Required |
| The src attribute specifies the URI where the external XML <data> content is located. Note that either 'src' or 'srcexpr' may be specified, but not both. | ||
| srcexpr | Data Type: CDATA | Default: Optional |
| The srcexpr attribute evaluates to an ECMAScript value that defines the target URI. Either srcexpr or src may be specified for the element, but not both. | ||
| <?xml version="1.0" ?> <vxml version = "2.1"> <meta name="author" content="Matthew Henry"/> <meta name="copyright" content="2005 voxeo corporation"/> <meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/> <var name="MyData"/> <form id="F1"> <block> <data name="MyData" src="MyData.xml"/> <assign name="document.MyData" expr="MyData.documentElement"/> <goto next="#F2"/> </block> </form> <form id="F2"> <script> <![CDATA[ function GetData(d, t) { return (d.getElementsByTagName(t).item(0).firstChild.data); } ]]> </script> <block> <prompt> The values are <value expr="GetData(MyData, 'child1')"/>. the next value is <value expr="GetData(MyData, 'child2')"/>. the next value is <value expr="GetData(MyData, 'child3')"/>. the next value is <value expr="GetData(MyData, 'child4')"/>. the next value is <value expr="GetData(MyData, 'child5')"/>. </prompt> </block> </form> </vxml> |
| <?xml version="1.0" ?> <xml> <parent> <child1>value number one</child1> <child2>value number two</child2> <child3>value number three</child3> <child4>value number four</child4> <child5>value number five</child5> </parent> </xml> |
| <?xml version="1.0" ?> <vxml version = "2.1"> <meta name="author" content="Matthew Henry"/> <meta name="copyright" content="2005 voxeo corporation"/> <meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/> <var name="MyData"/> <var name="Var1" expr="'Corey Feldman'"/> <var name="Var2" expr="'Corey Haim'"/> <var name="MyXMLDest" expr="'MyData.cfm'"/> <form id="F1"> <block> <data name="MyData" srcexpr="MyXMLDest" namelist="Var1 Var2" method="get"/> <assign name="document.MyData" expr="MyData.documentElement"/> <goto next="#F2"/> </block> </form> <form id="F2"> <script> <![CDATA[ function GetData(d, t) { return (d.getElementsByTagName(t).item(0).firstChild.data); } ]]> </script> <block> <prompt> Heres a good joke for you. <break strength="medium"/> So <value expr="GetData(MyData, 'child1')"/> and <value expr="GetData(MyData, 'child2')"/> walk into a bar. <break strength="medium"/> Then they get eaten by Marlun Brando. </prompt> </block> </form> </vxml> |
| <?xml version="1.0" ?> <cfheader name="Cache-Control" value= "no-cache"> <cfheader name="Expires" value="#Now()#"> <CFOUTPUT> <xml> <parent> <child1>#url.Var1#</child1> <child2>#url.Var2#</child2> </parent> </xml> </CFOUTPUT> |
| ANNOTATIONS: EXISTING POSTS |
awirtz
|
|
| The W3 DOM Core Level 1 specification can be found at:
http://www.w3.org/TR/2000/WD-DOM-Level-1-20000929/ |
|
DaveMorris
|
|
| I tried to get an application running for about 4 hours using this data tag. What finally made it work correctly was to remove the <?xml> and also the <xml> tag from the MyData.cfm template. That's bizarre, isn't it? I was getting xml parse errors until I got rid of the xml tags. | |
DaveMorris
|
|
| I presume the external program referenced by <data> can return an XML with multiple items. How does one iterate through those items?
I presume it would be something like: <for( var i = 0; i < arraysize; i++ )> <prompt><value expr="lookupdata.getElementsByTagName('Thing').item(i).firstChild.data"/> </for> Does that work? |
|
MattHenry
|
|
|
Hiya Dave, You are close. If you want to use the <foreach> to iterate through your items, we need to put all the node values into an array first. The code you have would simply output -one- of the node values. I'll try and put together some illustrative sample code to our docs on this topic today, time permitting. ~Matt |
|
MattHenry
|
|
|
Hiya Dave, I cooked this sample script up for you guys today that illustrates using the <foreach> to loop through an array of values returned by a <data> call. I did change the XML file to suit this request, and I think I'll eventaully replace the sample code above with this updated example. Let me know if you have any questions, or run into any problems. ~Matthew Henry ===MyFile.vxml=== <?xml version="1.0" encoding="UTF-8"?> <vxml version="2.1" xmlns:voxeo="http://community.voxeo.com/xmlns/vxml"> <var name="myData"/> <var name="myArray"/> <form id="F1"> <block> <data name="myData" src="myData.xml"/> <assign name="document.myData" expr="myData.documentElement"/> <goto next="#F2"/> </block> </form> <form id="F2"> <script> <![CDATA[ // grab the values of node 'n', and append the values to an array function assignArray(d, n, r) { var j=(d.getElementsByTagName(r).length); var subArray = new Array(); for(var i = 0; i < j; i++) { subArray[i] = d.getElementsByTagName(n).item(i).firstChild.data; } return subArray; } ]]> </script> <block> <prompt> <audio src="valuesAre.wav"> the returned values from the XML document are </audio> </prompt> <assign name="myArray" expr="assignArray(myData, 'child', 'child')" /> <log expr="'***** myArray = ' + myArray"/> <foreach item="nodeHolder" array="myArray"> <log expr="'~~~' + nodeHolder"/> <prompt> <value expr="nodeHolder"/> <break/> </prompt> </foreach> </block> </form> </vxml> === myData.xml ==== <?xml version="1.0" ?> <xml> <parent> <child>value number one</child> <child>value number two</child> <child>value number three</child> <child>value number four</child> <child>value number five</child> </parent> </xml> |
|
Magician
|
|
| I am trying to save intermediate results back to my business/data layer at each step within an involved process.
What is the "best practice" method for triggering a POST defined by <data>? It appears from your samples (cool tricks, btw), that using <assign> will do the job without any unwanted side effects. If this is the method, I'm supposing the the value is my previously defined <data> object. Since nothing is returned, should the name be "null" or "void", of the name of the data object. How is this magic done at Voxeo? Magician |
|
mikethompson
|
|
| Hello Magician,
I'm not sure I understand your question about best practice for triggering a POST with <data>. Are you asking at what point in your application you should submit the data? If this is the case, it's entirely up to you when you would like to do this. There's no better or worse time. I would just make sure you do it during at a time where your call flow is not disrupted too badly. I would also check this tutorial out for best practices for posting data: http://docs.voxeo.com/voicexml/2.0/t_17mot.htm Regarding your second question, <data> has the ability to both retrieve and send data. As such, you may not want to follow the above example provided by Mr. Henry for your POST needs. Again, the above tutorial should be very helpful to you. Best, Mike Thompson Voxeo Corporation |
|
kqian
|
|
| Hi:
I tried to write a simple code in the java servlet with this <data> tag, but it seems that the tag simply can not be understand. I'm currently use Genesys Framework 7.2, which should support VXML 2.1 Here is the code: <?xml version="1.0" encoding="utf-8" ?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/2001/vxml http://www.w3.org/TR/2007/REC-voicexml21-20070619/vxml.xsd"> <script src="../Languages/en-US/PlayConstantsTTS.js" /> <script src="../Languages/en-US/PlayBuiltinTypeTTS.js" /> <script>var f = new Format(); var pb; var i;</script> <form> <var name="stores" expr="''" /> <block> <data name="locations" src="DataServlet.java" /> <prompt>Testing</prompt> </block> </form> </vxml> I took out the <script> part to parse the result because it seems not able to understand the Data tag. The error I got says: http://www.w3.org/2001/vxml|data is an invalid tag;... Please help. |
|
mikethompson
|
|
| Hello,
I am not familiar with the Genesys debugging tools, or what VXML elements their platform supports, so I am not able to offer assistance in that regard. However, have you tried running this application on our hosted environment? I can tell you with certainty, we absolutely support the use of <data>. If you are not familiar with our platform, here is a quick start guide to help you get started: http://evolution.voxeo.com/docs/quickStart.jsp Best, Mike Thompson Voxeo Corporation |
|
jcian
|
|
| Hi!
I am trying to figure out how to greet my user with a friendly "please wait while I retrieve data" message before I actually make the call to get the data, and am running into an issue. It seems that no matter what I try, the fetch always executes as soon as my application loads, and then my "please wait" message fires after the waiting has already occurred! Is there any way (short of actually requesting some voice input from the user and tacking that onto my data URL) to get the platform to read my "please wait" message first, and then do the actual fetch? Here is a sample of what I have (I tried to break things up into seperate forms hoping it would help, but it didnt): <?xml version="1.0"?> <vxml version="2.1"> <script src="somescript.js"/> <form id="main_menu"> <block> <prompt> Please wait while I retrieve the data. </prompt> <goto next="#list_stuff"/> </block> </form> <form id="list_stuff"> <var name="data"/> <block> <data name="xmlData" src="http://someserver.somedomain/somexml.xml" fetchtimeout="10s"/> <assign name="data" expr="parseXml(xmlData)"/> </block> <block> <foreach item="thing" array="data"> <!-- do something --> </foreach> </block> </form> </vxml> |
|
VoxeoDustin
|
|
| Hey,
You almost had it! Since VoiceXML will prefetch the data, we can leverage one or both of two options: 1) fetchaudio - this will play an audio file we specify while the document is being fetched. <property name="fetchaudio" value="please_hold.wav"/> <!-- what to play --> <property name="fetchaudiodelay" value="50ms"/> <!-- how long to wait before playing audio --> <property name="fetchaudiominimum" value="5s"/> <!-- minimum time to play audio file --> 2) dummy field - by requiring user input, we prevent the data in the form from being fetched until after the first field times out. We set the timeout property low so there is no delay added. <?xml version="1.0"?> <vxml version="2.1"> <form id="main_menu"> <field> <property name="timeout" value="50ms"/> <grammar type="text/gsl"> [ aergonaeggegmmfjr ] </grammar> <prompt> Please wait while I retrieve the data. </prompt> <catch event="noinput nomatch"> <goto next="#list_stuff"/> </catch> <filled> <goto next="#list_stuff"/> </filled> </field> </form> <form id="list_stuff"> <var name="data"/> <block> <data name="xmlData" src="http://someserver.com/yourdoc.xml" fetchtimeout="10s"/> </block> </form> </vxml> Cheers, Dustin |
| login |