Adobe AIR article

Building an XML viewer on AIR with Flex

Understanding structured documents

Before I get into the design of the viewer, I'd like to explore the domain of structured documents. If you are already familiar with structured documents and how they are represented in XML, you can skip to the section titled Producing the Flex application

What are structured documents?

Every document you read has an implicit structure, that is conveyed via formatting and layout (see Figure 2). We are so used to these formatting and layout conventions that we hardly have to think about this. For example, we expect chapters to begin on a new page, and if there's a line of text at the top of the page in a bold font and larger size, we automatically deduce that's a chapter title. We recognize section titles in a similar way, and we know that if text in a paragraph is in italics, it probably has a special meaning.

Figure 2. Every document has an implicit structure.

The term structured documents is used when the structure of the document is made explicit. Instead of using formatting and other visual cues, the content in a structured document is tagged to indicate the purpose of that element (for example, "this is a series of instructions", or "this is the title of this section"). The content of the document (text, graphics, and so on) is organized into a hierarchy of elements and attributes, and the rules dictating how the content is tagged and organized are described in a schema or Document Type Definition (DTD) as shown in Figure 3.

Figure 3. An example of a structured document.

Years ago, it was common in certain industries (such as aerospace) to represent structured documents in SGML. But it was only with the introduction of XML (and all the associated tools to support processing XML, such as XSLT) that it became cost-effective for structured authoring to gain broad adoption.

Advantages of structured documents

There are many advantages to structuring your documents, including:

• Formatting is separated from content. Because elements are tagged according their meaning, a template can be produced that maps the elements to formatting. This helps provide consistent formatting across a document, and relieves the author of the task of assigning formatting manually. It also means that any changes to the formatting can be accomplished by just changing the template, without any reworking of the document content. This allows many different templates to be used to produce different types of output from the same source (for example, one template for PDF, one for HTML, one for mobile devices, and so on). This technique is also known as single-source, multichannel publishing. Conversely, the content can be edited and then reflowed into the template. This is extremely useful in translation workflows (because it eliminates the manual task of reformatting localized content), and with documents that are often being updated (for example, user manuals).
• Manipulation of the content can be automated. Because the content is tagged and organized into a predictable hierarchy of elements, you can write scripts to intelligently process the document, to filter, reorganize, or combine new content as required.
• Metadata is explicitly represented in a standard way. By using attributes on elements to represent metadata, you can be smart on filtering content, such as identifying all elements tagged with a specific model number or skill level.

Creating a structured document

To create a structured document, you'll need:

• A DTD or Schema that determines the information architecture of your document (that is, the rules for which elements and attributes can be used and how they can be organized)
• A template that maps formatting to elements and attributes
• An authoring environment that:
• Lets you author your content in an element hierarchy
• Lets you add attributes to elements
• Understands and validates against the DTD

Creating the UserGuide.xml example structured document

In this example, I used Adobe FrameMaker to author the structured document. However the origin of the XML file is immaterial to the viewer application. This is an advantage of using structured documents and XML: Your authoring environment and your publishing environment can be isolated from each other, allowing you to change your authoring environment or support multiple authoring tools without affecting the downstream publishing environment.

All that matters to the viewer application is that the XML is valid, meaning that it conforms to the rules in the DTD or Schema. The DTD is the specification of the data format to which both the authoring environment and the publishing environment conform. To keep the viewer code short and simple, you can assume the XML data is valid according to the DTD. If the XML wasn't valid, then the viewer would not recognize the elements or attributes, or those elements or attributes would not be in the hierarchy the viewer would expect. In a production environment, you would either have to introduce a process to ensure only valid XML was provided to the viewer, or you would need to build a validation function (and corresponding exception handling) into the viewer.

For UserGuide.xml, I will use a DTD of my own design (UserManual.dtd, which is in the src/assets folder of the ZIP file that accompanies this article).

Note: I could have gone with an industry-standard DTD or Schema (for example, DocBook or DITA), but the DTD is use for this article strikes a good balance by being complex enough to represent a working scenario without being as complex as one of the industry-standard DTDs.

UserGuide.xml, which is also part in the src/assets folder of the ZIP file that accompanies this article, contains text that is tagged and organized into a hierarchy of elements, and it represents product information on some sunglasses. Attributes are also provided on some elements providing additional information. The data references a number of external graphics. In this example, those graphics are in the SWF format, created using Adobe Illustrator and Adobe Flash.

Page 2 of 5

Previous Page

Next Page