4.2 FMPXMLRESULT SchemaGrammar | FileMaker Pro 6 Developers Guide to XML/XSL (Wordware Library for FileMaker)

4.1 FMPXMLLAYOUT Schema/Grammar

This simple example of the FMPXMLLAYOUT grammar uses the database Contact Management.fp5, which can be found in the FileMaker Pro 6 Folder, FileMaker Templates. Sections of the grammar are interspersed with the XML results on the following pages to show the kinds of information returned for one layout, "Form - Main Address", in the database. The FMPXMLLAYOUT grammar defines the standard for this kind of document and is available only with FileMaker Pro custom web publishing. You can read more about setting up FileMaker Pro for custom web publishing in Chapter 5. The example HTTP request to the Contact Management.fp5 database in the following example uses -format=-fmp_xml and the -view action. Replace the "localhost" domain with your IP address or server name and port, if necessary:

 http://localhost/fmpro?-db=Contact%20Management.fp5&-lay=Form%20-   %20Main%20Address&-format=-fmp_xml&-view

The definition for the FMPXMLLAYOUT grammar to create the result begins:

 <!DOCTYPE FMPXMLLAYOUT [       <!ELEMENT FMPXMLLAYOUT (ERRORCODE, PRODUCT, LAYOUT, VALUELISTS)>             <!ATTLIST FMPXMLLAYOUT xmlns CDATA #REQUIRED>

The first line declares the document type to be FMPXMLLAYOUT. The next line defines the first or root element to be named FMPXMLLAYOUT. This element has four children: ERRORCODE, PRODUCT, LAYOUT, and VALUELISTS. The FMPXMLLAYOUT element has one required attribute, xmlns, which has a value and is composed of character data (CDATA).

The first two lines in the XML result from the HTTP request to Contact Management.fp5 show the results:

 <?xml version="1.0" encoding="UTF-8" ?> <FMPXMLLAYOUT xmlns="http://www.filemaker.com/fmpxmllayout">

This well-formed result begins with the XML document prolog. This prolog conforms to the standard by including the version attribute with a value of "1.0". The prolog also specifies the language-encoding attribute, which shows that the document conforms to the UTF-8 character set. The prolog is followed by the opening root element of the document, FMPXMLLAYOUT, with the xmlns (XML Name Space) attribute. The xmlns is not a real link to anywhere but a unique identifier for this type of document. Namespaces are discussed more fully in Chapter 7.

The grammar continues to define the first child element of the root element ERRORCODE. This element is never empty and contains parsed character data:

 <!ELEMENT ERRORCODE (#PCDATA)>

An error code is returned and is 0 (zero) if the request encountered no problems. The error code is the same error code produced by the database if you have a script error. You can find a list of errors in FileMaker Pro Help under the topic "Status(CurrentError)." Specific Web Companion errors are discussed in section 5.5, "Error Codes for XML."

The XML result shows:

 <ERRORCODE>0</ERRORCODE>

The second child element of FMPXMLLAYOUT root element is defined in the grammar:

 <!ELEMENT PRODUCT EMPTY>       <!ATTLIST PRODUCT             NAME CDATA #REQUIRED             VERSION CDATA #REQUIRED             BUILD CDATA #REQUIRED>

This element, PRODUCT, is an empty element but contains the three required attributes describing the application programming interface (API) that created the document. The API, which published this XML from the database, is the Web Companion. The attribute BUILD lists the date of the product, followed by the NAME and VERSION attributes. Depending upon what version of FileMaker Pro you are using to web publish, you may get one of the following results:

 <product build="8/3/2000" name="FileMaker Pro Web Companion"   version="5.0v6" /> <PRODUCT BUILD="03/09/2001" NAME="FileMaker Pro Web Companion"   VERSION="5.5v1" /> <PRODUCT BUILD="5/4/2002" NAME="FileMaker Pro Web Companion"   VERSION="6.0v1" />

4.11 Layout Information

The third child element of FMPXMLLAYOUT is defined with one child element and two attributes:

 <!ELEMENT LAYOUT (FIELD*)>       <!ATTLIST LAYOUT             DATABASE CDATA #REQUIRED             NAME CDATA #REQUIRED>

The next portion of the result from the XML request, as shown in Listing 4.1, shows the LAYOUT element, followed by the required DATABASE attribute with the name of the database as the value of the attribute. The required NAME attribute has the name of the layout as its value. The definition for the LAYOUT element specifies its child element, FIELD, to be a repeated element zero or more times (∗). The FIELD elements are listed between the LAYOUT start and end markup. The number of field elements returned depends upon the number of elements on the layout in the HTTP request.

Listing 4.1: Layout and field information results

 <LAYOUT DATABASE="Contact Management.fp5" NAME="Form - Main Address">       <FIELD NAME="First Name">             <!-- code snippet for brevity, see Listing 4.2             for full code -->       </FIELD> </LAYOUT>

If the layout has no fields on it, the LAYOUT element is returned as an empty element. Create a new layout and do not place any fields on it. The following shows the request to the layout "blank" and the XML fragment result:

 http://localhost/fmpro?-db=Contact%20Management.fp5&-lay=blank&-format=   -fmp_xml&-view <LAYOUT DATABASE="Contact Management.fp5" NAME="blank" />

Warning

Fields placed on a layout by a copy-drag from a field with a value list will include the previous value list. If the value list is deselected in the new field, the old value list is still returned in the XML result. If you plan to use the FMPXMLLAYOUT information, place a field on a layout by choosing Insert, Field from the menu or by dragging the Field tool from the status area. Then format any fields individually to a specific value list.

4.12 Field Information

Each FIELD element has one required child element and one required attribute, the name of the field:

 <!ELEMENT FIELD (STYLE)       <!ATTLIST FIELD       NAME CDATA #REQUIRED>

The STYLE element is an empty element that has two attributes, TYPE and VALUELIST. This element describes how the field is formatted on the layout and if it has an associated value list. The pop-up list value for field "Address Type 1" in Listing 4.2 is "Address Type List". On another layout, "Form - Similars" in the Contact Management.fp5 database, some of the fields are plain "edittext" and others are formatted with a radio button value list "Similarity Criteria". The definition for the STYLE element is shown here:

 <!ELEMENT STYLE EMPTY>       <!ATTLIST STYLE             TYPE (POPUPLIST | POPUPMENU | CHECKBOX | RADIOBUTTONS |               SCROLLTEXT | SELECTIONLIST | EDITTEXT) #IMPLIED               VALUELIST CDATA #IMPLIED>

Listing 4.2: Fields formatted on a layout

 <LAYOUT DATABASE="Contact Management.fp5" NAME="Form - Main Address">       <FIELD NAME="First Name">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Company">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Image Data">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Title">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Phone 1">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Phone 2">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Email">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Notes">             <STYLE TYPE="SCROLLTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Similars Tab Label">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Street 1">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Address Type 1">             <STYLE TYPE="POPUPLIST" VALUELIST="Address Type List" />       </FIELD>       <FIELD NAME="City 1">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="State Province 1">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD>       <FIELD NAME="Postal Code 1">             <STYLE TYPE="EDITTEXT" VALUELIST="" />       </FIELD> </LAYOUT>

The TYPE attribute can have any of the values listed in the DTD. The "∣" (pipe) symbol means any of the values may be used in the attribute list. If a field is formatted as a standard field with "Include vertical scrollbar" checked, the TYPE attribute would have a value of "SCROLLTEXT". Any standard field (including merge fields) will have a TYPE value of "EDITTEXT". The value of the TYPE attribute "SELECTIONLIST" is not currently used. The standard value list formats for fields on a layout are pop-up list, pop-up menu, check boxes, and radio buttons. The fields with a value list will also show the name of the value list in the VALUELIST attribute.

4.13 Merge Fields

Single merge fields placed on the layout are listed in the FMPXMLLAYOUT result as EDITTEXT along with fields in the standard format. Multiple merge fields together in a single block may not all be listed in the resulting XML. If multiple merge fields are listed, they may not be in the order in which they appear on the layout. Other variables determine which merge field is used, if any, in the XML result.

Exercise 4.1: Create Merge Fields for FMPXMLLAYOUT

Create two new calculated fields:

 RecCt (Unstored) = Status(CurrentRecordCount) FndCt (Unstored) = Status(CurrentFoundCount)

Place the two new fields on any layout as merge fields in one block of text:
```
 Found <<FndCt>> of <<RecCt>> Records 
```

Make the same HTTP request to the web published FileMaker Pro and get a result in your browser. Only the first merge field, "FndCt", is returned in the XML, and it is shown as "EDITTEXT" style type:

 http://localhost/fmpro?-db=Contact%20Management.fp5&-lay=   Form%20-%20Main%20Address&-format=-fmp_xml&-view <!-- result --> <FIELD NAME="FndCt">       <STYLE TYPE="EDITTEXT" VALUELIST="" /> </FIELD>

4.14 Value List Information

The final child element of FMPXMLLAYOUT is VALUELISTS. This element is defined to have one child element, VALUELIST (not required), and no attributes.

 <!ELEMENT VALUELISTS (VALUELIST)*>

If there are no fields formatted with value lists, this element may be empty in the XML results.

 <VALUELISTS />

The element VALUELIST has one child element and one required attribute, the name of the value list. The VALUELIST element may be repeated in the XML result for each unique value list on a layout.

 <!ELEMENT VALUELIST (VALUE)*>       <!ATTLIST VALUELIST NAME CDATA #REQUIRED>

The VALUE element may contain any parsed character data and be repeated in the XML result for each value in the VALUELIST. All of the value list information for this layout is shown in Listing 4.3.

 <!ELEMENT VALUE (#PCDATA)>

Listing 4.3: Value list FMPXMLLAYOUT results

 <VALUELISTS>       <VALUELIST NAME="Address Type List">             <VALUE>Home</VALUE>             <VALUE>Business</VALUE>             <VALUE>Home Office</VALUE>             <VALUE>Vacation</VALUE>             <VALUE>-</VALUE>       </VALUELIST> </VALUELISTS>

4.15 Completing the FMPXMLLAYOUT DTD

The FMPXMLLAYOUT definition closes with "]>". The full schema/ grammar/DTD is shown in Listing 4.4.

Listing 4.4: FMPXMLLAYOUT Document Type Definition

 <!DOCTYPE FMPXMLLAYOUT [       <!ELEMENT FMPXMLLAYOUT (ERRORCODE, PRODUCT, LAYOUT, VALUELISTS)>             <!ATTLIST FMPXMLLAYOUT                   xmlns CDATA #REQUIRED>             <!ELEMENT ERRORCODE (#PCDATA)>             <!ELEMENT PRODUCT EMPTY>             <!ATTLIST PRODUCT                   NAME CDATA #REQUIRED                   VERSION CDATA #REQUIRED                   BUILD CDATA #REQUIRED>       <!ELEMENT LAYOUT (FIELD*)>             <!ATTLIST LAYOUT                   NAME CDATA #REQUIRED                   DATABASE CDATA #REQUIRED>             <!ELEMENT FIELD (STYLE)>                   <!ATTLIST FIELD                         NAME CDATA #REQUIRED>                   <!ELEMENT STYLE EMPTY>                         <!ATTLIST STYLE                               TYPE (POPUPLIST | POPUPMENU | CHECKBOX                                 | RADIOBUTTONS | SCROLLTEXT |                                 SELECTIONLIST | EDITTEXT) #IMPLIED                               VALUELIST CDATA #IMPLIED>       <!ELEMENT VALUELISTS (VALUELIST)*>             <!ELEMENT VALUELIST (VALUE)*>                   <!ATTLIST VALUELIST                         NAME CDATA #REQUIRED>                   <!ELEMENT VALUE (#PCDATA)> ]>

4.16 FileMaker Pro Report/Layout Information

Some of the information found in a database layout can be collected using FileMaker Pro built-in design and status functions. Status(CurrentError), FieldNames(Status(CurrentFileName)), Status(CurrentLayoutName), and FieldStyle(database, layout, field) are all example functions of some of the information about a layout. A calculation field or a scripted set field can show the results of these functions. This layout information can be used in various ways in the database or for reports on the structure of the database. These fields could also be used when transforming the XML data with a stylesheet instead of requesting the FMPXMLLAYOUT results.

Some information can be returned using the FMPXMLLAYOUT schema. The way the fields are formatted on the layout may be used to recreate the style type in another display, such as the browser. Value list information is most useful if the XML results are used in a FORM submit field to allow editing of the contents of a field. Value lists are a useful way to restrict data entry. There are several ways to display value lists in the browser. Browser value lists correlate to the formats that FileMaker Pro uses on the layout and are described in Chapter 6.