VoiceXML 2.1 Development Guide

Home | Frameset Home

GSL Grammar Weighting

| TOC

Shadow Variables

Tutorial: Subdialogs

This tutorial is based on concepts you accomplished in previous tutorials. If you have not completed most of VoiceXML tutorial section, we recommend you go through them first.

In this tutorial, we will:

learn how to reuse our vxml code
author a simple VoiceXML script which references our new dubdialog
learn how to pass variables back and forth between the invoking dialog, and the subdialog itself
create our reusable subdialog component

Step 1: creating our initial VoiceXML file

Many times in our code development, we will want to reuse code fragments rather than waste precious time writing them over and over. Picture, if you will, a survey application asking the caller a series of ten "yes" or "no" questions. Is it really worth the time to write a VoiceXML file with ten separate fields using the same grammar? In the words of the recently departed prophet Joey Ramone:

"Gabba Gabba Hey!"

This roughly translates to "Not really." Being accomplished coders, we can whip out, as a matter of course, a hypothetical "game show" application to demonstrate all that is cool about subdialogs:



<?xml version="1.0" encoding="UTF-8"?>

<vxml version = "2.1">

 <meta name="maintainer" content="yourEmail@here.com"/>

  <form id="Form_1">

    <field name="F_1">

      <prompt>

        what is the tastiest fast food burger ever made?

        whopper, press one.

        big mac, press two.

        big kahuna burger, press three.

      </prompt>



      <grammar type="text/gsl"> [dtmf-1 dtmf-2 dtmf-3] </grammar>



      <filled>

        you chose <value expr="F_1"/>

      </filled>

    </field>

  </form>

</vxml>

Step 2: Implementing the SubDialog references

We recognize the above structure as being pretty familiar, and this works well if we want a simple, one question app. But if we want to get some game-show host credibility for ourselves, we really have to stump our contestants with more than one question, right? So let's transform our code to use subdialogs and increase the length of our game show.



<form id="Form_1">

  <subdialog name="SubD_1" src="Subdialog_File.xml">

    <param name="question"

           expr="' what is the tastiest fast food burger known to man?

                   whopper, press one.

                   big mac, press 2.

                   big kahuna burger, press three.'"/>

    <filled>

      <goto nextitem="SubD_2"/>

    </filled>

  </subdialog>



  <subdialog name="SubD_2" src="Subdialog_File.xml">

    <param name="question"

           expr="' which former fashion model turned actor will soon replace Fabio as the

                   I Cant believe Its Not Buttah spokesperson?

                   to choose Punky Brewster, press one.

                   to choose Marky Mark Wahlberg, press two.

                   to choose Jay Mc Dee, press three.'"/>

    <filled>

      <goto nextitem="SubD_3"/>

    </filled>

  </subdialog>



  <subdialog name="SubD_3" src="Subdialog_File.xml">

    <param name="question"

           expr="' Was Joey Ramone the hardest working ugly man in Rock-n-Roll history?

                   for the answer of most definitely, press one.

                   to choose gabba gabba hey, press two.

                   if you do not know who Joey Ramone is, press three.'"/>

    <filled>

      <prompt>

        congratulations, you are a winner.

      </prompt>

    </filled>

  </subdialog>

</form>

Crikey, this looks new. We have replaced our <field> and <grammar> constructs with a reference to our soon-to-be written external subdialog file using the <subdialog> element:



  <subdialog name="My_SubDialog_Label" src="My_Subdialog_File.xml">

  </subdialog>

Note that we are placing the <subdialog> element at the <form> level, the only location this construct is allowed. We are also declaring a variable to send to our subdialog, this being the text-to-speech question we want to ask while within said subdialog:



    <param name="MyVarName" expr=" 'some string' "/>

Within the Subdialog, we place the familiar <filled> elements to catch the returning result from our external file. We also implement the <goto nextitem> element/attribute to explicitly navigate from one form-item subdialog to the next.

Step 3: constructing the subdialog

While the station takes a commercial break, let's get down to brass tacks and do some work on our subdialog file. Since all of our game show questions have the same basic format, (i.e., ask a question with three possible answers), we can define a single grammar file to be reused, and a single prompt structure that will output the TTS defined within the appropriate "question" parameter. And, since we are going to return back to the invoking dialog once we get a valid answer to any of our questions, we can use the somewhat generic 'response' variable to be sent once the <filled> element is entered.



<?xml version="1.0" encoding="UTF-8"?>



<vxml version = "2.1">

 <meta name="maintainer" content="yourEmail@here.com"/>



<form id="SubD_Form">





<field name="response">



<grammar type="text/gsl"> [dtmf-1 dtmf-2 dtmf-3]</grammar>

<grammar type="text/gsl">[(james brown)] </grammar>



    <prompt>

      <value expr="question"/>

    </prompt>



    <filled>

      <return namelist="response"/>

    </filled>

  </field>

</form>

</vxml>

Most of this should be familiar, with one or two minor exceptions. The first curious piece is our <value expr="question"/> element; what the heck is this all about? That, dear contestants, will output the <param> string we sent across from the invoking dialog as a TTS string. Mighty nifty, eh? The second thing that you'll likely spot, is the <return> element, with the appropriate namelist tacked on:



  <return namelist="response"/>

So what does this element do, you ask? It is simply the method for returning back to our main dialog, and passing along our <field> value so the aforementioned main dialog knows how the question was answered. Our only remaining task is to gussy up the main scipt into a polished application. The muckity-mucks at NBC expect nothing less. Also take note of the fact that while the grammar has the utterance for 'dtmf-1/2/3' defined, it will inherently return a numeric value only, so instead of receiveing 'dtmf-1' from a keypress, you will instead get '1'. As such, we need to code any conditional statements based on this knowledge, (or write a slot defined grammar).

Step 4: Polishing the application

With all the grunt work behind us, let's tie everything together. Below, we add some fancy .wav files, along with some backup text-to-speech in case our audio files cannot be found. Just to show off, we are going to add some conditional logic to our <filled> elements in the main dialog, allowing us to add more appropriate responses to the contestant's answers. Note how we access the variables set in the subdialog below:



      <if cond="SubD_1.response=='1'">

We have to reference subdialog variables in the main script by using the SubDialogName.FieldName syntax. To wit:



      <if cond= " SubDialogName.FieldName == 'value'  ">

Enough of this tip-toeing, onto the polish. And what the heck, let's hire Samuel L. Jackson as the host, and dredge up a few sound files to give our application some "street cred":



<?xml version="1.0" encoding="UTF-8"?>

<vxml version = "2.1">

 <meta name="maintainer" content="yourEmail@here.com"/>

 <form id="Form_1">



  <subdialog name="SubD_1" src="Subdialog_File.xml">

   <param name="question" expr="' what is the tastiest fast food burger known to man?

		              whopper, press one. big mac, press 2. big kahuna burger, press three.'"/>





    <filled>



    <if cond="SubD_1.response=='1'">

       <audio src="No.wav">

          sorry, that is incorrect. the correct answer is the big kahuna burger.

         </audio>



    <elseif cond="SubD_1.response=='2'"/>

       <audio src="No.wav">

          sorry, that is incorrect. the correct answer is the big kahuna burger.

         </audio>



    <elseif cond="SubD_1.response=='3'"/>

        <audio src="tastburg.wav">

          your answer is correct.

         </audio>



    <elseif cond="SubD_1.response=='james brown'"/>

        <audio src="feelgood.wav">

           james brown is the answer to everything.

         </audio>



     <else/>

        <prompt>

          Pathetic, you were not even close

         </prompt>

     </if>

       <goto nextitem="SubD_2"/>

    </filled>

   </subdialog>







   <subdialog name="SubD_2" src="Subdialog_File.xml">



    <param name="question" expr="' which former fashion model turned actor

                                   will soon replace Fabio as the I Cant believe Its

            	              Not Butter spokesperson? to choose punky brewster,

                                   press one. to choose marky mark, press two.

                                   to choose Jay Mc Dee, press 3.'"/>



    <filled>

     <if cond="SubD_2.response=='1'">

       <audio src="No.wav">

          sorry, that is incorrect. while Punky is cute, the correct answer is Jay.

       </audio>



     <elseif cond="SubD_2.response=='2'"/>

      <audio src="No.wav">

          sorry, that is incorrect. while Marky is cute, the correct answer is Jay.

       </audio>



     <elseif cond="SubD_2.response=='3'"/>

       <audio src="correcta.wav">

          your answer is correct.

        </audio>



     <elseif cond="SubD_2.response=='james brown'"/>

      <audio src="feelgood.wav">

        james brown is the answer to everything.

       </audio>



     <else/>

      <prompt>

          Pathetic, you were not even close.

       </prompt>

      </if>



     <goto nextitem="SubD_3"/>

   </filled>

  </subdialog>





  <subdialog name="SubD_3" src="Subdialog_File.xml">



   <param name="question" expr="'Was Joey Ramone the hardest working ugly man in 				Rock-n-Roll history? For the answer of, most definitely,

	press one. to choose, gabba gabba hey, press two.

	if you do not know who joey ramone is, press three.'"/>



    <filled>

     <if cond="SubD_3.response =='1'">

      <audio src="correcta.wav">

       your answer is correct.

      </audio>



     <elseif cond="SubD_3.response =='2'"/>

      <audio src="No.wav">

       sorry that is incorrect. the correct answer is most definitely.

      </audio>



     <elseif cond="SubD_3.response =='3'"/>

      <audio src="No.wav">

       you must be a communist.

       </audio>



     <elseif cond="SubD_3.response =='james brown'"/>

      <audio src="feelgood.wav">

          james brown is the answer to everything.

       </audio>



     <else/>

        <prompt>

          Pathetic, you were not even close.

         </prompt>

     </if>



       <goto nextitem="finish"/>

    </filled>

  </subdialog>





  <block name="finish">

   <prompt>

    you are the Big Winner for the eve.

    you win a dream date with eighties fashion model Jay Mc Dee.

  </prompt>

  </block>



 </form>

</vxml>

Wow, quite a trek through the dense jungles of subdialogs. Now that we have completed this tutorial, we can look to a brighter, less cumbersome VoiceXML future as we utilize subdialogs to reuse simple code fragments. You are no longer... the Weakest Link.

Download the Code!

Source code

What we covered:

SubDialog construction
Use of the <param> element in SubDialogs
Use of the <return> element in SubDialogs
How to access returned variable values from a SubDialog
With the possible exception of Chistopher Walken, Samuel L. Jackson is the Coolest Human on Earth

ANNOTATIONS: EXISTING POSTS

bfoster63

7/20/2004 5:39 PM (EDT)

Neither set of source code works. "1.3" does not recognize the keytones at all; "2.0" recognizes the keytones only as the wrong answer. James Brown comes through loud and clear. Is it supposed to work this way as part of the tongue-in-cheek nature of the content?? James sounds real good though. Any suggestions? Thanks.

MattHenry

7/20/2004 5:48 PM (EDT)

Hi there,

Looks like I neglected to add a link for the *Motorola* version of the code....I'll see about getting that fixed. Do note however, that if you copy/paste from the text of the tutorial, then the code should execute normally. For now, grab this version of the code, which will most certainly work for you:

http://docs.voxeo.com/opensource/vxml_Mot20_subD.zip

~Matt

alexey.timofeev

7/25/2007 10:49 AM (EDT)

Hi!
Subdialogs are really useful stuff in order to reuse common dialogs and I'm eager to use it. But as I've understood from the example the question that is passed using <param> tag is prompted just by TTS. Can it be replaced in anyway with wav-files in order not to use TTS?

Thanks in advance.

MattHenry

7/25/2007 3:24 PM (EDT)

Hi there,

subdialogs can be useful in some cases, but in all frankness, my personal opinion is that:

1) Subdialogs over-complicate applications

2) Character for character, they really don't save any coding time, (it actually takes more effort to code a series of subdialogs than a series of form/field dialogs).

In short, use subdialogs very carefully, and only when needed. To answer your direct question, you can pass in something like this:

<param name="myPrompt" expr="'myfile.wav'"/>

...and execute the audio in the subdialog like so:

<audio expr="myPrompt"/>

Cheers,

~Matthew henry

oliver.huber

3/11/2008 10:46 AM (EDT)

Hi there,

is there any issue with using the shorthand version for

<if cond="response=='1'">

instead of

<if cond="SubD_1.response=='1'">

within the

<subdialog name="SubD_1" src="xyz">

context?

It is obviously working either way, but is there some (hidden) downside to short version?

Cheers,

Oli

voxeojeremyr

3/11/2008 12:10 PM (EDT)

Hi Oli,

If I understand your question correctly, you are asking why the tutorial is using the full name of the response in the subdialog, i.e "Sub_D.response". The reason is because of scoping. Simply trying to access the value by 'response' will not work. The variable 'response' is valid only within the subdialog form <form id="SubD_Form"> within Subdialog_File.xml.

Regards,
Jeremy Richmond
Voxeo Support

Phanimca2003

5/29/2008 2:25 AM (EDT)

Hi

Which element does not supported by subdialog.

voxeojeremyr

5/29/2008 6:07 AM (EDT)

Hi,

I am not sure I understand your question. You can find all the parent - child relationship info for the <subdialog> element at this link:

http://docs.voxeo.com/voicexml/2.0/subdialog.htm

Thanks,
Jeremy Richmond
Voxeo Support

aliciajott

11/4/2008 7:43 PM (EST)

If an error.semantic occurs in a subdialog and is caught by a catch within that subdialog, and not returned to or re-thrown by the calling form, is that error.semantic event still a fatal application error?

Thanks,
Alicia

voxeoJohn

11/4/2008 10:45 PM (EST)

Hi Alicia,

This type of error unfortunately is going to always lead to a fatal application error simply due to the type of error. I hope that addresses your questions here, please let us know if there is anything else that can can do to assist!

Regards,

John D.
Customer Engineer
Voxeo Support

fatma

2/10/2009 5:31 AM (EST)

I'm trying to try a simple subdialog example as follows,

main.xml

<?xml version="1.0"?>
<vxml version="2.1">

<form>

<block>
<prompt>
In the begining
</prompt>
</block>

<subdialog name="SubD" src="sub.xml">
<param name="t" expr="'question'"/>
<filled>
<goto nextitem="Doc"/>
</filled>
</subdialog>

<block name="Doc">
<prompt>
Back to the main document
</prompt>
</block>

</form>
</vxml>

sub.xml

<?xml version="1.0"?>
<vxml version="2.1">
<var name="w" expr="'x'"/>
<form>

<block>
<prompt>
In the Subdialog.The parameter sent is <value expr="t"/>
</prompt>
</block>
<return namelist="w"/>
</form>
</vxml>

but the execution does not return back to the main document!!
can anyone tell me why???

fatma

2/10/2009 8:03 AM (EST)

Sorry for that

I was using a <return> tag in a <form> tag as paren which isn't valid.

voxeoAlexBring

2/10/2009 8:40 AM (EST)

Hello,
You are correct about this, although I'm sure you have already stumbled upon our element table, I would still like to place a [url=http://www.vxml.org/element_summary.htm]LINK[/url] to our useful table that shows attribute, and parent and child relationships between the different elements in VoiceXML. Please let us know if you have any further questions that we may be able to assist you with.

Regards,

Alex Bring
Voxeo Support

GSL Grammar Weighting

| TOC

Shadow Variables