Using XSLT with Custom Web Publishing

The previous section discusses how to use FileMaker to produce plain XML, distributed over HTTP. This section builds on the previous one and demonstrates how to use XSL transformations (XSLT) to manipulate that raw XML further.

About Server-Side XSLT

The previous section demonstrates how to query a FileMaker database via the Web Publishing Engine, and return the results as some form of raw XML. But, as youll know if youve worked with XSLT before, or if youve already read Chapter 22 of this book, XML becomes even more interesting when you begin to transform it with XSLT stylesheets.

If youve already read Chapter 22, youll have become familiar with the distinction between client-side and server-side XSL transformations. When using FileMakers XML export capability, its the client copy of FileMaker that performs any XSL transformations you specify, hence the term client-side transformation. On the other hand, with Custom Web Publishing, the transformation is performed by the Web Publishing Engine (server-side), and only the transformation result is sent back to the client (in this case a web browser).

In the world of Custom Web Publishing, all XSLT transformations are server-side transformations. Stylesheets are placed in one or more predetermined locations within the Web Publishing Engine install hierarchy and accessed by the Web Publishing Engine as necessary.

Where to Put Your Stylesheets

When using Custom Web Publishing with XSLT, your stylesheets live on the same machine as the Web Publishing Engine. All the stylesheets you write need to be located at or beneath a certain point in the Web Publishing Engine directory hierarchy. On Mac OS X, the root directory is /Library/FileMaker Server 8/Web Publishing/xslt-template-files. On Windows, the root directory is located by default at c:Program FilesFileMakerFileMaker Server 8Web Publishingxslt-template-files, but you have the option to change the install directory on Windows, so be aware of where you installed your Web Publishing Engine and plan accordingly.

Getting Started with XSLT in CWP

To use XSLT stylesheets in your Custom Web Publishing project, you need several things. A number of them are also prerequisites for using Custom Web Publishing with plain XML. The only significant additional points are that the Web Publishing Engine must be configured with XSLT publishing enabled (see the section titled "Configuring the Web Publishing Engine" earlier in this chapter), and all FileMaker databases that you want to make accessible must have the fmxslt extended privilege assigned via a privilege set to one or more activated user accounts (see the section titled "Getting Your Databases Ready for Custom Web Publishing" earlier in this chapter).

A Simple Stylesheet to Display Search Results

Suppose that, rather than have data come out of FileMaker Server as raw XML, youd like to return it in nicely formatted HTML. For convenience, lets continue working with the example of a simple listing of herd animals. A simple database lists the animals, and youd like them to appear in a browser formatted as shown in Figure 23.13.

So you need an XSLT stylesheet that will transform FileMakers XML into formatted HTML.

Youll probably remember that, before you can write a stylesheet to transform FileMaker XML, you need to know in what grammar that XML will be presented. When you e using Custom Web Publishing, you can request the XML from the Web Publishing Engine in whichever one of the available FileMaker grammars you prefer. Here you e going to request the data in the fmresultset grammar and write the stylesheet accordingly. (For an example of this CWP-only grammar, see Listing 23.1.) A stylesheet that will do this is shown in Listing 23.3.

Listing 23.3. CSS-Formatted HTML Stylesheet

The mechanics of the stylesheet are straightforward enough. It declares a namespace called fmrs, to match up with the fmresultset namespace. It does an initial template match on the fmresultset element, where it outputs all the initial HTML elements, including a small CSS stylesheet. After this is done, it uses to loop over all the elements, and outputs two formatted HTML table rows for each record: one containing the name, the other containing the other three fields of interest. Youll notice that the fmresultset grammar is easier to work with than the FMPXMLRESULT grammar because you can reference field names directly, instead of having to refer to them by their position within the element.

Format of the XSLT URL

The previous section demonstrated a simple server-side stylesheet, but it didn explain exactly how the stylesheet would be applied to XML coming out of FileMaker Server. Just as with XML Custom Web Publishing, you invoke the stylesheet from a web browser, via a specially formatted URL. For the previous sections stylesheet, a sample URL might be

[View full width]

The general format of an XSLT URL is somewhat similar to that for XML. It looks like this:

//[:

]/fmi/xsl/[

/][?]

Many of these elements have the same significance as in the plain XML URL. Rather than reference the /fmi/xml path on the server, though, we reference /fmi/xsl. We follow this immediately with the name of the stylesheet, but note that this assumes that the stylesheet is immediately inside the root XSL directory in your Web Publishing Engine installation directory. You have the option, though, of creating additional subdirectories inside that root directory, and if you do this, you need to reference those intermediate folders in the path as well. In the URL shown previously, weve created a subdirectory inside the XSLT root directory, called animal, and inside that directory is the stylesheet, called animal-fmresult.xsl. So you need to include the intermediate /animal folder in the path in the URL.

After the name of the stylesheet, a query string is supplied thats very similar to the XML query string (because you can request the identical actions and search options). One difference, though, is that you need to pass a parameter called -grammar, and set it to be equal to the name of the grammar you intend to use. The earlier stylesheet was written with the fmresultset grammar in mind, so this needs to be specified in the URL. Its an error to omit the -grammar parameter. And of course, if you specify a grammar different from the one the stylesheet expects, youll get unexpected results.

Note

Its actually possible to omit the entire query string when using XSLT with Custom Web Publishing! The reason is that XSLT-CWP has a special command for embedding the query parameters inside the stylesheet itself. Youll see more on this in the following section.

Embedding Query Parameters in a Stylesheet

One of the difficulties with allowing your FileMaker data to be accessed via a URL is that a canny user can easily experiment with the URL elements to try to create effects other than those you intendedfor example, displaying forbidden records, or even sending a command to delete a record.

Custom Web Publishing has a method for embedding query parameters in the body of a stylesheet. To do this, you use a special XML construct called a processing instruction. A processing instruction is a command to a specific XML processor. If you pass a processing instruction that your processor doesn understand, it is ignored.

To embed query parameters in a stylesheet, you could add a line like the following to a stylesheet:

What this processing instruction means is that any values for -grammar, -db, -lay, or the database action that are passed via the URL will be overridden by the values supplied in this processing instruction. So, no one can ever point the page to a different database, or demand a different database action (such as record deletion!).

Caution

You should be aware that this query string in the processing instruction does not simply replace the query string that might be present in a URL. It overrides it, one parameter at a time. What this means is that if the URL contains a parameter (such as a search field or sort order) that isn mentioned in the processing instruction, that parameter will still be in force. If you want to block any possibility that a user can supply a rogue query parameter, you need to specify that parameter explicitly in your static processing instruction.

Its a good idea to use this technique wherever you can to increase the security of your databases and your web application. Also, embedding at least the expected grammar in the stylesheet prevents you from ever having a mismatch between the grammar you choose in a URL and the one for which the stylesheet is written.