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