Spry XML Primer

One of formats of data that Spry accepts is XML. The Spry XML Data set was the first type of data that Spry used when it was released. This document will present an overview of setting up XML for use with Spry. It will have tips and tricks for generating proper XML from the start.

The important points of this document:

XML nodes are case sensitive.
Valid XML will display properly in browsers. If it works in the browser, it should work for Spry.
Special characters must be encoded or wrapped in CDATA
XML docs need to be served as 'text/xml' or 'application/xml'.

What is XML?

XML stands for eXtensible Markup Language. This is a flexible yet strict method of storing and transmitting data. Flexible in that the user can create the format and node names in any way they please; strict in the sense that XML has a strict set of rules for structure: required closing tags and case sensitivity for instance.

XML is a tree structure of nodes and nested nodes of information, with the user defining the names of the nodes.

A basic XML file looks like this:

<?xml version="1.0" encoding="utf-8"?>
   <employees xmlns="http://www.foo.com/employees">
     <employee id="120585">
       <lastname>Jones</lastname>
       <firstname>John</firstname>
       <phone>(415) 333-9345 </phone>
       <username>jjones</username>
    </employee>
    <employee id="127493">
       <lastname>Brown</lastname>
       <firstname>Joe</firstname>
       <phone>(415) 333-5938 </phone>
       <username>jbrown</username>
    </employee>
  </employees>

Line 1 is the XML declaration. It specifies the version of the XML and the encoding of the document. The encoding tells the browser which language is being used in the XML. Using UTF-8 is a good choice unless you have specific language needs.

"Employees" is the top level node. This defines the start of the user specified content. All top level node tags must have a closing tag. Notice that the last line of the XML file is the closing </employees> tag.

Within the <employees> block is the repeating <employee> node. This is where the bulk of the actual data is kept. The user defines the actual names of the nodes. Important: Node names are case sensitive. This is important to keep in mind when using Spry data references. If the node is <employee>, the data reference needs to be {employee}. If the node was <Employee>, the data reference needs to be {Employee}. If the node was uppercase and the data reference was lowercase, it will fail.

Adding Data

Notice there are 2 places to put data:

In the node, like <lastname>Jones</lastname>. "Jones" is the value of the node.
As an attribute of a node. In <employee id="120585">, 'id' is an attribute of a node. The attribute name is 'id' and the value of the attribute is '120585'.

This node/value structure works well for simple data. If the data is more complex, meaning it has many special characters or perhaps HTML markup, then these nodes need to be wrapped in a CDATA container or be entity encoded. For example, if the value of a node was: ' 6 > 5 and 5 < 6', the XML parser (the browser or Spry) will get confused since it would think that the '><' characters are opening or closing tags. This would cause a parsing error and the XML is therefore invalid.

There are two ways to handle this.

The first is to entity encode the special characters. Each special character has its own character pattern that is used to display the character in the browser. For instance. the '<' character can also be written as < or <. This way the above sample can be written '6 > 5 and 5 < 6'. This should be parsed correctly.

The second way is to wrap the value in CDATA. This is done like <formula><![CDATA[ 6 > 5 and 5 < 6]]></formula>. CDATA tells the parser to ignore everything within the CDATA tag. This way, you can have HTML markup and any number of special characters within the value of the node.
Note the structure of the CDATA tag: < ! [ CDATA [ your code ] ] >

Dynamically Generating XML

Frequently, users will want to generate XML using information from a database. This is useful when the data changes frequently. Spry can take data from an XML page or any page that can generate valid XML. This can be done, for instance, with ASP, PHP or Coldfusion application servers. We have a series of code samples that show how to convert database queries into XML.

Using server side functionality brings up an important web concept: that of 'content-type'. Content type is a message to the browser that tells it what kind of content is on the page. By default, the content type is 'text/plain'. This tells the browser that it is plain text that requires no special processing. Most web pages have a content type of 'text/html'. This tells the browser that the content is HTML code and the browser knows how to handle it.

Browser also have default content types determined by the file extension. These are MIME types. So a browser will know that a PHP page is serving HTML content. When serving up XML content via these server side technologies, it is vital that you tell the browser that the content is actually XML. To do this, we need to send a header that says that the content type is XML. Notice in the file linked above that each code sample has a content type header that is sent along.

PHP: header('Content-type: text/xml');
ASP: Response.ContentType = "text/xml"
Coldfusion: <cfheader name="Content-type" value="text/xml">

This will ensure that the browser will parse the content as valid XML. Otherwise, it will be seen as plain text and may not work properly. When making a dynamic source for Spry, it's a good idea to simply view the page in a browser. It will be obvious when a XML file is being parsed correctly. If it works in the browser, it should work in Spry.

One other concern with dynamic feeds is making sure that the browser (or server) does not cache the data. Browser or server caching will prevent the latest data from reaching Spry. To prevent this, set the headers for:

Cache-Control
Expires
Pragma

Check the Query to XML sample for examples.

http://juicystudio.com/article/content-negotiation.php is a good article that further explains content type.

For further information about XML, check out http://www.xmlfiles.com/xml/