<field>

Description

Declares an input field in a form. Prompts user for values that match a grammar.

Syntax


<field
    name="string"
    expr="ECMAScript_Expression"
    cond="ECMAScript_Expression"
    type="boolean" | "currency" | "date" | "digits" | "number" | "phone" | "time"
    slot="string"
    modal="boolean"
    saveutterance="boolean"
    utterancedest="string"
    endbeep="boolean"
    audioinexpr="ECMAScript_Expression"
    wakeupword="boolean">
  child elements
</field>

Attributes

Attribute	Description
name	The name of this field. This variable holds the matched user input and is set according to the Field Variable Assignment rules. This variable can be referenced anywhere within the field's form. Optional. (Defaults to an inaccessible internal variable.)
expr	An ECMAScript expression to be evaluated and used as the initial value of this field. This field will be visited only if the expression evaluates to `undefined`. Optional. (Defaults to undefined.)
cond	An ECMAScript expression to be evaluated and used as a boolean condition. This field will be visited only if the expression evaluates to `true`. Optional. (Defaults to true.)
type	Specifies a built-in speech and dtmf grammar for this field. See Limitation below. Optional (an alternative to using speech and dtmf <grammar> elements to specify the built-in grammar).
slot	The name of the grammar slot used to populate the field item variable; usually used for mixed initiative dialogs. Optional. (Defaults to the variable name.)
modal	Set to true if only the field's grammars are enabled. Otherwise, all active grammars are enabled. See Limitation below. Optional. (Defaults to false.)
saveutterance	Set to true to enable recording of user utterances. Overrides the value of the `com.voicegenie.saveutterance` property. Optional. (Defaults to false.)
utterancedest	Specifies the path of the directory to use for saved utterance audio files. The value will be resolved relative to the `/usr/local/phoneweb/utterance/` directory. Overrides the value of the `com.voicegenie.utterancedest` property. Optional.
endbeep	Specifies whether or not a beep should be played at the end of the prompts, when bargein is disabled. When bargein is enabled, this attribute has no effect (there is never a beep). Platform owners can access the audio file at `/usr/local/phoneweb/audio/effects/endofprompt.vox`. Overrides the value of the `endbeep` property. Optional. (Defaults to false.)
audioinexpr	An ECMAScript expression which should evaluate to a string that specifies a recording to be used as speech input in this field. This can specify a complete or relative URI, or a variable reference to a recording (i.e. `<record>` variable, or `$.utteranceaudio` shadow variable).
wakeupword	Specifies whether or not Wakeup Word Spotting should be used for input in this field. Overrides the value of the `com.voicegenie.wakeupword` property. (Only supported with ScanSoft/SpeechWorks OSR.) Optional. (Defaults to false.)

Attribute Notes

An error event may be thrown if a reserved ECMAScript word is used as the name.
In standards compliance mode, if the type attribute references an invalid builtin type, the error.unsupported.builtin event is thrown at runtime. If the com.voicegenie.STRICTCONFORMANCE property is set to FALSE, the event is thrown at compile time (and therefore cannot be caught by the application).

Shadow Variables

For each <field> whose name attribute is set to <name>, there is a shadow variable <name>$ (in the same scope as the field name variable), containing the following properties:

Property	Description
<name>$.confidence	The recognition confidence level. Floating point value between 0.0 and 1.0. It is an ECMAScript number.
<name>$.utterance	The raw string of words that were recognized.
<name>$.inputmode	The user input mode. One of dtmf or voice.
<name>$.interpretation	This is the same value as the field's `name` variable. (This is a limitation of the VoiceGenie browser. The W3C Specification suggests that this shadow variable should instead be assigned the same value as `application.lastresult$.interpretation`.)
<name>$.audiooffset	(extension) Offset of audio data on bargein (-1 if audio was played to the end). This is `undefined` if last played prompt was not `<audio>`. It is an ECMAScript number.
<name>$.bargein	(extension) True if bargein occurred, false otherwise. It is an ECMAScript boolean.
<name>$.bargeinphrase	(extension) The recognized phrase returned by ASR upon bargein. (See notes, below.)
<name>$.bargeinscore	(extension) Confidence level of the bargein phrase. Floating point value between 0.0 and 1.0. (See notes, below.)
<name>$.info	(extension) ASR recognition result parameters, such as how much time was used to do recognition, from the 'info' portion of the ASR result. Supported with Watson ASR only.
<name>$.utteranceaudio	(extension) A reference to the recording, or `undefined` if no audio is collected. This is only meaningful if the `com.voicegenie.saveutterance` property is set to true.
<name>$.size	(extension) The size of the recording in bytes, or `undefined` if no audio is collected. This is only meaningful if the `com.voicegenie.saveutterance` property is set to true.
<name>$.duration	(extension) The duration of the recording in seconds, or `undefined` if no audio is collected. This is only meaningful if the `com.voicegenie.saveutterance` property is set to true.
<name>$.recording	(VoiceXML 2.1 feature) A reference to the recording, or `undefined` if no audio is collected. This is only meaningful if the `recordutterance` property is set to true.
<name>$.recordingsize	(VoiceXML 2.1 feature) The size of the recording in bytes, or `undefined` if no audio is collected. This is only meaningful if the `recordutterance` property is set to true.
<name>$.recordingduration	(VoiceXML 2.1 feature) The duration of the recording in seconds, or `undefined` if no audio is collected. This is only meaningful if the `recordutterance` property is set to true.
<name>$.markname	(VoiceXML 2.1 feature) The name of the mark last executed by the SSML processor before barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is `undefined`. This only meaningful when the `<field>`'s prompts contain `<mark>`s.
<name>$.marktime	(VoiceXML 2.1 feature) The number of milliseconds that elapsed since the last mark was executed by the SSML processor, until barge-in occurred or the end of audio playback occurred. If no mark was executed, this variable is `undefined`. This only meaningful when the `<field>`'s prompts contain `<mark>`s.

Shadow Variable Notes

The field shadow variable is only set if the user's input is recognized and the field name variable is set, according to the Field Variable Assignment rules. The application.lastresult$ object has corresponding properties which are set after every utterance, even if a nomatch occurs or the recognition result is not used to set the field variable.

When any shadow variable is not set, its value will be ECMAScript undefined.
The shadow variables bargeinphrase and bargeinscore are only meaningful with certain ASR engines that use special notation in their grammars to allow portions of utterances to trigger bargein. Otherwise, these variables are only filled if recognition-based bargein is used, in which case they will have the same values as the recognition result and confidence level. In the application.lastresult$ object, the bargein score and bargein phrase are stored together in the bargeinresult variable, as phrase|score.

Built-in Types

The following built-in types are supported:

Type	Description
boolean	Grammar for affirmative and negative phrases. Returns true for "yes" (or DTMF equivalent) and false for "no" (or DTMF equivalent).
currency	Grammar for currency amount. The result is a string with the format UUUmm.nn, where UUU is the three character currency indicator according to ISO standard 4217:1995, or mm.nn if the currency is not spoken by the user or if the currency cannot be reliably determined (e.g. "dollar" and "peso" are ambiguous). If the field value is subsequently used in a prompt, it will be spoken as a currency amount appropriate to the current locale. The set of accepted spoken currency formats is platform dependent and may vary by locale.
date	Grammar for specifying a date. Returns a fixed-length date string format yyyymmdd. If the year is not specified, yyyy becomes ????; if the month is not specified, mm becomes ??; if the day is not specified, dd becomes ??.
digits	Grammar for a string of digits. Returns the string of digits.
number	Grammar for numbers. Returns a string of digits from 0 to 9, and may optionally include a decimal point (".") and/or a plus or minus sign.
phone	Grammar for a phone number. DTMF asterisk "*" represents "x". The result is a string containing a telephone number consisting of a string of digits and optionally containing the character "x" to indicate a phone number with an extension. For North America, a result could be "8005551234x789".
time	Grammar for specifying time. The result is a five character string in the format hhmmx, where x is one of "a" for AM, "p" for PM, "h" to indicate a time specified using 24 hour clock, or "?" to indicate an ambiguous time. Because there is no DTMF convention for specifying AM/PM, in the case of DTMF input, the result will always end with "h" or "?".

The boolean and digits built-in types can be parameterized with the following syntax:

typename?parameter1=value1;parameter2=value2

For example, we can assign DTMF equivalents for "yes" and "no" in the boolean type:

<field name="mychoice" type="boolean?y=5;n=6">

Type

Input Parameters

boolean

y - the DTMF sequence for an affirmative answer
n - the DTMF sequence for a negative answer

digits

minlength - minimum number of digits
maxlength - maximum number of digits
length - exact number of digits

If there is a conflict among these parameters, an error.badfetch event is thrown.

Parents

<form>

Children

<audio>, <catch>, <dtmf>, <enumerate>, <error>, <filled>, <grammar>, <help>, <link>, <noinput>, <nomatch>, <option>, <prompt>, <property>, <value>, #PCDATA

Extensions

Added saveutterance and utterancedest attributes; added utteranceaudio, size, and duration shadow variables.
Added endbeep attribute.
Added audioinexpr attribute.
Added wakeupword attribute.
Added audiooffset, bargein, bargeinphrase, bargeinscore, and info shadow variables.
Added <dtmf> as a child, to be used like <grammar>.

Limitations/Restrictions

When the modal attribute is set as "true" in a <field> tag, the VoiceGenie browser does not disable the universal grammars. A workaround is to put the universals property inside the field to explicitly disable the universal grammars:

<field name="test" modal="true"> <property name="universals" value="none"/> ... </field>

When a field that specifies the type attribute also has children <grammar> elements, the children grammars are ignored, and only the builtin grammars corresponding to the type attribute are used.

Example


<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
  <form>
    <field name="field1" type="boolean">
      <prompt> Please say yes or no. </prompt>
      <filled>
        You said <value expr="field1"/>.
      </filled>
    </field>
  </form>
</vxml>