FileMaker and XML

Before you can appreciate FileMaker's Web service capabilities, you need to learn more about the things FileMaker can do with XML data. To put it briefly , FileMaker can both import and export data as XML. This capability has several interesting uses: For one thing, it means FileMaker can participate in Web services transactions, as you'll see in this chapter. For another, it means FileMaker can exchange data with other applications via XML. Before we delve deeper, though, a brief overview of XML may be useful.

The Basics of XML

XML is a large topic, on which many books have been written. We'll have to content ourselves with a quick overview; you can find further reading suggestions in Appendix A.

XML is a text-based means of representing data, which is at the same time rich and portable . By "rich," we mean that the data is more than mere text: An XML document is capable of describing its own structure, so that in looking at an XML document you can tell a chapter heading from a bullet point, or a personnel ID from a health-insurance deductible. By portable , we mean that XML documents are stored as plain text and can be read by a wide variety of programs on a wide variety of computers and operating systems.

As an example, consider the XML document that appears in Listing 22.1. This is a short document containing information about motors. You'll notice the document is full of tags (called markup ) that might look superficially familiar to you if you've seen some HTML before. You'll notice that the tags always occur in pairs, with some content between them, and you'll notice that the tags seem to describe the data they contain. These tag pairs are known in XML jargon as elements .

Listing 22.1. A Small XML File Containing Motor Data

 <?xml version="1.0" encoding="UTF-8" ?> <motors>     <motor>         <model>Rotary 17</model>         <weight>1200</weight>         <part_number>M3110A-3</part_number>         <volume>312</volume>     </motor> </motors> 

This XML document is rich, in the sense that it contains two kinds of information: It contains raw data, but it also contains tags telling a reader what the data means . In this document, M3110A-3 is not just a string of numbers and letters ; it's specifically a part number.

The document is also portable in the sense that it's stored as plain text, meaning you don't need a special "motor processing" application to read it. Any tool or program that can read plain text can work with this data.

XML documents have to follow some simple rules. Each must begin with an XML declaration, like the first line of Listing 22.1. Each must have a single outermost, or "document," element ”in Listing 22.1, the document element is called motors . Each tag must be properly closed ”if you have a <model> tag, you'd better have its closing counterpart , called </model> . And, although tags may be nested (for example, in Listing 22.1, the weight element is completely enclosed within the motor element), it is not permissible for tags to overlap. Therefore, something like

 <model>Rotary<weight>500</model></weight> 

would not be allowed, because the weight tag, rather than being completely enclosed in the model tag, instead overlaps it.

XML documents that follow these few simple rules, as well as some rules about allowable characters , are said to be well- formed .

NOTE

XML is a rigorous standard, with plenty of technical documents that describe it in exact detail. In this book we opt for clarity over rigor, so we encourage you to get hold of additional resources to explore the full details of XML concepts such as well- formedness . The description we've given is fairly complete, but the last word can be found at http://www.w3.org/TR/2004/REC-xml-20040204/#sec-well-formed.

FileMaker's XML Grammars

XML syntax rules, as you may have noticed, don't say anything about how to mark up your data. XML doesn't force you to use a motor element when talking about motors, nor would it specify what other elements a motor element should contain. If you're designing an XML document, the exact structure of the document, as far as what data it contains and how that data is marked up, remains up to you, the designer.

FileMaker is capable of presenting its data as XML, and when it does so, it uses its own, FileMaker-specific set of elements to describe its data. FileMaker can actually present its data in either of two XML structures, called grammars ; you, as the user or developer, get to choose which one suits your current situation best.

Exporting FileMaker Data as XML: The FMPDSORESULT Grammar

Suppose you have some product data in a FileMaker table, which looks like Figure 22.2.

Figure 22.2. Some sample "widget" data in a FileMaker table.

To export these records as XML, choose F ile, E xport Records, then choose a file type of XML in the following dialog. When you do this, before seeing the familiar Export dialog, you see an XML options dialog, as shown in Figure 22.3.

Figure 22.3. FileMaker's XML/XSL export options dialog.

Here you can choose which of FileMaker's XML "grammars" to apply. (You can also apply an XSL stylesheet to the output, which is an important topic we'll deal with in its own section later in this chapter.) If you're trying this for the first time, you might want to choose FMPDSORESULT . From there, you'll see the familiar Export dialog, where you can choose which fields to export, and in what order.

If you open the resulting exported file, you'll see something like the document in Listing 22.2.

Listing 22.2. Records Exported Using FileMaker's FMPDSORESULT Grammar

 <?xml version="1.0" encoding="UTF-8" ?> <!-- This grammar has been deprecated - use FMPXMLRESULT instead --> <FMPDSORESULT xmlns="http://www.filemaker.com/fmpdsoresult">   <ERRORCODE>0</ERRORCODE>   <DATABASE>Widget.fp7</DATABASE>   <LAYOUT/>   <ROW MOD RECORD>     <WidgetID>W1</WidgetID>     <Description>Medium Frobisher</Description>     <Color>Mauve</Color>     <Weight>12.2</Weight>   </ROW>   <ROW MOD RECORD>     <WidgetID>W2</WidgetID>     <Description>Gosset Socketeer</Description>     <Color>Red</Color>     <Weight>4</Weight>   </ROW>   <ROW MOD RECORD>     <WidgetID>W3</WidgetID>     <Description>Triple Hex Ping Nut</Description>     <Color>Steel</Color>     <Weight>2.3</Weight>   </ROW> </FMPDSORESULT> 

FileMaker has applied its own XML structure to the exported data ”in this case the FMPDSORESULT structure. An FMPDSORESULT document has a document element (the top-level element) called <FMPDSORESULT> . That element in turn contains elements for ERRORCODE ( generally 0 unless there was some error in the export process), for DATABASE (to tell us which database file the data was drawn from) and LAYOUT , as well as one <ROW> element for each record in the table from which we're exporting. The <ROW> elements in turn contain additional elements, named for the fields that were selected for export.

About the FMPDSORESULT Grammar

You might have noticed, in Listing 22.2, that the second line of the generated XML contains a warning: "This grammar has been deprecated ”use FMPXMLRESULT instead." Deprecation is a term used in computer languages to indicate that a language's designers are actively discouraging you from using an element or feature. This is generally because the language designers believe that newer features represent an improvement on the deprecated feature. The old feature continues to work (as does FMPDSORESULT in FileMaker 7), but you are discouraged from using it and encouraged to use a different or newer feature instead.

Although FMPDSORESULT is now formally deprecated, we chose to use it here anyway, because of its value in teaching XML. It's a verbose grammar that creates XML element names based on FileMaker field names . This makes it very easy for an XML novice to see how the FileMaker data maps onto the XML output, and this makes FMPDSORESULT a very useful teaching tool.

So what's wrong with FMPDSORESULT ? Three things, all of them tied to the fact that FileMaker generates the element names for this grammar directly from FileMaker field names. In the first place, if your FileMaker field names are of any length, the XML element names are similarly long, and the generated files can become massive. Second, the element structure of an FMPDSORESULT document obviously varies depending on the FileMaker field names that lie behind it. All such documents will have an FMPDSORESULT element, containing one or more ROW elements, but within each ROW element there's no way to predict what the sub-elements will be. This makes it impossible to validate these documents via a single Document Type Definition document, or DTD. (We don't deal with DTDs much in this book, but many XML environments and workflows make significant use of them, and the ability to conform to a single DTD is useful.)

The third and most serious problem with FMPDSORESULT , though, is that it can generate XML that is literally invalid. To take a simple example, XML element names may not begin with a number. There's no such restriction on FileMaker field names. A FileMaker file with a field named 2004Results will generate an FMPDSORESULT XML document with elements called <2004Results> . That's not a valid XML element name , and any XML parser that tries to process a document containing such a name will generate an error.

So, pay careful attention to the fact that this grammar is deprecated. Although we used it in this section for teaching purposes, we recommend that you begin using the FMPXMLRESULT grammar as soon as you feel comfortable with this more complex grammar.

Exporting FileMaker Data as XML: The FMPXMLRESULT Grammar

The FMPDSORESULT grammar is considered to be FileMaker's more "readable" export grammar. It's a bit more legible to humans , but it's not the one FileMaker uses most heavily. That honor is reserved for the other grammar, called FMPXMLRESULT . If you were to export the widget data as XML with this grammar, you'd see something like the document in Listing 22.3.

Listing 22.3. Data Exported Using FMPXMLRESULT Grammar

 <?xml version="1.0" encoding="UTF-8" ?> <FMPXMLRESULT xmlns="http://www.filemaker.com/fmpxmlresult">   <ERRORCODE>0</ERRORCODE>   <PRODUCT BUILD="01-07-2004" NAME="FileMaker Pro" VERSION="7.0v1"/>   <DATABASE DATEFORMAT="M/d/yyyy" LAYOUT="" NAME="Widget.fp7" RECORDS="3" TIMEFORMAT="h:mm  :ss a"/>   <METADATA>     <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="WidgetID" TYPE="NUMBER"/>     <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Description" TYPE="TEXT"/>     <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Color" TYPE="TEXT"/>     <FIELD EMPTYOK="YES" MAXREPEAT="1" NAME="Weight" TYPE="NUMBER"/>   </METADATA>   <RESULTSET FOUND="3">     <ROW MOD RECORD>       <COL>         <DATA>W1</DATA>       </COL>       <COL>         <DATA>Medium Frobisher</DATA>       </COL>       <COL>         <DATA>Mauve</DATA>       </COL>       <COL>         <DATA>12.2</DATA>       </COL>     </ROW>     <ROW MOD RECORD>       <COL>         <DATA>W2</DATA>       </COL>       <COL>         <DATA>Gosset Socketeer</DATA>       </COL>       <COL>         <DATA>Red</DATA>       </COL>       <COL>         <DATA>4</DATA>       </COL>     </ROW>     <ROW MOD RECORD>       <COL>         <DATA>W3</DATA>       </COL>       <COL>         <DATA>Triple Hex Ping Nut</DATA>       </COL>       <COL>         <DATA>Steel</DATA>       </COL>       <COL>         <DATA>2.3</DATA>       </COL>     </ROW>   </RESULTSET> </FMPXMLRESULT> 

The most obvious difference from the FMPDSORESULT grammar is that whereas FMPDSORESULT provides element names within each row that correspond to field names, FMPXMLRESULT wraps all the database data in generic-looking <COL> and <DATA> elements. There's also a <METADATA> element, which you can see contains sub-elements for each field that give a lot of information about the field, such as its data type, whether it's a repeating field, and whether it's allowed to be empty. The data within the <ROW> elements then matches up to the field descriptions in the <METADATA> section based on position: The value Mauve in the first row is the third data element, and when you consult the <METADATA> section you can see that this means it corresponds to the Color field.