<grammar>

Specifies the grammars (set of phrases a user is expected to say during a dialog in response to a particular prompt) that an application uses for recognition.

Voice Platform supports the GrXML (W3C XML) grammar format, as defined in the Speech Recognition Grammar (GrXML) Specification (W3C Candidate Recommendation June 26, 2002), and compiled binary grammars (.gram).

Attributes

This section describes the attributes you can set for this element.

Name	Data type	Default
fetchhint	(prefetch \| safe)	optional
fetchtimeout	CDATA	optional
maxage	CDATA	optional
maxstale	CDATA	optional
mode	(voice \| dtmf)	voice
root	IDREF	optional
scope	(document \| dialog)	optional
src	CDATA	optional Specify one (and only one) of src, srcexpr, or an inline grammar. Otherwise an error.badfetch is thrown.
srcexpr	CDATA	optional
tag-format	CDATA	Nuance
type	CDATA	optional
version	NMTOKEN	1.0
weight	CDATA	optional
xml:base	CDATA	optional
xml:lang	NMTOKENS	optional

fetchhint

The fetchhint attribute determines when content is retrieved from the server. The settings for the fetchhint attribute are:

prefetch—Files or dialogs are downloaded when a page is loaded.
safe—Files or dialogs are downloaded only when they are actually needed.

The default value is “prefetch” when the <grammar> element specifies an src or srcexpr. Inline grammars will implicitly be forced to a value of “safe”.

fetchtimeout

The fetchtimeout attribute specifies the amount of time to wait for the content to be fetched before throwing an error.badfetch event.

The value may be specified in seconds (s) or milliseconds (ms). If no unit is specified, the value is interpreted as milliseconds by default. If no value is specified, the fetchtimeout defaults to the value set an applicable <property> element, or to the value set for the browser.loading.fetchtimeout property in the Management Station if no <property> applies. If no other default applies, the platform default of 10000 milliseconds is used.

maxage

The maxage attribute specifies the maximum amount of time in seconds that a fetched resource may remain in the locale cache without requiring a server revalidation. The resource may still be used if the time specified in the maxstale attribute is greater than the maxage, but the refresh will always be triggered if the maxage has been exceeded.

If a value for the maxage attribute is not specified, revalidation will occur after the expiration of the freshness lifetime (as defined in Request for Comments (RFC) 2616).

maxstale

The maxstale attribute specifies the maximum amount of time a stale file remains valid before a refetch is required. If a value for the maxstale attribute is not specified, the stale document is refetched.

mode

The mode attribute specifies the mode of the contained or referenced grammar. Acceptable values include voice (both speech recognition and DTMF) and dtmf (dtmf recognition only). The default value is voice.

root

The root attribute specifies the entry point into GrXML, grammars. It is important to note, however, that this attribute is a XML ID reference. As such, this requires the value of the attribute to be contained somewhere on the page as an ID. An alternative to the root attribute is the #ref syntax on URL grammars. See the src attribute for details.

scope

The scope attribute is an optional attribute valid only for form-level grammars. If specified, it overrides the scope attribute set in the parent <form> element, and instead applies a different scope for this particular grammar.

You can set one of the following options:

dialog (default)—The grammar is active only in the current form.
document—The grammar is active throughout the current document. If the current document is the application root document, then the <form> grammar will be active throughout your application.

Other grammars within the same <form> element will still use the <form> scope, unless a different local scope is specified for them as well.

src

The src attribute specifies the URL of a grammar file.

Note: Specify one (and only one) of src, srcexpr, or an inline grammar. Otherwise an error.badfetch is thrown.

The protocol used can be one of:

file
http
builtin (See Built-in grammar types for details).
static

Top-level rules can be identified with a reference on the main URL. Additionally, in special cases, the src attribute can be used to specify just the top-level rule. For example:

<!-- URL location of a GrXMLgrammar with the default top-level rule. -->

<grammar src="grammars/boolean.grxml" />

<!-- URL location of a GrXML grammar with a specified top-level rule within the grammar. -->

<grammar src="grammars/boolean.grxml#Strict" />

<!-- Inline grammar specifying a top-level rule. -->

<grammar src="#Order" >

    Type [pan (deep dish)]

    Order (i want a Type pizza)

</grammar>

<!-- Specifies a static grammar loaded into the Main VoiceBrowser package.Grammars referenced in this way must be declared in the package as:public, and cannot be "top-level" grammars (i.e. those with the dot prefix). -->

<grammar src="static:BigGrammar"/>

<!-- Specifies a platform custom builtin grammar. -->

<grammar src="builtin:DrivingDirections?distance=10"/>

srcexpr

The srcepxr attribute is equivalent to src except that here, the grammar file URL is dynamically determined by evaluating the given ECMAScript expression in the current scope (for example, the current form item). Since this expression is evaluated every time the grammar needs to be activated, use this attribute only when necessary.

Note: Exactly one of src, srcexpr, or an inline grammar must be specified, otherwise an error.badfetch event is thrown.

The example below captures a street address. The three fields request a country, a city, and a street in that order. The grammar for the city field is selected dynamically using the result of country field; the grammar for the street field is selected dynamically using the result of the city field.

<field name="country">

  <grammar type="application/srgs+xml" src="country.grxml"/>

  <prompt>Say a country.</prompt>

<field name="city">

  <grammar type="application/srgs+xml" srcexpr="country +   '/cities.grxml"/>

  <prompt>What city in <value expr="country"/>.</prompt>

<field name="street">

  <grammar type="application/srgs+xml" srcexpr="country + '/' 
  + city + '/streets.grxml'"/>

  <prompt>What street in <value expr="city"/> are you looking for?   </prompt>

</field>

tag-format

Ignored.

type

The MIME type for the grammar:

MIME type	Value
GrXML	application/srgs+xml
compiled grammar	application/x-swi-grammar

version

The grammar version.

weight

The grammar's weight relative to other grammars active for that recognition state. This value can range from 0.0 to 100.0.

xml:base

The base URL for resolving relative paths. Use this attribute to override the base of the VoiceXML document (see File header).

xml:lang

A space-separated list of language codes for the referenced grammar. These codes are used in conjunction with other active <grammar> codes to route the recognition request to the appropriate package. Each code identifier is compliant with RFC 1766.

If the xml:lang attribute is not specified, the xml:lang attribute of the enclosing <vxml> element is used. Note that the xml:lang attribute of the enclosing <vxml> element defaults to the Java Virtual Machine's locale.

The value of the xml:lang attribute is defined as:

lang_value = language [DELIMITER country]

DELIMITER = "-"

language = <ISO-639 language code>

country = <ISO-3166 country code>

For example, some valid specifications of the xml:lang attribute are:

fr French

en-US American English

It is possible to specify any valid RFC-1766 language code in the xml:lang attribute.

Children

Parents

Sample code

<!-- A <value> element nested within in a <grammar> element allows you to dynamically create or modify an inline grammar on the client. This feature is different from specifying an expr attribute within a grammar, which allows you to dynamically select a grammar on the server.

Note that there are two inefficiencies that result from the use of the embedded <value> elements.

First, there is the extra scripting that must occur when something is dynamic rather than static. This inefficiency is akin to use the expr attribute on <grammar> rather than the src attribute.

Second, the content of inline grammars (generated with <value> or not) cannot be cached. In other words, they must be compiled on each recognition cycle. For this reason, if there is significant dynamic content within the <grammar>, and that content is cacheable, it's best to generate such grammars on the server.

The following example demonstrates using the <value> element to build a grammar. Note that when using an embedded <value> element, you must specify the grammar type. The voice browser service does not auto-detect the type when embedded <value>s are used.-->

<var name ="a_GRXML_Grammar_Rule"/>

<script><![CDATA[

    a_GRXML_Grammar_Rule = '<rule

    id="Test"><one-of><item>goodbye</item></one-of></rule>';]]>

</script>

<field>

    <prompt>Say hello or goodbye</prompt>

<!--Note that within GRXML, each <value> element is meant to define a <rule>. You may have other statically defined <rule>s in place, but you cannot use the <value> element to define a portion of a <rule>.-->

<grammar type="application/srgs+xml" root="Test">

    <value expr="a_GRXML_Grammar_Rule"/>

</grammar>

</field>