XML Documents and Flash

Flash can use XML documents from any source providing that they are well formed . The most straightforward method is to use a file saved with an .xml extension. This document can be something that youve written in NotePad, SimpleText, or XMLSpy. It can also be an Office 2003 document, perhaps from a Word template or Excel spreadsheet.

Flash can also consume XML documents provided by web services. You can do this either by using data components or by writing ActionScript. Your Flash movie can display parts of the XML document, perhaps by binding it to a UI component such as the DataGrid.

You can also use a server-side file to consume a web service using REST. The server-side file accesses a URL and receives the XML content. The file can then provide the XML document to Flash.

In Flash version 5, a measurable speed difference was caused by different XML document structures. Information in attributes parsed more quickly than information contained in elements. As a result, early XML documents created for Flash used attributes quite a bit. Im not sure if there is still a noticeable speed difference with later Flash players.

One useful piece of advice that I can give you is that if youre going to write ActionScript to work with XML, it will really benefit you to keep the element structures in your XML document as simple as possible. Try to avoid deeply nested elements as the document will be much harder to process than if you use flatter structures.

Creating an XML Document

Id like to finish this chapter by creating an XML document from scratch. Well also create a schema for the document so that we can update it in Office 2003 later.

Ill work through some of the decisions that well need to consider when creating our XML document. For this example, you can use either a text editor or an XML editor like XMLSpy. Ive used XMLSpy as youll see from my screenshots.

Well be creating an XML document to describe photographs for an XML photo gallery that well create in Chapter 4. The photos that were going to use are stored with the resource files in the photos folder. To make things easier, they are all landscape photos that are exactly the same width and height. In case youre interested, theyre all photos that Ive taken during my travels .

Our task is to design an XML document that will store information about these photos. Well need to store the file name of the photo, a caption, and a description. If you look at the photo names , youll see that they all have a two-letter prefix indicating where they were taken. There are photos from Australia, Europe, the United Kingdom, the United States, and South Africa.

You can see a working example of this photo gallery at www.sasjacobs.com. Click the photo gallery link on the home page. The online example uses transitions between each photo.

Before we start typing, lets consider the relationships between the pieces of data that were going to store. The photo gallery contains many photos. Each photo comes from an area or location, and more than one photo can be associated with an area.

Figure 3-37 shows the relationships that well need to capture in our XML document.

Figure 3-37: The data structure for the photo gallery

Lets start at the top and work down. Well need to begin with an XML declaration. Actually, Flash doesnt need this, but its a good habit for you to get into.

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

All of the information in this XML document is contained inside the photo gallery, so well use that for the document root:

 <photoGallery></photoGallery> 

The photo gallery has multiple locations for the photos. Each location has its own name. Ill create an element with an attribute for the location name. This listing shows the XML document with the list of locationsAustralia, Europe, the United Kingdom, the United States, and South Africa:

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <photoGallery>   <location locationName="Australia"></location>   <location locationName = "Europe"></location>   <location locationName = "South Africa"></location>   <location locationName = "UK"></location>   <location locationName = "US"></location> </photoGallery> 

Youll notice that I called the attribute locationName instead of just name . Theres nothing wrong with using the word name ; its just not very specific and could easily refer to other elements. More importantly, name is often a reserved word in programming languages. Even though Flash will probably let us use the word name , it may color it incorrectly in the Actions panel.

Each <location> contains one or more photos, so well include child <photo> elements in each <location> . Using one of the <location> elements as an example, the XML document fragment looks like this:

 <location locationName="Australia">   <photo></photo>   <photo></photo> </location> 

Each photo has a single file name, caption, and description. Heres where we have a choice to make. Photos have two characteristics as well as a text description. We can either enter these as attributes within the <photo> element, as child elements, or as a mixture of both. Here are some of the choices for structuring the XML document:

 <photo>   <filename></filename>   <caption></caption   <description></description> </photo> 

or

 <photo filename="xxx" caption="yyy" description="zzz"/> 

or

 <photo filename="xxx" caption="yyy">   Text displayed inside the photo element </photo> 

All of these choices are valid structures for the XML documents; however, the implications of each will be different.

The first choice, where all elements are child elements of <photo> , creates a clearly defined hierarchy in our elements. In the schema, we can specify the datatypes for each element as well as the order in which the elements are to appear. Actually, the order probably doesnt really matter. What is important is that there is only one occurrence of each element.

However, the first option creates a structure that nests more deeply than either of the other two examples. This means well need a little extra code to display the data within Flash.

The second option isnt too bad, but the description could be a problem. Well probably want to enter quite a long description for some photos, and this might make the attribute difficult to read. We may also want to add some basic HTML tags for display within Flash, and we cant do that inside an attribute.

I favor the third option. Logically, the file name and caption are attributes of a <photo> element. Placing the text description inside the <photo> element allows us to enclose it within a CDATA declaration to preserve any HTML tags. There are no child elements within the <photo> element, which means it will be easier to process this document within Flash.

This listing shows the completed <location> element for the photographs of the United States:

 <location locationName = "US">   <photo filename="us-grandcanyon.jpg" caption="The Grand Canyon">     <![CDATA[Flying through the <b>Grand Canyon</b> in a helicopter     was an amazing experience.]]>   </photo>   <photo filename="us-timessquare.jpg" caption="Times Square">     <![CDATA[There is <b>no</b> place in the world like Manhattan.]]>   </photo> </location> 

Notice that Ive included <b></b> tags in my description text. Ill be able to display these words as bold in Flash. I had to include the text as CDATA so that the <b></b> tags dont get parsed when the XML document is loaded.

Ive saved the completed XML document as resource file photoGallery.xml . Figure 3-38 shows this document open in XMLSpy. I checked to see that the document was well formed.

Figure 3-38: The complete file photoGallery.xml displayed in XMLSpy

Creating a schema

Now its time to write a schema for this XML document. To start with, well need a new file containing an XML declaration and a root node that refers to the appropriate namespace:

 <?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> </xsd:schema> 

Ill need to add declarations, starting with <photoGallery> , the document root of photoGallery.xml . This is a complexType element because it contains <location> elements. Each <location> element has to occur at least once and there is no upper limit for the number of repeats.

 <xsd:element name="photoGallery">   <xsd:complexType>     <xsd:sequence>       <xsd:element ref="location" minOccurs="1"       maxOccurs="unbounded"/>     </xsd:sequence>   </xsd:complexType> </xsd:element> 

I used ref to refer to the element <location> as Ill define it in the next block of declarations.

The <location> element contains an attribute locationName so it is automatically a complexType element. The attribute is of string type. The <location> element contains the child element <photo> . This element must occur at least once but can appear an unlimited number of times inside the <location> element.

 <xsd:element name="location">   <xsd:complexType>     <xsd:sequence>       <xsd:element ref="photo" minOccurs="1" maxOccurs="unbounded"/>     </xsd:sequence>     <xsd:attribute name="locationName" type="xsd:string"/>   </xsd:complexType>   </xsd:element> 

The final block will deal with the <photo> element. Each <photo> element has two attributes: filename and caption and contains only text. An element with an attribute is automatically a complexType element, but because it only has text content, it is a simpleContent element. The text is string information.

 <xsd:element name="photo">   <xsd:complexType>     <xsd:simpleContent>       <xsd:extension base="xsd:string">         <xsd:attribute name="filename" type="xsd:string"/>         <xsd:attribute name="caption" type="xsd:string"/>       </xsd:extension>     </xsd:simpleContent>   </xsd:complexType> </xsd:element> 

The following listing shows the complete schema. You can also see it in the resource file photoGallerySchema.xsd .

 <?xml version="1.0"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">   <xsd:element name="photoGallery">     <xsd:complexType>       <xsd:sequence>         <xsd:element ref="location" minOccurs="1"         maxOccurs="unbounded"/>       </xsd:sequence>     </xsd:complexType>   </xsd:element>   <xsd:element name="location">     <xsd:complexType>       <xsd:sequence>         <xsd:element ref="photo" minOccurs="1" maxOccurs="unbounded"/>       </xsd:sequence>       <xsd:attribute name="locationName" type="xsd:string"/>     </xsd:complexType>   </xsd:element>   <xsd:element name="photo">     <xsd:complexType>       <xsd:simpleContent>         <xsd:extension base="xsd:string">           <xsd:attribute name="filename" type="xsd:string"/>           <xsd:attribute name="caption" type="xsd:string"/>         </xsd:extension>       </xsd:simpleContent>      </xsd:complexType>  </xsd:element> </xsd:schema> 

There are other ways that I could have arranged the declarations in the schema. For example, instead of using ref , I could have nested the element declarations within their parent elements. Thats often referred to as a Russian Doll arrangement.

Linking the schema with an XML document

The final job is to link the schema with the photoGallery.xml file by adding a reference in the root element. Ive done this in the resource file photoGallerySchema.xml . The root element in photoGallerySchema.xml has changed to

 <photoGallery xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="photoGallerySchema.xsd"> 

Figure 3-39 shows the completed file in XMLSpy, validated against the schema.

Figure 3-39: The complete file photoGallerySchema.xml displayed in XMLSpy