Formatting XML

Before we go over the basic rules and formatting of XML, you should know that you will want to use a text editor such as Notepad for building the XML files. Also, XML files can be opened in a browser such as Internet Explorer 5 (or better) of FireFox and will show errors in the form, so it is good to test your XML in browsers first to make sure it is well formed.

Here is a basic snippet of XML:

 <root>      <sample>           the stuff      </sample> </root> 

The first thing you will notice in this XML is that XML uses tags. If you are familiar with HTML, you know what tags are. If you are not familiar with HTML, tags describe the data held between them. If the data in between the tags is supposed to be a title, you would use the tags <title> and </title> on either end of the data. And in XML lingo, these tags with their data are called elements and that is how we will be referring to them. So you see, elements are data holders and the data they hold.

In the preceding snippet of code, you see that the first element, <root> has a sub-element, <sample>, which then contains some data. And that's XML really, just a bunch of tags and data. Of course, it can get more complicated, and we will be going over how to extend the elements and data later in the chapter.

Notice that the structure of the XML is very tree-like with its hierarchy. As we continue to move forward in building out the XML documents, you will begin to see the structure more easily.

That small example showed you the basic layout. Now we will create a larger XML document, and then discuss some of the rules for XML.

Here is the code that you should type into a text editor such as Notepad or SciTe. (Or you could get it from the website.) Save this code as team1.xml.

   <team>      <player>           <name>Paul</name>           <number>15</number>           <position>Point Guard</position>      </player>      <player>           <name>Matt</name>           <number>21</number>           <position>Small Forward</position>      </player>      <player>           <name>Doug</name>           <number>33</number>           <position>Center</position>      </player>      <player>           <name>Todd</name>           <number>51</number>           <position>Power Forward</position>      </player>      <player>           <name>Eddie</name>           <number>11</number>           <position>Shooting Guard</position>      </player> </team> 

And to make sure everything is fine with your XML file, open it in a browser, and you should see a layout similar to Figure 24.1.

Figure 24.1. XML viewed in FireFox will help weed out possible bugs or typos in making sure your document is well formed.

You can use the handles on the left side of the elements to collapse or expand their substructure.

Now that you have a better idea of the structure of XML, it's time to go over some basic rules.

Rules of XML

There are several rules to creating well-structured XML. And it is very important that your XML be as perfect as possible when bringing it into Flash. The first rule concerns the first line in the document.

XML Declaration

Although we have not yet done so in our XML, it is good practice to put a line of code in the beginning that declares what the document is, and what version the document is in.

The declaration line looks like this:

 <?xml version="1.0"?> 

Notice that the line may look like an XML element, but in fact, it is not; it is a processing instruction because of the <? ?> surrounding it. It is used to tell the browser or parser that the content is XML, and should be viewed that way.

From here on out, all of our XML documents will have this line in it.

Open-and-Shut Case

Another rule that you may have noticed we are already implementing is that all elements that open must also close. Notice in our last example each new element started with a <team> tag and ended with a </team> tag.

Here is an example of an element:

 <name>David</name> 

There are elements that open and close in one single tag, and they are called empty elements, meaning they do not have any data, or sub-elements.

Here is an example of an empty element:

 <empty/> 

The difference is that instead of the closing slash being at the front, it is at the end of the element name.

No Overlapping

HTML is pretty soft when it comes to elements being within other elements, and the order in which they close. XML, however, is not. If you open a child element within a parent element, the child element must be closed before the parent element is closed.

Here are two examples of what I mean:

 <parent><child>this is legal</child></parent> <parent><child>this is not legal</parent></child> 

The latter of the two lines of code will produce an error because it is not permitted.

Those are a couple of rules about how the elements work; there are also naming convention rules associated with elements.

Element-Naming Conventions

The elements themselves do have some rules and guidelines to follow when creating them.

• Element names, much like variables in Flash, are case sensitive, meaning that element, ELEMENT, and Element are completely different elements.

• Element names must begin with a letter or an underscore.

• Element names cannot begin with a number or a special character (@,#).

• Element names cannot begin with "xml" in upper- or lowercase.

• Element names cannot have spaces in them (you will see why when we discuss attributes).

Commenting XML

Not all information in an XML document has to be elements or data within elements: XML does support the use of comments. Comments in XML have the same syntax as comments in HTML.

Here is an example of a comment found in an XML document

 <!here lies a comment> 

They are not allowed to be within tags, however, so the following code is illegal:

 <team <!this won't work> >data</team> 

The preceding code will cause errors.

There is another part of XML we have yet to cover: attributes.

Attributes

Those familiar with HTML know what attributes are. They are snippets of data stored within tags (or in this case, within elements). They are used to distinguish between elements of the same name. After the element name, use a space, then the attribute name followed by equal signs "=" and the attribute value in quotes.

Here is an example of using attributes:

 <root>      <element number="1">stuff</element>      <element number="2">more stuff</element> </root> 

Notice that you still close the element with the element name only.

You can also put multiple attributes in a single element separated by spaces like this:

 <element number="1" name="David" type="author">stuff</element> 

And empty elements can also have attributes.

 <element style="none" color="blue"/> 

No Duplicating Attributes

There is one strict rule for attributes; they cannot be duplicated in the same element.

Here is an example of an illegal use of attributes:

 <element number="1" number="2">stuff</element> 

The preceding code cannot be used in well-formed XML documents.

Now that you understand attributes, we can revisit the XML document we created earlier.

Here is the first of two new versions of the team XML document. Save this one as team2.xml.

 <?xml version="1.0"?> <team>      <player name="Paul">           <number>15</number>           <position>Point Guard</position>      </player>      <player name="Matt">           <number>21</number>           <position>Small Forward</position>      </player>      <player name="Doug">           <number>33</number>           <position>Center</position>      </player>      <player name="Todd">           <number>51</number>           <position>Power Forward</position>      </player>      <player name="Eddie">           <number>11</number>           <position>Shooting Guard</position>      </player> </team> 

The preceding code removes the child element <name> and creates a name attribute in the player element. You can immediately see the benefits of using attributes: Now when you look through the player elements, you can see which one is which immediately without having to look to its child node. Also notice that we now include the XML declaration line in the beginning. You can see the output of this XML document in the browser in Figure 24.2.

Figure 24.2. Use attributes to help identify multiple elements.

Here is another version of the team XML document. Save it as team3.xml.

 <?xml version="1.0"?> <team>      <player name="Paul" number="15" position="Point Guard"/>      <player name="Matt" number="21" position="Small Forward"/>      <player name="Doug" number="33" position="Center"/>      <player name="Todd" number="51" position="Power Forward"/>      <player name="Eddie" number="11" position="Shooting Guard"/> </team> 

In this version, we removed all the child elements and replaced them with attributes in the player elements. Also notice that all of the player elements are empty elements. You can see the output of this document in the browser in Figure 24.3.

Figure 24.3. You can have all attributes and no child elements, and the document is still well-formed.

Now you have seen elements and attributes, but you might be confused as to which to use when.