====== Forms, menus, and links ======

===== What is a form ? =====

A form in a VoiceXML document presents information and gathers input from the user.
A form is represented by the <form> tag and has an ID attribute associated with it. The
ID attribute is the name of the form. Following is an example of the use of a form
element:

<code>
 <form id="hello" >
  <block>
   Hello world!
  </block>
 </form>
</code>

In this example, the name of the form is "hello" and "Hello world" is presented to the user.

===== Form items =====

Two types of form items exist: field items and control items. A field item prompts the
user on what to say or key in and then collects the information from the user that is
then filled into the field item variable. A field item also has grammars that define the
allowed inputs, event handlers to process the resulting events, and a <filled> element
that defines an action to be taken after the field item variable has been filled. Following
is a list of types of field items:
  * <field>: value of the field item is obtained from the user via speech or DTMF grammars
  * <record>: value of the field item is an audio clip recorded by the user, such as a voice mail message, which can be collected by the <record> element
  * <transfer>: used for transferring the user to another telephone number
  * <object>: invokes platform-specific object with one or more properties
  * <subdialog>: like a function call, invokes a call to another dialog on the current page or another VoiceXML document.

A control item's task is to help control the gathering of the form's fields. Following are two types of control items:
  * <block>: sequence of statements used for prompting and computation
  * <initial>: useful in mixed initiative dialogs that prompt the user for information

===== Form item variables and conditions =====

A form item variable is associated with each form. The form item 'variable by default' is
set to 'undefined' initially and contains a result (collected from the user) once a form
item has been intepreted. You can define the name of a form item variable by using the
name attribute. A guard condition exists for each form item. The guard condition tests
whether the item's variable currently has a value. If a value exists, then the form item is
skipped.

===== Menus =====

A menu gives the user a list of choices to select from and transitions to a different dialog or document based on the user's choice. Following is an example of a menu:

<code>
<menu>
 <prompt>Say what sports news you are interested in:
 <enumerate/></prompt>
 <choice next="http://www.news.com/hockey.vxml">
  Hockey
 </choice>
 <choice next="http://www.news.com/baseball.vxml">
  Baseball
 </choice>
 <choice next="http://www.news.com/football.vxml">
  Football
 </choice>
 <noinput>Please say what sports news you are interested in
  <enumerate/>
  </noinput>
</menu>
</code>

The menu element supports the following attributes:
  * id: Identifies the menu
  * scope: The scope of the menu's grammar
  * dtmf: If choices in a menu don't have explicit DTMF elements, they are given implicit ones "1", "2", etc. This is only if DTMF is set to 'true'.

The choice element specifies the URL to go to based on the choice selected from the menu. The enumerate element specifies a template that is applied to each choice in the order they appear in the menu. So, for the above example, the menu's prompt would be, "Say what sports news you are interested in: hockey; baseball; football".

===== Links =====

A <link> element specifies one or more grammars. When one of these grammars is
matched, the link is activated and either transitions to the destination specified, or
throws an event. Below is an example of the usage of the link element:

<code>
 <link next="http://www.news.com/hockey.vxml">
  <grammar type="application/x-jsgf"> red | yellow <grammar>
  <dtmf> 1 </dtmf>
 </link>
</code>

The link is activated when you say "red" or press "1". The next attribute of the link element specifies the appropriate destination.