# <subdialog>

Description

Invokes another dialog as a subdialog of the current one. The subdialog is a reusable dialog that allows values to be returned. The subdialog executes in a new execution context with all variables and execution state initialized. Values can be passed into the subdialog using `<param>` child elements; the subdialog must contain `<var>` variable declaration for each parameter. The original dialog can continue execution only when the subdialog executes the `<return>` element. Returned values are available as properties of the `<subdialog>` form item variable.

Note: The values passed in and out of a subdialog (using `<param>` and `<return>`) can be strings or any ECMAScript values (ex. numbers, pointers, objects, arrays, etc.).

Syntax

    <subdialog
        name="string"
        expr="ECMAScript_Expression"
        cond="ECMAScript_Expression"
        src="URI"
        srcexpr="ECMAScript_Expression"
        namelist="variable1 variable2 ..."
        method="get" | "post"
        enctype="MIME_type"
        fetchaudio="URI"
        fetchaudiodelay="time_interval"
        fetchaudiominimum="time_interval"
        fetchhint="safe"
        fetchtimeout="time_interval"
        maxage="integer"
        maxstale="integer">
      child elements
    </subdialog>

Attributes

Attribute | Description
name | The name of this subdialog. This variable can be referenced anywhere within the subdialog's form. The results returned from the subdialog can be retrieved as properties of the subdialog variable: `name.<returnVariable>`. Optional. (Defaults to an inaccessible internal variable.)
expr | An ECMAScript expression to be evaluated and used as the initial value of this subdialog. This subdialog 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 subdialog will be visited only if the expression evaluates to `true`. Optional. (Defaults to true.)
src | The URI of the subdialog. This can be the URI of another document, a dialog in the same document, or a dialog in another document. If this attribute is empty (""), the current document will be used. Exactly one of src or srcexpr must be specified.
srcexpr | An ECMAScript expression to be evaluated and used as the URI of the subdialog. This can be the URI of another document, a dialog in the same document, or a dialog in another document. If this attribute is empty ("") or set to the empty string ("''"), the current document will be used. Exactly one of src or srcexpr must be specified.
namelist | A space-separated list of variables to submit with the request. Optional. (Defaults to nothing.)
method | The request method: get or post. Optional. (Defaults to get.)
enctype | The MIME encoding of the submitted data. The following types are supported: application/x-www-form-urlencoded multipart/form-data Optional. (Defaults to application/x-www-form-urlencoded.)
fetchaudio | The URI of audio to play while waiting for the document to be fetched. Optional.
fetchaudiodelay | The length of time to wait at the start of the fetch delay before playing `fetchaudio`. Optional.
fetchaudiominimum | The minimum length of time to play `fetchaudio`, once started, even if the document arrives in the meantime. Optional.
fetchhint | Defines when the subdialog should be fetched. Optional. safe - only load the subdialog when needed
fetchtimeout | The length of time to wait for the subdialog to be fetched before throwing an `error.badfetch` event. Optional.
maxage | Indicates that this document is willing to use a cached copy of the subdialog only while the age of the cached copy is less than or equal to the number of seconds specified by this attribute. Optional.
maxstale | Indicates that this document is willing to use a cached copy of the subdialog that has exceeded its expiration time by as much as the number of seconds specified by this attribute. Optional.

Attribute Notes

- An `error` event may be thrown if a reserved ECMAScript word is used as the `name`.
- An `error.semantic` event is thrown if an undeclared variable name is used in the `namelist`.
- An `error.badfetch` event is thrown if more or less than one of `src` and `expr` are specified.

Parents

<form>

Children

<audio>, <catch>, <error>, <filled>, <help>, <noinput>, <nomatch>, <param>, <prompt>, <property>, <value>, #PCDATA

Extensions

- Added `fetchaudiodelay` attribute.
- Added `fetchaudiominimum` attribute.

Limitations/Restrictions

- When submitting ECMAScript objects in the `namelist`, the object will be "flattened", ie. all the object's properties will be submitted separately. For example, if object `o` has two properties, `p1` and `p2`, such that `o.p1 = "value1"` and `o.p2 = "value2"`, and the following subdialog is called:
  `<subdialog name="s1" src="test.jsp" namelist="o" ...>`
  then the HTTP request will contain `o.p1=value1&o.p2=value2`. Remember to retrieve the properties separately (as `o.p1` and `o.p2`) in the server-side code used to generate the subdialog page.

- The order in which the parameters are sent in an HTTP request may not be the same as the order specified in the `namelist`.
- The use of POST is recommended when submitting a long list of variables. If you use GET (where the entire request is a single line), there may be a limit configured on the request length. Exceeding this limit will result in an `error.badfetch`. This limit may be configured by Squid on the Dialogic IP Media Server, or may be overridden by application server configuration.

Example

Document that calls the subdialog:

    <?xml version="1.0"?>
    <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
      <form>
        <subdialog name="result" src="subdialog.vxml">
          <filled>
            Your account number is <value expr="result.acctnum"/>.
            Your phone number is <value expr="result.acctphone"/>.
          </filled>
        </subdialog>
      </form>
    </vxml>

Document containing the subdialog:

    <?xml version="1.0"?>
    <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
      <form>
        <field name="acctnum" type="digits">
          <prompt> What is your account number? </prompt>
        </field>
        <field name="acctphone" type="phone">
          <prompt> What is your home telephone number? </prompt>
          <filled>
            <return namelist="acctnum acctphone"/>
          </filled>
        </field>
      </form>
    </vxml>