Publishing FileMaker Data as XML

 <  Day Day Up  >  

Custom Web Publishing falls into two broad categories: CWP with XML and CWP with XSLT. The former technique allows you to publish FileMaker data as raw XML over the Web. The latter technique is XML-based as well, but involves applying additional transformations to the XML to turn it into other data formats such as HTML. Because XML publishing is the basis for both of these "flavors" of CWP, we begin with a thorough discussion of FileMaker data publishing with XML.

Introduction to XML Publishing

To publish FileMaker data as XML via the Web Publishing Engine, you need several things:

  • A Web server with the appropriate Web server module and the Administration Console installed.

  • A running copy of the Web Publishing Engine, with XML publishing enabled. (See the previous section, "Configuring the Web Publishing Engine.")

  • A copy of FileMaker Server Advanced that's configured to work with the Web Publishing Engine.

  • One or more FileMaker databases that are enabled for XML access via the appropriate extended privilege, and are being served by the server mentioned in the preceding bullet.

If ”and only if ”all these pieces are in place, you can draw XML data from a served database by opening a Web browser and entering a URL like the following:

http://192.168.100.101/fmi/xml/ fmresultset .xml?-db=Animal&-lay=web&-findall

This URL, 192.168.100.101, is the address of the Web server that we've configured to work with the Web Publishing Engine. The path to fmresultset.xml indicates that we want the results returned in the fmresultset grammar. URL also instructs the WPE to access a database called Animal, via a layout called Web, and then find all records and return them in the selected fmresultset grammar.

NOTE

Note that it's not necessary to include the filename suffix (.fp7) when referencing the database name in the URL.


If you indeed had a database called Animal open under FileMaker Server, and if it had privilege sets with the extended privilege for XML enabled, and it had a layout called Web, then the Web Publishing Engine would return an XML document to your browser. If you're using a browser capable of displaying XML (the major ones at the time of writing were later versions of Mozilla/Netscape and Internet Explorer 5 or later), you'd see something like the code in Listing 23.1.

Listing 23.1. XML Formatted with the fmresultset Grammar
 <?xml version="1.0" standalone="no"?> <!DOCTYPE fmresultset PUBLIC "-//FMI//DTD fmresultset//EN" "/fmi/xml/fmresultset.dtd"> <fmresultset xmlns="http://www.filemaker.com/xml/fmresultset" version="1.0">     <error code="0">     </error>     <product build="12/10/2003" name="FileMaker Web Publishing Engine" version="7.0v1" />     <datasource database="animal" date-format="M/d/yy" layout="web" table="Animal" graphics/ccc.gif time-format="h:mm:ss a" total-count="17" />     <metadata>         <field-definition auto-enter="no" global="no" max-repeat="1" name="date_birth" graphics/ccc.gif not-empty="no" result="date" type="normal" />         <field-definition auto-enter="yes" global="no" max-repeat="1" name="id_animal" graphics/ccc.gif not-empty="yes" result="text" type="normal" />         <field-definition auto-enter="no" global="no" max-repeat="1" name="id_father" graphics/ccc.gif not-empty="no" result="text" type="normal" />         <field-definition auto-enter="no" global="no" max-repeat="1" name="id_mother" graphics/ccc.gif not-empty="no" result="text" type="normal" />         <field-definition auto-enter="no" global="no" max-repeat="1" name="name" graphics/ccc.gif not-empty="no" result="text" type="normal" />         <field-definition auto-enter="no" global="no" max-repeat="1" name="weight_birth" graphics/ccc.gif not-empty="no" result="number" type="normal" />         <field-definition auto-enter="no" global="no" max-repeat="1" name="weight_current" graphics/ccc.gif not-empty="no" result="number" type="normal" />         <field-definition auto-enter="no" global="no" max-repeat="1" name="HerdID" graphics/ccc.gif not-empty="no" result="text" type="normal" />         <field-definition auto-enter="no" global="no" max-repeat="1" name="gender" graphics/ccc.gif not-empty="no" result="text" type="normal" />     </metadata>     <resultset count="17" fetch-size="17">         <record mod- record->             <field name="date_birth">                 <data>4/23/1994</data>             </field>             <field name="id_animal">                 <data>A1</data>             </field>             <field name="id_father">                 <data></data>             </field>             <field name="id_mother">                 <data></data>             </field>             <field name="name">                 <data>Great Geronimo</data>             </field>             <field name="weight_birth">                 <data>107</data>             </field>             <field name="weight_current">                 <data>812</data>             </field>             <field name="HerdID">                 <data>H1</data>             </field>             <field name="gender">                 <data>Male</data>             </field>         </record>         [ ... multiple additional records ...]     </resultset> </fmresultset> 

In general, when you want to access XML data from an appropriately-configured FileMaker file, you do so by entering a URL in the following format:

 

 <  protocol  >//<  server-ip  >[:<  port  >]/fmi/xml/<  grammar  >.xml?[<  query-string  >] 

Protocol indicates a Web protocol, either HTTP or HTTPS.

Server-IP is the IP address of the Web server that serves as the point of entry to the Web Publishing Engine. Note that if by chance the Web Publishing Engine is installed on a different machine from the Web server, you must specify the IP address of the Web server machine here ”providing the address of the Web Publishing Engine does not work.

Port is an optional part of the URL. In general, your Web server will be running on the default HTTP port of 80 or the default HTTPS port of 443. If for any reason you've configured your Web server to run on a different port than the protocol default, you need to specify that port number here. This port has nothing to do with any of the WPE-specific ports (in the 16000 range) or the FileMaker Server port (5003) that you may have encountered in the Web Publishing Engine documentation; it refers strictly to the port on which your Web server accepts incoming requests .

Grammar refers to one of three FileMaker xml grammars: FMPXMLRESULT , FMPXMLLAYOUT , or fmresultset .

NOTE

Note that only the first one of these is available via XML Export: the second two are available only via Custom Web Publishing. The FMPDSORESULT grammar that's available with XML Export is not available with Custom Web Publishing.


Query-string refers to a series of one or more specific pieces of information you pass to the Web Publishing Engine to form the substance of your request. Among the pieces of information you would pass in the query string are the name of the database to access, the name of the layout you want to work with, and the name of a database action (such as "find all records", expressed in the example URL by the -findall command).

In general, then, you'll use specially-formatted URLs to access FileMaker data as XML via Custom Web Publishing. These URLs can be manually entered in a Web browser, or they can be linked from a Web page, or they can be used by other processes or applications that want to consume FileMaker data as XML.

Understanding Query Strings

A lot of the action in a Custom Web Publishing URL occurs inside the query string ”that odd-looking set of commands at the end of the URL. Here again is the example URL from the previous section:

http://192.168.100.101/fmi/xml/fmresultset.xml?-db=Animal&-lay=web&-findall

The query string is the portion of the URL that comes after the question mark. A query string consists of multiple name-value pairs , with each name-value pair taking the form name=value . If there are multiple name-value pairs in a URL, additional pairs are separated from the first one by an ampersand character (&).

NOTE

Query strings are not peculiar to FileMaker or to Custom Web Publishing ”they're an HTTP standard for passing information to a server-side program via a URL.


In the example URL, we've passed three name-value pairs. Table 23.1 shows the names and their corresponding values.

Table 23.1. Name-value Pairs in a Sample CWP URL

Name

Value

Meaning

-db

Animal

Which FileMaker database to access

-lay

Web

Which layout in the specified database to use

-findall

(no associated value)

What action to perform


In general, any Custom Web Publishing URL needs to specify at least a database name, a layout name, and a database action to perform. (In fact, the database name and layout name can also be omitted in the case of a few specialized database actions). So at a minimum, you will usually provide a -db value, a -lay value, and the name of some database action.

A few more notes on query string syntax: The order of the name-value pairs within the query string doesn't matter, as long as all the required pairs are present. The initial dash (-)in the various names is significant, however, and can't be omitted. You'll notice that the database action consists of a name without a value (which is perfectly legitimate in an HTTP URL query string); database actions always consist of a name with no value attached.

graphics/troubleshooting_icon.jpg

If you have spaces in your field, layout, or database names, this will cause trouble. See "Dealing with Spaces" in the Troubleshooting section at the end of this chapter.


Performing Specific Searches with CWP URLs

The CWP URLs we've looked at so far are simply querying a FileMaker database table, finding all records, and returning the results as raw XML according to the selected XML grammar. But what if you want to query different tables within the chosen database, or select only certain records rather than all records, or apply a sort order to the results? All these things are possible with CWP.

Specifying the Table

One of the reasons it's so important to supply a layout name with your CWP URLs (via the -lay parameter) is that, in FileMaker 7, the active table is determined by the active layout, via that layout's table context . You may recall that, in the Layout Setup dialog for each layout, there's a choice labeled Show Records From. This enables you to select a table occurrence that will provide the layout's table context. When you specify a layout in a CWP URL, you are implicitly setting the active table as well. All commands in the query string are considered to be applied to whatever table underlies the chosen layout.

For a refresher on the idea of table context, see "Understanding Table Context," p. 161 .


Finding Specific Records

The Custom Web Publishing URL can also be used to search for specific records. To do this, use -find as the database action, instead of -findall . You also need to specify one or more search criteria, which are also supplied as name-value pairs.

For example, if you're working with a database of animals, and there's a field called name for the animal's name, you can use the following URL to search for any animals named Hector:

http://192.168.100.101/fmi/xml/fmresultset.xml?-db=animal&-lay=web&name=Hector&-find

NOTE

The database in question has only a single table, also called Animal, and that table is the table context for the Web layout.


This code snippet specifies a database action of -find , and adds one more parameter to the query string. We say name=Hector to cause the Web Publishing Engine to search for only records where the name is Hector. If there are any such records, they'll be returned in the chosen XML grammar. If there are no matching records, we get back a response that looks a bit like Listing 23.2.

Listing 23.2. Sample Error Response
 <?xml version="1.0" encoding="UTF-8" standalone="no" ?> <!DOCTYPE fmresultset (View Source for full doctype...)> <fmresultset xmlns="http://www.filemaker.com/xml/fmresultset" version="1.0">     <error code="401" />     <product build="12/10/2003" name="FileMaker Web Publishing Engine" version="7.0v1" />     <datasource database="" date-format="" layout="" table="" time-format="" graphics/ccc.gif total-count="0" />     <metadata />     <resultset count="0" fetch-size="0" /> </fmresultset> 

You can see that in the case where no records are found, the XML returned by the Web Publishing Engine contains an error code appropriate to the situation. In this case, the code is a standard "no records found" error. (Note that the exact format of the error response varies depending on which XML grammar you specified in the URL.)

Specifying an Exact Match when Searching

In the previous example, the search appeared to be for all animals named Hector. This is not exactly true. The previous URL will have exactly the same effect as entering Find mode in the regular FileMaker client, typing Hector into the name field, and performing the search. FileMaker, when searching text fields, searches on a "starts with" basis, so this search actually finds animals named Hector, Hector II, Hectorax, and so on. To specify that you want an exact match, rather than a "starts with" match, you need a bit more precision. In FileMaker's regular Find Mode, you'd type =Hector in the search field, with the equals sign indicating an exact match. In a CWP URL, you'd write:

http://192.168.100.101/fmi/xml/fmresultset.xml?-db=animal&-lay=web&name=Hector&name.op=eq&-find

Another parameter has been added to the query string here. The new parameter specifies what kind of operator we want to apply to one of the search fields. The syntax for this new parameter is

 

 <field-name>.op=<operator> 

Here, field-name is the field to which you want to apply the operator, and operator is a short character string indicating one of nine different possible operators. Here, the operator we've chosen is eq for an exact match. Other possible operators are cn for "contains", bw for "begins with" (the default), and ew for "ends with." So, if you wanted to find all animals with a name ending in "tor", you could use this URL:

http://192.168.100.101/fmi/xml/fmresultset.xml?-db=animal&-lay=web&name=tor&name.op=ew&-find

This query string instructs the Web Publishing Engine to treat the search on the name field as an "ends with" search.

NOTE

The operators available to you in Custom Web Publishing are similar to, but not identical to, the list you would find in the FileMaker client if you entered Find Mode and clicked on the symbol list in the status area. FileMaker Find Mode and the Custom Web Publishing find syntax each contain operators that are not available in the other. Table 23.2 lists all the operators available in Custom Web Publishing.

Table 23.2. Comparison Operators for the -find Command

Operator

Significance

FileMaker Find equivalent

eq

Equals

=value

cn

Contains

*value*

bw

begins with

value*

ew

ends with

*value

gt

greater than

>value

gte

greater than or equal

>=value

lt

less than

<value

lte

less than or equal

<=value

neq

not equal

(omit checkbox)



Performing a Numerical Comparison Search

Consider a database that contains some numerical fields. The Animal database used as an example so far contains a field called weight_birth for an animal's birth weight. Suppose you want to find all animals with a birth weight less than 100 pounds . The following URL would do it:

http://127.0.0.1/fmi/xml/fmresultset.xml?-db=animal&-lay=web&weight_birth=100&weight_birth.op=lt&-find

Here, 100 is specified for the weight_birth search field, but we go on to say that the operator for that search field is the "less than" operator, symbolized by the code lt .

Searching on Multiple Criteria

Suppose we want to construct a more narrowly tailored search. You want to find all male animals with a birth weight less than 100. (This is the equivalent of filling in two fields in FileMaker's Find Mode, instead of just one.) You'd use a URL like the following:

http://127.0.0.1/fmi/xml/fmresultset.xml?-db=animal&-lay=web&weight_birth=100&gender=Male&weight_birth.op=lt&-find

Here we've simply added one more search field: gender=Male . This constitutes a further limit on the search you saw in the previous example. This search finds only records for male animals with birth weight less than 100.

Creating Multiple Find Requests

The preceding example showed how to use multiple criteria to narrow a search. But what if you want to use multiple criteria to broaden a search? We've searched for animals with birth weight less than 100. What if you also want to find, in the same search, any animals who have a current weight less than 500? (You might recognize this as the equivalent of creating additional Find requests in the regular FileMaker Pro software.)

To explain this kind of search, you need to introduce the concept of a logical operator . In the search demonstrated previously, for a record to be included in the search, all the search criteria in the query string had to be true. That is, an animal would not be included in the search results unless it was both male and had a birth weight less than 100. This kind of search is thus often referred to as an "and" search or an "all-true" search.

On the other hand, when you think about also finding animals with current weight less than 500, you have a situation where an animal will be included in the search results if any of the search criteria are true. In other words, a record will be found if the animal had a birth weight of less than 100, or it has a current weight of less than 500. This type of search is thus often called an "or" or an "any-true" search.

By default, the Web Publishing Engine treats all searches as "and" searches. To perform an "or" search, you'd use a URL like this one:

http://127.0.0.1/fmi/xml/fmresultset.xml?-db=animal&-lay=web&weight_birth=100&weight_current=500e&weight_birth.op=lt&weight_current.op=lt&-lop=or&-find

Here you supply two search criteria. You also need to supply the field-level operator for each search field. In both cases, you're performing a " less-than " search, so you need to specify an operator of lt for each field. The new element in the query string is the -lop parameter, which stands for "logical operator". -lop can have a value of "and" (the default) or "or" (the one we're using here). The -lop parameter here instructs the Web Publishing Engine to treat the search as an "or" search.

NOTE

In FileMaker proper, you can construct a search that's a complex mixture of "and" and "or" searches by entering multiple Find requests, each with more than one field filled in. Such searches can't readily be reproduced with Custom Web Publishing: the -lop command can be applied only to all the search fields taken together. There is also no way to invoke the additional FileMaker search options of Constrain or Extend Found Set.


Specifying a Sort Order for Search Results

When you make a request to the Web Publishing Engine, you can specify how the results should be sorted. You can specify one or more fields to sort on, as you can in the regular FileMaker application, and you can specify whether each sort field should be sorted in ascending or descending order. Consider a URL that will find all records in the Animal table, and ask that the records be sorted by name:

http://192.168.101.100/fmi/xml/fmresultset.xml?-db=Animal&-lay=web&-sortfield.1=name&-findall

The new query string command here is called -sortfield . You'll notice we also added the suffix .1 to this parameter. This indicates the sort field's precedence . The concept of precedence is meaningful only if you have more than one sort field, as you'll see in a moment. Despite this fact, you can't omit the sort precedence, even for a one-item sort, or the records won't be sorted at all.

Suppose you wanted the records to be sorted by gender, and within each gender to be sorted by current weight from highest to lowest . You'd do that like this:

http://127.0.0.1/fmi/xml/fmresultset.xml?-db=Animal&-lay=web&-sortfield.1=gender&-sortfield.2=weight_current&-sortorder.2=descend&-findall

Here two sort fields are specified. The first sort is by gender , the second by weight_current . There's also a new parameter, called -sortorder . Like -sortfield , -sortorder also takes a numeric suffix. Here, it's used to indicate which sort field is being referred to. By default, each field will be sorted in ascending order. If you supply a value of descend for the second sort field, you ensure that the animals will be sorted, within each gender group , from heaviest to lightest.

Applications of Custom Web Publishing with XML

The current section shows how to use the Web Publishing Engine to query a database and "publish" the results as raw XML in one of several XML grammars. But what use is the capability, exactly?

Well, the most obvious significant use is to allow FileMaker to act as a Web service provider. In Chapter 22, "FileMaker and Web Services," we cover how to use FileMaker to pull data from other Web services on the Internet. But FileMaker can also act as a Web service. If you provide a Web service client with an appropriate URL, remote services and programs can query your FileMaker database via the Web Publishing Engine and extract whatever information you choose to let them see.

Additionally, the URL query syntax discussed in this section is also at the heart of the more sophisticated form of Custom Web Publishing that's made possible by the application of XSLT style sheets, which is the topic of the next section.

 <  Day Day Up  >  


QUE CORPORATION - Using Filemaker pro X
QUE CORPORATION - Using Filemaker pro X
ISBN: N/A
EAN: N/A
Year: 2003
Pages: 494

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net