Tutorial: Hello World with Container Element Inheritance

This Lesson is based on the things you accomplished in Lesson 1. If you haven't yet done this Lesson, you'll need to go through it first so that you aren't left in the dust with the high-falutin' concepts that we discuss here.

In this tutorial, we will:

explore the retooled <block> container element
learn about the new container alias names
explore how we can set a document/dialog scoped parameter so that it is active for all relevant child elements

Step 1: A few words about container element aliases

In the previous tutorial, we ended up with a callxml file that was pretty one-sided: Your caller dials the application, the application plays some audio, then the application hangs up. We are going to do the same thing here, but we are going to do it in a much more slick, and lean fashion by utilizing the concept of container element inheritance, which is a brand new feature in CallXML 3.0.

Those of us who have worked with later versions of CallXML, (v1.0/2.0), should be familiar with the <block> element, which groups all of our action and event handling elements into logical 'blocks' of code. CallXML 3.0 adds intelligent naming syntaxes to this element, that allows us to christen our containers so that they are more representative of what will be occurring in the section of code. To explain, all of the below elements are for all purposes equivalent:

<block>
<case>
<do>
<if>
<switch>
<with>

So, if we wanted to have a section of code that performed some conditional logic that used the 'test' attribute, we might use the alias of <if>, or possibly <case>, to make our code more readable at a glance. If we decided that our section of code would output some media, or perform a specific action based on a user's input, we might choose to name our container element <do>. Again, there is no requirement of any kind as to what container name you use; this entirely dependent on the developer's coding style and sensibilities.

Step 2: A few words about value inheritance from container elements

Also new to the CallXML 3.0 feature set is the 'value' attribute for container elements. Populating this attribute with something valid will also populate any child elements that do not have a specific value defined. Elements that do have a specific value defined will return their values, and will not be overwritten by container values that are specified. This allows a large degree of freedom in writing CallXML 'shorthand' that will save the developer lots of time, in not having to repeat these values throughout the code, and additionally makes for much cleaner, and easier to debug, CallXML documents.

Now, let's take a look at putting some of these concepts into action, and writing some code that uses the <do> alias to populate the values of it's own 'child' elements. Again, in our last tutorial we used the <prompt> element to output our pre-recorded audio file to the caller. We will do the same thing here, but we will also add in some Text-To-Speech, and a <log> statement that will be visible in the application debugger window. The trick of it is, we are going to use the inherent ability of container elemnts to set our values but once, and have this populate all of our 'child' elements, as we covered above. Our starting point is going to be with our initial XML declarations,just like in the last tutorial. Remember, that as we are using the 3.0 version of the markup, the only suitable 'version' setting will be, (you guessed it), "3.0":


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

 </callxml>

Now that we have the beginnings of an IVR application, we can add in our container element, and give it a value:


<?xml version="1.0" encoding="UTF-8"?> 
 <callxml version="3.0"> 
  <do value="helloworld">

    <prompt/>
    <say/>
    <log/>

  </do>
 </callxml>

Step 3: Breaking things down

As we mentioned, we don't have a darn thing defined for our 'child' elements, (<prompt>, <say>, and <log>), but per our definitions above, we know that these values will be generated from the container element. We can map this application, as-is, and call it, and the following will occur:

the <prompt> element will play the "helloworld.wav" file
the <say> element will render "helloworld" to the caller via TTS.
the <log> element will print out "helloworld" in the application debugger

By comparison, let's look at an alternate way of doing the same thing so we can get a feel for exactly why container inheritance is so handy:


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

    <prompt value="helloworld"/>
    <say>hello world</say>
    <log value="helloworld">

  </do>
 </callxml>

See any redundancy? Of course you do. This is the exact reason why using container inheritance is so useful. Jumping down from our Soapbox, let's now take the next step, and add a few more child elements, this time *with* some values:

Step 4: Complicating things even further


<?xml version="1.0" encoding="UTF-8"?> 
 <callxml version="3.0"> 
  <do value="helloworld">

    <prompt/>
    <say/>
    <log/>
    <say>we are now done with our humble application</say>
    <log value="***  APPLICATION EXITING ***"/>

  </do>
 </callxml>

We didn't do anything too complicated, contrary to the heading. All we did was add an additional <say> and <log> element to the mix, this time with predefined values. You'll note that these values are not changed by the container element at all, and will execute as you see them above. Once again, nothing too fancy about adding in a few more media elements to hammer home the fact that container inheritance only applies to child elements that do not have a value defined.

Step 5: Upload and test!

Your "hello world with container inheritance" application is now complete. You can now upload this you your server, or our free webhosting servers, and map a CallXML 3.0 number to the application to try it out first-hand. And in the event that you are too lazy to write the code yourself, or even copy-paste, you can download the source code below without lifting a finger. Well of course, you kind of -need- to lift a finger to click the link, but if you can manage that, we take care of the rest for you.

CallXML 3.0 source code.

ANNOTATIONS: EXISTING POSTS

awirtz

6/18/2007 4:48 PM (EDT)

I notice you define "value" in the container tag and that is inherited as the "value" attribute of the "log" tag, but what about the "say" tag? According to the documentation on "say", there is no "value" attribute per se. Is "value" an undocumented attribute of "say" when used as a singleton tag, or is "value" a universally magic attribute that will be used in the absence of textual content in other tags as well?
Additionally, if "value" is universally magic, does it go the other way too? E.g. can I use text content inside a pair of "log" tags instead of a "value" attribute in a singleton "log" tag?
-Aaron

voxeojeff

6/18/2007 8:30 PM (EDT)

Hello Aaron,

I, too, noticed that 'value' is not listed as a valid attribute of the <say> element. However, per my testing, it appears to work. I have spoken with our CallXML 3.0 gurus about this, and they have informed me that it does indeed work for now, but if it is not listed in the documentation, then it is not guaranteed to continue working in the future as updated versions come out. I hope this helps clarify things. :-)

Best regards,

Jeff Menkel
Voxeo Corporation

visionik

1/30/2008 8:41 AM (EST)

Actually Aaron, you're half right.

There are a few CallXML tags where the value attribute and the text content of that tag serve the same purpose. "Say" is one of them, so these are the same:

<say>hello</say>

<say value="hello"/>

You might ask why this behavior is present on a few elements.

In short, you're seeing a few places where we "prototyped" this behavior with an eye towards some CallXML 4 features we're testing.

As voxeojeff said, because its undocumented - and because the underlying reason for its implementation was an experiment - it may go away.

Container Inheritance

| TOC

| Recognizing User Input