script

Article
03/26/2013

script element

Includes a block of ECMAscript code.

Syntax

<script
charset = "string"
fetchaudio = "URI"
fetchhint = "string"
fetchtimeout = "string"
maxage = "seconds"
maxstale = "seconds"
src = "URI"
srcexpr = "ECMAScript_Expression"
/>

Attributes

charset	The character set in which the script is encoded. iso-8859-1 The United States ASCII character set synonymous with "us-ascii."
expr	DEPRECATED. Use srcexpr instead.
fetchaudio	The URI of the audio clip to play while the interpreter fetches the resource. For complete details on the proper use of this attribute, read the fetchaudio tutorial.
fetchhint	Defines when the interpreter context may retrieve scripts from the server. prefetchScripts may be prefetched. safeScripts may only be fetched when needed, never before.
fetchtimeout	The time in seconds (s) or milliseconds (ms) for the VoiceXML interpreter to wait for content to be returned by the HTTP server before throwing an error.badfetch event. The fetchtimeout value is rounded down to the nearest whole second (e.g., 5700ms or 5.7s would be rounded down to 5s). If fetchtimeout has a value less than 1 second, it is reset to the default value. The default value is 15s.
maxage	Sends the max-age Cache-Control HTTP header along with the request for the specified resource. The header indicates that the document is willing to use content whose age is no greater than the specified time in seconds, unless maxstale is also provided. Voice application developers should use extreme caution when setting this attribute. If used improperly, it could have an adverse affect on the performance of your application. You should only consider using this attribute in requests for frequently changing content (e.g. dynamically generated content) hosted on a misconfigured HTTP server that you do not control. To reduce load, some HTTP servers are configured to indicate to clients that content expires some arbitrary time in the future. In that case, set the maxage attribute to 0. If you do control the HTTP server, you should instead configure the HTTP server to omit the expires header and possibly to send the Cache-Control: no-cache header. The former requires the VoiceXML interpreter to check with the server before using any cached content. The latter requires the VoiceXML interpreter to not cache the fetched resource.
maxstale	Instructs the VoiceXML interpreter to send a max-stale Cache-Control header along with the HTTP request for the specified resource. The header indicates that the document is willing to use content that has exceeded its expiration time by no more than the specified number of seconds. Voice application developers should use extreme caution when setting this attribute. If used improperly, your application may present stale content to users. If you do control the HTTP server, you should instead configure the HTTP server to send an expires header with a time in the distant future.
src	The URI of an external script file.
srcexpr	An ECMAScript expression that resolves to the URI of an external script file.

Parents

block, catch, error, filled, foreach, form, help, if, menu, noinput, nomatch, prompt, vxml

Children

None.

Remarks

The script element enables you to embed ECMAScript within your VoiceXML file or to reference externally a file containing ECMAScript.

If you specify both a src attribute and inline ECMAScript, the Platform ignores the inline script.

The src and srcexpr attributes are mutually exclusive.

The VoiceXML interpreter uses an XML parser to parse a VoiceXML document. When embedding a block of script directly within a VoiceXML document, use a CDATA section to prevent the XML parser from parsing the script. Otherwise, if the XML parser encounters a character such as <, >, or &, used in script for comparison and bit-wise operations, it will generate an error.

If any of the fetchtimeout, fetchhint, maxage, or maxstale attributes is not specified for a script element, then the value of the fetchtimeout, scriptfetchhint, scriptmaxage, or scriptmaxstale property, respectively, is used.

Prior to Revision 3, if a referenced script is empty, it is silently ignored. In Revision 3 and later, the interpreter throws error.badfetch.

Prior to Revision 3, the interpreter ignores any undeclared variables in the namelist attribute. In Revision 3 and later, the interpreter throws error.semantic if any of the variables is undeclared.

Prior to Revision 3, it is possible to assign values to undeclared variables at application, document, and dialog scope when executing a script. In Revision 3 and later, an attempt to assign a value to an undeclared variable results in the interpreter throwing error.semantic.

Examples

The following example defines an inline script block that defines an array of objects, each representing an advertisement, and a function to return a random advertisement. The VoiceXML calls the function and plays the advertisement to the user. Run the code a few times, and you are likely to get a different advertisement each time.

<?xml version="1.0"?>
<vxml version="2.1"
 xmlns="http://www.w3.org/2001/vxml">
<script>
<![CDATA[
   // declare array of advertisements
   // an ad consists of a (tts, wav) hash tuple
   var aAds = [
      {"tts" : "Brought to you by ack me airlines.", "wav" : "aa.wav"},
      {"tts" : "Brought to you by virtual traders.", "wav" : "vt.wav"},
      {"tts" : "Brought to you by napa vineyards.", "wav" : "nv.wav"},
   ];

   // pick a random ad from the array
   function GetRandomAd()
   {
      // get a number between 0 and and the number of ads minus one
      var iAd = Math.floor(Math.random()*aAds.length);
      return aAds[iAd];
   }
]]>
</script>

<form id="play_ad">
   <block>
      <var name="oAd" expr="GetRandomAd()"/>
      <audio expr="oAd.wav">
        <value expr="oAd.tts"/>
      </audio>
   </block>
</form>
</vxml>

To reuse the advertisement code in multiple VoiceXML documents or applications without having to copy, to paste, and to maintain the code in various locations, you can move the contents of the script element into a separate file and include that code using the src attribute of the script element. As shown, an external script file includes neither the script element nor the CDATA section.

// declare array of advertisements
// an ad consists of a (tts, wav) hash tuple
var aAds = [
  {"tts" : "Brought to you by ack me airlines.", "wav" : "aa.wav"},
  {"tts" : "Brought to you by virtual traders.", "wav" : "vt.wav"},
  {"tts" : "Brought to you by napa vineyards.", "wav" : "nv.wav"},
];

// pick a random ad from the array
function GetRandomAd()
{
  // get a number between 0 and and the number of ads minus one
  var iAd = Math.floor(Math.random()*aAds.length);
  return aAds[iAd];
}

The following example sources in and calls the GetRandomAd function contained within the external script shown in the previous example.

<?xml version="1.0"?>
<vxml version="2.1"
 xmlns="http://www.w3.org/2001/vxml">
   <!-- include the ad code --> 
   <script src="ads.js"/>
   <form id="play_ad">
      <block>
         <var name="oAd" expr="GetRandomAd()"/>
         <audio expr="oAd.wav"><value expr="oAd.tts"/></audio>
      </block>
   </form>
</vxml>