Scripting Your Interactive XML Application

Setting Up Your .xml File
Scripting Your .xml File
Working With Variables
Media Resources
Testing Your .xml File

Setting Up Your .xml File

The first line of the .xml file must read as follows:
<?xml version="1.0" encoding="UTF-8"?>
Be sure to always save your .xml file with UTF-8 encoding. Otherwise, the file may contain illegal characters.

The rest of the file must be scripted according to the Tag Hierarchy.

Scripting Your .xml File

Following is an overview to help you grasp the basics of scripting your Interactive XML application. For more details about functionality and syntax, please consult the Glossary of Interactive XML Tags. You can also refer to the Interactive XML code for the following demo applications:
  1. '80s Flashback Music Trivia featuring Mark Goodman. This is the application you see on the home page of this site. The code is here.
  2. Movie Date Trivia. This application tests your knowledge of famous date scenes in movies. The code is here.
  3. Trivia Demo. This application uses videos of generic responses in the context of a geography trivia game. The code is here.
(Note: If you are using the Chrome browser, you'll have to go to View → Developer → View Source to see the code rendered correctly.)


At the highest level, your .xml file must be enclosed within <document> tags. At the next level, Interactive XML is structured to accommodate one <settings> tag and any number of <node name=""> tags.


As the name suggests, <settings> is where you can establish default behavior for much of your application, such as the position of videos on the screen, the file path for media, and the presence of mute or pause buttons. You can also define templates of clickable buttons so they do not have to be redefined in multiple places.

See the <settings> definition in the glossary for more information.


Nodes, represented by <node name=""> tags, are the "steps" through which an Interactive XML application progresses. The topmost node defined in the script is the node through which the user enters the application and can be considered the starting point of the interaction. For the interaction to continue, each node must lead to another node. If a node does not lead to another node, the interaction will end there and such a node (or nodes) can be considered the ending point of the interaction.

Here is a simple example of how a series of nodes might define an interactive experience:

<node name="hello">
            <media_end node="how_are_you"/>
<node name="how_are_you">
            <media_custom_event node="how_are_you_buttons"/>
<node name="how_are_you_buttons">
<node name="user_good">
            <media_end node="goodbye"/>
<node name="user_bad">
            <media_end node="goodbye"/>
<node name="goodbye">

In the above interaction, here's what the user would experience:
  1. A video (hello.mp4) in which the host of the interaction says hello (hello node).
  2. A video (how_are_you.mp4) in which the host asks, "How are you?" (how_are_you node).
  3. Three seconds after the "How are you?" video starts, "Good" and "Bad" buttons will appear on the screen (how_are_you_answer node). The media defined in the previous node plays in succession, so the user will see a video of the host waiting for an answer (waiting_for_answer.mp4).
  4. If the user clicks "Good," they will go to the user_good node and see a video of the host acknowledging that the user feels good (user_good.mp4).
  5. If the user clicks "Bad," they will go to the user_bad node and see a video of the host acknowledging that the user feels bad (user_good.mp4).
  6. At the conclusion of the user_good.mp4 or user_bad.mp4 videos, the interaction advances directly to the goodbye node, in which the host says goodbye.
Here are some important things to keep in mind regarding nodes:
  1. A node can determine which node to proceed to depending on user behavior or other conditions, such as a button click or the time elapsed from the beginning of a video.
  2. A node does not have to actually include any user interaction. A node may simply increment a counter, evaluate the result of a web service call, or perform any number of actions that are "invisible" to the user.
  3. Unlike many scripting languages, nodes in Interactive XML can be recursive. In other words, Node A can lead to Node B and Node B can lead back to Node A.
  4. Other than the topmost node being the first node, nodes are not hierarchical. They can lead arbitrarily to any other node anywhere in the script.
Working With Variables

Data may be written to variables for use during a user session. These variables may also be stored across sessions in the user's Flash cookie.

See the following tags in the tag glossary: <assign name="" expr=""/>, <get>, <if cond=""><set>.

In order to call a variable within any tag besides <assign name="" expr=""/>, <get> and <set>, it must be placed within percent symbols. For example:
Variables may be called in this way in any tag (as long as they resolve to a value that's appropriate for that tag). This is useful to establish default values as well as to help provide a more personalized experience to the user. Some examples:


<bg_mp3 file="%user_favorite_song%"/>

<media_end node="%next_node%"/>
Setting Flash Variables

Flash variables may be set within the .html page on which the application is embedded and subsequently accessed within the .xml code. This is also where the name of the .xml content file to be used is specified.

There are two places within the code on the .html page where the Flash variable must be defined: the OBJECT tag and the EMBED tag.

First, look within the OBJECT tag and find the FlashVars PARAM tag:
<PARAM NAME="FlashVars" VALUE="ContentFile=my_app.xml">
Add an ampersand (&) followed by the name of the variable and the value of the variable as follows:
<PARAM NAME="FlashVars" VALUE="ContentFile=my_app.xml&entry_point=home_page">
Then find the FlashVars attribute within the multi-line EMBED tag and add the variable there as well:
Then you can evaluate the variable directly in your .xml file:
<if cond="entry_point=='home_page'">
          <!-- Insert functionality for home page entry point. -->
          <!-- Insert functionality for other entry point. -->
In order to be able to test your application on testing pages that do not have your Flash variable defined, you should define the variable with a default value in the <settings> section of your .xml:
<assign name="entry_point" expr="''"/>
The bg_image Flash Variable

Interactive XML recognizes a special Flash variable: bg_image. If you use it in the OBJECT and EMBED tags as described above, the specified image will be displayed in the object window before the XML for your application loads. It is effectively the same as using the <bg_image file=""/> tag in your XML code, with the added benefit that the image will load right away, giving your users a smoother starting experience.


In the FlashVars PARAM tag within the OBJECT tag:
In the FlashVars attribute within the multi-line EMBED tag:
The StageHeight and StageWidth Variables

The variables StageHeight and StageWidth are system variables that represent the current dimensions of the Flash frame. If the frame is resized, these variables will change accordingly.

Media Resources

Interactivation has provided media resources for your use at the following location:

Currently, the resources include:
  1. Clear .png files of various sizes to create transparent "buttons" (by defining them with <image name=""> tags that contain <link> tags).
  2. A set of video (.mp4) files of generic responses (e.g., "Hello," "Goodbye," "Well done!") that you are free to use in your application. These videos are featured in the Trivia Demo application. (See code here.)
Testing Your .xml File

When you're ready to test your Interactive XML application, you should follow these steps:
  1. Open the .xml file in a browser window and fix any XML errors the browser might report.
  2. When the .xml file opens properly in a browser window, test your code in the  online Interactive XML testing page.
To use the testing page, copy-paste the entire contents of your .xml file into the window at the top of the page and click the "Start" button. Any debug text you have specified in your application will output in the debug window at the bottom of the page as the application runs. To reload your code, refresh the page and paste the code again. The testing page also allows you to:
  1. skip to any node in your application by entering it in the "Skip to node" field and clicking "Submit," and
  2. skip to any point in the video that is currently playing by entering a number of seconds in the "Seconds into video" field and clicking "Submit."
Tips & Tricks
  1. It's a good idea to set a background image (see <bg_image file=""/>) in the first node of a video-driven Interactive XML application. Otherwise, a blank, gray screen will appear momentarily as the Flash is loading. Ideally, this image should be the first frame of the video that is about to play.
  2. If something's not working and you're not sure what it is, first check your .xml file in a browser window (as described above) and fix any XML formatting errors.
  3. Be sure to follow the advice listed in What makes a good Interactive XML application?.
Check back here as we add more tips & tricks!