field

Article
03/26/2013

field element

Formulates an interactive dialog between the user and the system.

Syntax

<field 
cond = "ECMAScript_Expression"
expr = "ECMAScript_Expression"
modal = "boolean"
name = "variable"
slot = "slot_name"
type = "string"
/>

Attributes

cond	A condition that must evaluate to true for the element to be selected by the form interpretation algorithm (FIA). If this condition evaluates to false or the variable associated with the name attribute has a defined value, the element is not visited.
expr	An ECMAScript expression that supplies the initial value for the form item variable associated with this element. If the expression evaluates to something other than null or ECMAScript undefined, the element will not be visited until the form item variable is explicitly cleared.
modal	One of the following values: falseAll active grammars are enabled while collecting data for this field. trueActive grammars outside this form are temporarily disabled; only the grammar(s) of the field are enabled.
name	The variable that holds the recognition result if a recognition match occurs. If the attribute is not specified, the interpreter creates a hidden, anonymous variable to store the result.
slot	The slot name within the grammar used to populate the named variable for this field. If this attribute is absent, the slot is equivalent to the value of the name attribute. If the grammar returns only a single slot, the field item variable is filled with the value in that slot even if the slot name differs from the value of this attribute.
type	The name of one of the following built-in grammars: booleanDefines a field that expects an affirmative or negative response from the user. The DTMF digits 1 and 2 are supported for yes and no. The result is an ECMAScript true or false. currencyDefines a field that expects a currency amount from the user. For DTMF input, the star key () acts as a decimal point. The result is a concatenated string prefixed by the currency indicator if spoken by the user. For example, if the user utters "150 US Dollars and 95 cents", the Platform returns "USD150.95". Amounts are limited to ten million dollars. dateDefines a field that expects a date including month, day, and year from the user. The user can input the date using DTMF in the following format: yyyymmdd. The result is a fixed-length date string formatted as yyyymmdd. For example, if the user utters June 18, 1970, the Platform returns "19700618." If a part of the date was not uttered by the user, it is returned as question marks (?). For example, if the user utters "June 1970", the Platform returns "197006??." digitsDefines a field that expects one or more individual digits (0-9) from the user. The result is a string of concatenated digits. For example, if the user utters "1" "5" "0", the Platform returns "150". Use the ECMAScript parseInt function to convert the string to a number. numberDefines a field that expects a number from the user. For example, the user can say "one hundred and fifty", "thirty-nine point five", or "negative twenty-three". For DTMF input, the star key () acts as a decimal point. The result is a string of concatenated digits. Use the ECMAScript parseFloat function to convert the string to a number. phoneDefines a field that expects a phone number from the user. For example, the user can say "one six five zero nine three zero nine two three four extension one two three". For DTMF input, the star key (*) acts as an "x" and indicates an extension. The result is a string consisting of the telephone number, for example "16509309234x123." timeDefines a field that expects the time including hours and optionally minutes, and AM or PM. The result is a time string formatted as hhmmx where x is "a", "p", "h", or "?" to indicate AM, PM, military, or an ambiguous time. DTMF input does not support AM or PM. If, for example, the user says "one-thirty p m", the result is "0130p." If the user types "1300", the result is "1300h." If the user says "one", the result is "0100?."

Shadow variables

The field element exposes the following shadow variables.

name$.confidence	The confidence level (0.0-1.0) of the recognition match returned by the recognizer, where 0.0 is low confidence and 1.0 indicates high confidence.
name$.utterance	The string of words recognized by the recognition engine. The string corresponds to the utterance definition in a grammar expression.
name$.interpretation	An ECMAScript variable containing the interpretation of the user input.
name$.inputmode	The mode of user input. If a grammar element was used to define the selected utterance, the value corresponds to the grammar element's mode attribute. dtmfIndicates that the field element's item variable was filled via DTMF input. voiceIndicates that the field element's item variable was filled via one or more spoken words.
name$.markname	The name of the last mark that was executed before barge-in or the end of playback occurred. If no mark was active, this shadow variable is undefined.
name$.marktime	The number of milliseconds that elapsed since the last mark was executed when barge-in or the end of audio playback occurred. If no mark was active, this shadow variable is undefined.
name$.recording	The variable that stores the recorded utterance when the recordutterance property is set to true. Like the variable associated with the name attribute of the record element, this shadow variable stores a reference to the recording within the scope of the dialog that contains the field. The recording referenced by the recording shadow variable is in the format specified by the recordutterancetype property. For information on persisting the recording to a Web server see the utterance recording tutorial.
name$.recordingsize	The size of the utterance recording referenced by the recording (name$.recording) shadow variable, in bytes.
name$.recordingduration	The duration of the utterance recording referenced by the recording (name$.recording) shadow variable, in milliseconds.

Parents

form

Children

audio, catch, enumerate, error, error, grammar, help, link, noinput, nomatch, option, prompt, property, value

Remarks

To take advantage of n-best processing, set the maxnbest property to a value greater than 1. When the filled element is executed, check the confidence shadow variable of the field element to see if the recognizer returned a value with a reasonably high confidence level. If not, consider disambiguating from among the elements in the application-scoped lastresult$ array.

Use the built-in grammars accessed via the type attribute to rapidly prototype your application. Use custom, tuned grammars when transitioning to production-level code.

The Tellme VoiceXML interpreter creates an implicit form item variable for a field that you do not name explicitly. Although the variable name is currently predictable, your application code should not rely upon it since it is likely to change in a future release. To manipulate the form item variable associated with a field you must explicitly set the name attribute. If you attempt to reference an implicitly declared form item variable, the following deprecation warning will appear in the Debug Log: "possible direct access of internal variable".

If the type attribute specifies a grammar type that is not supported by the platform, the interpreter throws error.badfetch prior to Revision 3, or error.unsupported.builtin in Revision 3 and later.

Field names must conform to the following conventions:

A field name must consist only of numbers, letters, underscores ("_"), and dollar signs ("$").
A field name must begin with a letter.
A field name may only end with a letter, a number, or an underscore.
Field names that begin with an underscore ("_") or end with a dollar sign ("$") are reserved for use by the interpreter.

The handling of invalid field names prior to revision 3 is the following:

If a field name contains spaces, the interpreter throws error.badfetch to the calling document.
If a field name begins with a number, or contains invalid characters, the interpreter throws error.semantic to the document containing the invalid field name.
If a field name ends in a dollar sign ("$"), no error is thrown.
If a field name begins with an underscore ("_"), then in revision 2, the interpreter throws error.badfetch to the calling document, but no error is thrown prior to revision 2.

In revision 3 and later, if a field has an invalid name, the interpreter throws error.semantic to the calling document.

Examples

This example asks the user to pick a store. A nomatch or noinput event results in a more detailed prompt, letting the user know what choices we offer.

A sample transcript for this example follows:

Tellme:	Where do you want to shop?
Caller:	Bookstore
Tellme:	I'm sorry. I didn't understand. Where do you want to shop? You can choose pet store or flower store.
Caller:	Flower shop
Tellme:	Okay, let's shop for flowers.

<?xml version="1.0"?>
<vxml version="2.1"
 xmlns="http://www.w3.org/2001/vxml">
   <link event="event.exit">
   
   <grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0"
         xml:lang="en-US">
      <rule id="root_rule" scope="public">
         <one-of>
            <item>
               quit
            </item>
            <item>
               goodbye
            </item>
         </one-of>
      </rule>

   </grammar>

   </link>

   <catch event="event.exit">
      <exit />
   </catch>

   <form>
      <field name="store_type">
         
         <grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0"
         xml:lang="en-US">
                  <rule id="root_rule" scope="public">
                           <one-of>
                                    <item>
                                             <one-of>
                                                      <item>
                                                               pet
                                                               <item repeat="0-1">
                                                                        <one-of>
                                                                                 <item>
                                                                                          store
                                                                                 </item>
                                                                                 <item>
                                                                                          shop
                                                                                 </item>
                                                                        </one-of>
                                                               </item>
                                                      </item>
                                             </one-of>
                                             <tag>out.store_type = "pets";</tag>
                                    </item>
                                    <item>
                                             <one-of>
                                                      <item>
                                                               florist
                                                      </item>
                                                      <item>
                                                               flower
                                                               <one-of>
                                                                        <item>
                                                                                 store
                                                                        </item>
                                                                        <item>
                                                                                 shop
                                                                        </item>
                                                               </one-of>
                                                      </item>
                                             </one-of>
                                             <tag>out.store_type = "flowers";</tag>
                                    </item>
                           </one-of>
                  </rule>

         </grammar>


         <prompt count="1">Where do you want to shop?</prompt>

         <!-- give more information in the second prompt -->
         <prompt count="2">
            Where do you want to shop? You can choose pet store or florist.
         </prompt>

         <catch event="nomatch noinput">
         I'm sorry. I didn't get that.
         <reprompt/>
         </catch>

         <filled>
            <prompt>Okay, let's shop for <value expr="store_type"/></prompt>

            <!-- restart the example -->
            <clear />
         </filled>
      </field>
   </form>
</vxml>

This example illustrates the use of the confidence shadow variable. On each recognition, this variable will be set, and can be used to trigger a confirmation. In this example, if confidence is below .75 the application will check the recognition result. Each grammar requires individual tuning, as the value being compared has no intrinsic meaning (i.e. do not assume .75 is a reasonable threshold).