<field>

Declares an input field in a form.

Syntax

 <field
     name="string"
     expr="js_expression"
     cond="js_expression"
     type="boolean"|"currency"|"date"|"digits"|"number"|"phone"|"time" 
     slot="string"
     modal="true"|"false"
     bevocal:urlexpr="js_expression"
 >
   Child Elements
 </field>

Description

Input item that prompts user for a value that matches a particular grammar.

Attribute Description

name
Name of the input variable that will hold the recognition result. The variable name may not be a JavaScript reserved keyword.

The input variable has dialog (form) scope; its name must be unique among all VoiceXML and JavaScript variables within the form's scope.

expr
JavaScript expression that assigns the initial value of the input variable for this field. Optional (default is undefined).

If you set the input variable to a value other than undefined, you'll need to clear it before the field can execute.

cond
JavaScript boolean expression that also must evaluate to true for the field to execute. Optional (default is true).

If not specified, the value of the input variable alone determines whether or not the field can execute.

type
Specifies a built-in grammar. Optional (as alternative to <grammar> element).

• boolean--Grammar for recognizing positive and negative responses. Returns true for yes and false for no.

• currency--Grammar for recognizing amounts of money, in dollars (Not implemented: International currency designation). Returns a string with format mm.nn.

• date--Grammar for recognizing dates. Returns string with format yyyymmdd; ???? is used for an unknown year and ?? is used for an unknown month or day.

• digits--Limited grammar for recognizing a sequence of digits. Returns a string of digits.

• number--More general grammar for recognizing numbers. Returns a string that could include digits, a decimal point, or positive or negative sign.

• phone--Grammar for recognizing a telephone number adhering to the North American Dialing Plan (with no extension). Returns a sequence of digits.

• time--Grammar for recognizing a time. Returns a string with format hhmmx where and x is one of: a for AM, p for AM, h for 24 hour notation, or ? for an ambiguous time (could be AM or PM).

slot
If this field is part of a mixed-initiative dialog, the name of the grammar slot that will be used to assign a value to the input variable for this field. Optional (defaults to variable name).

This attribute is ignored by a field-level grammar. See the Grammar Reference for more information on grammar slots.

modal
Boolean value that must be true to temporarily turn off higher level grammars. Optional (default is false).

Lets you alter default behavior so that only this field's grammars are active while the field executes.

bevocal:urlexpr
JavaScript expression that evaluates to the URI of an audio file or a local audio variable. The local audio variable can be from a <record> tag or can be a shadow variable that contains audio. Optional.

Lets you perform recognition against input from the specified audio file or from a local audio variable.

Properties of the Shadow Variable

Corresponding to the input variable name is a "shadow variable" called name$. After the input variable is filled, some additional information is available in the following properties of this shadow variable:

Property Description

confidence

The recognition confidence level (with 0.0 representing the lowest confidence and 1.0 representing the highest).

utterance

A string representation of the words actually spoken by the user.

inputmode

The mode in which input was provided, one of voice or dtmf.

audio

If the bevocal.audio.capture or recordutterance property is set to true and the user's speech matched the field grammar, the audio property contains an audio capture of the user's speech.

You can send the captured audio to a server using a <data> element. Doing so is useful if you need a record of the user's speech for legal reasons.

recording
If the recordutterance property is set to true and the user's speech matched the field grammar, the recording property contains an audio capture of the user's speech. If no audio is collected, this variable is undefined.

You can send the captured audio to a server using a <data> element. Doing so is useful if you need a record of the user's speech for legal reasons.

recordingsize
The size of the recording in bytes, or undefined if no audio is collected.

recordduration
The duration of the recording in milliseconds, or undefined if no audio is collected.

interpretation
The interpretation returned from the recognition result, or undefined if no interpretation is available.

For a field whose name is name, you access the property propName of the shadow variable with the syntax:

 name$.propName

For example, you access the confidence property for the color field as:

 color$.confidence

Built-in Types--Parameters

Some built-in field types can be parameterized to affect the built-in type's behavior. The following table shows the types that can be parameterized and indicates which input parameters must be specified.

Field Type Input Parameters

boolean

• y--The DTMF keypress for an affirmative response.

• n--The DTMF keypress for a negative answer.

digits

• minlength--The minimum number of digits in a valid response.

• maxlength--The maximum number of digits in a valid response.

• length--The exact number of digits in a valid response.

Note: If you do not specify length or maxlength, the built-in grammar accepts any number of digits. You should use length or maxlength whenever you can; doing so usually results in more accurate speech recognition.

A parameter is specified within the type attribute with syntax of the form:

 typeName ? parameter = value

For example the following element specifies a field of type digits that must contain exactly five digits:

   <field name="mydigits" type="digits?length=5">

More than one parameter may be specified; the parameters are separated by semicolons.

Note: The interpreter throws a error.badfetch event if it retrieves a VoiceXML file that contains a field type with inconsistent parameters, such as:

   <!-- ERROR: Inconsistent parameters for field type -->
   <field ... type="digits?minlength=5;maxlength=1">

Built-in Types--Output.

In VoiceXML 2.0 the field's type attribute no longer defines an implicit <say-as> type to output the field's value. Instead it plays the value in normal TTS. You must now use the type attribute of <say-as> for a type-specific readout of the value.

Tip:

•	If a JavaScript expression contains any of the characters "`<`", "`>`", or "`&`", that character must be replaced with the corresponding escape sequence "`<`", "`>`", or "`&`". For more information, see JavaScript Quick Reference.

Usage

Parents Children

<form> <audio> <catch> <enumerate> <error> <filled> <grammar> <help> <link> <noinput> <nomatch> <option> <prompt> <property> <value>

Exceptions

error.semantic - Thrown if no grammars are active.

See Also

•	VoiceXML 2.0 Specification: `<field>`
•	Grammar Reference
•	Related tags: `<filled>`, `<grammar>`

Examples

Example 1--no type:

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form id="foo">
     <field name="name">
       <prompt> What is your favorite color? </prompt>
       <grammar type="application/x-nuance-gsl">
         [ red green yellow blue orange ]
       </grammar>
       <filled>
         <prompt> Your favorite color is <value expr="name"/> </prompt>
       </filled>
     </field>
   </form>
 </vxml>

Example 2--boolean type:

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form id="form1">
     <field name="new_file" type="boolean"> 
       <prompt>
         Do you want to play the game again?
       </prompt>
       <filled>
         <prompt>
           Your answer is <value expr="new_file"/>
         </prompt>
       </filled> 
     </field> 
   </form>
 </vxml>

Example 3--date type:

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form id="form1">
     <field name="today" type="date"> 
       <prompt>
         What date is today? Please say or enter month day and year.
       </prompt>
       <filled> 
         <prompt>
           Your answer is 
           <say-as type="date"><value expr="today"/></say-as>
         </prompt> 
       </filled> 
     </field> 
   </form>
 </vxml>

Example 4--digits type:

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form id="form1">
     <field name="card_num" type="digits"> 
       <prompt>
         Please say or enter the last four digits of your credit card.
       </prompt> 
       <filled> 
         <if cond="card_num.length != 4"> 
           <prompt>
             Sorry, I didn't hear exactly four digits.
           </prompt> 
           <clear/>
           <reprompt/>
         <else/>
            <prompt>
             The number you entered is
             <say-as type="number:digits"> <value expr="card_num"/> </say-as>
           </prompt>
         </if> 
       </filled> 
     </field> 
   </form>
 </vxml>

Example 5--currency type:

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form id="form1">
     <field name="ticket_cost" type="currency"> 
       <prompt>
         Please say the cost of your ticket.
       </prompt> 
       <filled> 
         <prompt>
           The cost you entered is
           <say-as type="currency"><value expr="ticket_cost"/></say-as>
         </prompt>
       </filled> 
     </field> 
   </form>
 </vxml>

Example 6--number type:

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form id="form1">
     <field name="num_count" type="number"> 
       <prompt>
         Please say the number of computers you want to order.
       </prompt> 
       <filled> 
         <prompt>The number you entered is <value expr="num_count"/></prompt>
       </filled> 
     </field> 
   </form>
 </vxml>

Example 7--phone type:

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form id="form1">
     <field name="phone_num" type="phone"> 
       <prompt>
         Please say or enter your phone number.
       </prompt> 
       <filled> 
         <prompt>
           The phone number you entered is
           <say-as type="telephone"> <value expr="phone_num"/></say-as>
         </prompt>
       </filled> 
     </field> 
   </form>
 </vxml>

Example 8--time type:

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
   <form id="form1">
     <field name="meeting_time" type="time"> 
       <prompt>
         Please say the meeting time.
       </prompt> 
       <filled> 
         <prompt>
           The meeting time is
           <say-as type="time"> <value expr="meeting_time"/> </say-as>
         </prompt>
       </filled> 
     </field> 
   </form>
 </vxml>

[Show Frames] [FIRST] [PREVIOUS] [NEXT]

Property	Description
`confidence`	The recognition confidence level (with 0.0 representing the lowest confidence and 1.0 representing the highest).
`utterance`	A string representation of the words actually spoken by the user.
`inputmode`	The mode in which input was provided, one of `voice` or `dtmf`.
`audio`	If the `bevocal.audio.capture` or `recordutterance` property is set to `true` and the user's speech matched the field grammar, the `audio` property contains an audio capture of the user's speech. You can send the captured audio to a server using a `<data>` element. Doing so is useful if you need a record of the user's speech for legal reasons.
`recording`	If the `recordutterance` property is set to `true` and the user's speech matched the field grammar, the `recording` property contains an audio capture of the user's speech. If no audio is collected, this variable is undefined. You can send the captured audio to a server using a `<data>` element. Doing so is useful if you need a record of the user's speech for legal reasons.
`recordingsize`	The size of the recording in bytes, or undefined if no audio is collected.
`recordduration`	The duration of the recording in milliseconds, or undefined if no audio is collected.
`interpretation`	The interpretation returned from the recognition result, or undefined if no interpretation is available.

Parents	Children
`<form>`	`<audio>` `<catch>` `<enumerate>` `<error>` `<filled>` `<grammar>` `<help>` `<link>` `<noinput>` `<nomatch>` `<option>` `<prompt>` `<property>` `<value>`