Export (0) Print
Expand All

field

Formulates an interactive dialog between the user and the system.

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

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?."

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.

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.

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).

A sample transcript for this example follows:

Tellme:

Please say a day of the week.

Caller:

(mumbles) Sunday.

Tellme:

I'm not sure, but I thought you said Monday. Say a day of the week. For example, say Monday.

Caller:

(clearly) Sunday.

Tellme:

You said Sunday. Please say a day of the week.

<?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>

   <!-- illustrate the use of the confidence shadow variable -->
   <form id="confidence">
      <script><![CDATA[
         // days of the week. 
         // The result returned by the grammar is used to index into the array.
         var aDOW = ["Sunday", "Monday", "Tuesday", 
            "Wednesday", "Thursday", "Friday", "Saturday"];
      ]]></script>
   
      <field name="dow">

         <grammar src="dow-voice.grxml" mode="voice" type="application/srgs+xml"/>
         <grammar src="dow-dtmf.grxml" mode="dtmf" type="application/srgs+xml"/>

         <prompt count="1"> Please say a day of the week. </prompt>
         <prompt count="2"> 
           Say a day of the week.  
           For example, say Monday. 
         </prompt>

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


         <filled>
            <!-- dow$.confidence is set during the recognition -->
            <if cond="dow$.confidence &lt; 0.75">
               <prompt> i'm not sure, but i thought you said 
               <value expr="aDOW[dow]" /> </prompt>

               <!-- reset "dow" variable; will play second prompt -->
               <clear namelist="dow"/>
            <else/>
               <prompt> you said <value expr="aDOW[dow]" /> </prompt>

               <!-- reset by clearing all form item variables; 
                 back to first prompt -->
               <clear />
            </if>
         </filled>

      </field>
   </form>
</vxml>

The following example provides a simple demonstration of the field element's inputmode shadow variable. By detecting if the user responds using voice or DTMF input or has trouble responding to the request for voice input, the example tailors the UI of the next dialog.

<?xml version="1.0"?>
<vxml version="2.1"
 xmlns="http://www.w3.org/2001/vxml">
  <var name="vmode" expr="true"/> <!-- default to voice mode -->
  <form id="main">
    <field name="yesno" type="boolean">
    <prompt>Say yes to begin or no to quit.</prompt>
    <catch event="noinput nomatch">
       Sorry. I didn't get that.
       Let's try this another way. On your touch-tone keypad 
       type 1 for yes, or type 2 for no.
       <assign name="vmode" expr="false"/>
    </catch>
    <filled>
      <if cond="!yesno">
         <exit />
      </if>
      <if cond="yesno$.inputmode=='dtmf'">
            <log>Switching to DTMF mode</log>
            <assign name="vmode" expr="false"/>
      </if>
      <goto next="#pick_fruit"/>
    </filled>
    </field>
  </form>

  <form id="pick_fruit">
    <field name="fruit">
    <prompt cond="vmode">Say apple, orange, or pear.</prompt>
    <prompt cond="!vmode">Type 1 for apple, 2 for orange, or 3 for pear.</prompt>

    
    <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>
                            apple
                        </item>
                    </one-of>
                    <tag>out.fruit = "apple";</tag>
                </item>
                <item>
                    <one-of>
                        <item>
                            orange
                        </item>
                    </one-of>
                    <tag>out.fruit = "orange";</tag>
                </item>
                <item>
                    <one-of>
                        <item>
                            pear
                        </item>
                    </one-of>
                    <tag>out.fruit = "pear";</tag>
                </item>
            </one-of>
        </rule>

    </grammar>

    
    <grammar mode="dtmf"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0">
        <rule id="root_rule" scope="public">
            <one-of>
                <item>
                    <one-of>
                        <item>
                            1
                        </item>
                    </one-of>
                    <tag>out.fruit = "apple";</tag>
                </item>
                <item>
                    <one-of>
                        <item>
                            2
                        </item>
                    </one-of>
                    <tag>out.fruit = "orange";</tag>
                </item>
                <item>
                    <one-of>
                        <item>
                            3
                        </item>
                    </one-of>
                    <tag>out.fruit = "pear";</tag>
                </item>
            </one-of>
        </rule>

    </grammar>

    
    <catch event="noinput nomatch">
       Sorry. I didn't get that.
       <assign name="vmode" expr="false"/>
       <reprompt/>
    </catch>
    <filled>
       <prompt>You picked <value expr="fruit"/></prompt>
       <!-- reset vmode for this demo -->
       <assign name="vmode" expr="true" />
       <goto next="#main"/>
    </filled>
    </field>
  </form>

</vxml>

Community Additions

ADD
Show:
© 2015 Microsoft