FileMaker Extra: About the Custom Web Publishing Tools

FileMaker Extra About the Custom Web Publishing Tools

FileMaker Server Advanced comes with a couple of extremely useful tools for kick-starting your work with FileMaker XSL. These are the CDML Converter and the Site Assistant. They e not installed automaticallyyou need to install them separately if you want to use them.

The CDML Converter

The CDML Converter is designed to do what its name implies. It does its best to take a set of FileMaker-based web pages written in CDML (which was the custom Web publishing option in versions of FileMaker Pro before version 7) and convert these files to a set of XSLT-CWP stylesheets. As of FileMaker Pro 7, CDML is no longer an available web publishing option for FileMaker, so if you want to use an existing CDML solution with FileMaker 7 or later, you need to convert it somehow, and the CDML Converter is probably the best place to start.

The CDML Converter converts all your CDML files into XSLT-CWP stylesheets. A reasonable conversion path exists for most CDML constructs, but not all CDML is converted correctly. There are, for example, a few CDML commands that the Web Publishing Engine no longer supports, such as -dbopen and -dbclose. CDML also, like XSLT-CWP, supported custom functions for sending email, but these tags won be converted correctly and youll probably need to rewrite your email functionality with the new XSLT-CWP tools.

As the CDML Converter converts your CDML files, it writes out a conversion log describing the conversion process. If there were any errors during conversion, the Converter writes an entry into the log describing the error. It also adds a comment to the affected XSLT file, if possible, pointing you to the exact location and description of the error.

The documentation that accompanies FileMaker Server Advanced has a thorough description of the CDML conversion process, and a detailed list of all potential trouble areas. To ensure the smoothest conversion of your CDML files, we recommend you read the conversion specification carefully before beginning. Take note of any potential trouble areas. The documents offer specific guidance in rewriting any CDML trouble spots.

Whether or not you do any rewriting, its a good idea to verify that your CDML files actually work (under FileMaker 6 or whichever version they e built for). After you have a working CDML system that youve vetted for possible conversion problems, make a copy of the system and try out the CDML Converter. From there, youll want to refer to the conversion log, inline comments, and the detailed conversion documentation to iron out any remaining difficulties.

The Site Assistant

The Site Assistant is likely to have much wider application for you than the CDML Converter. Think of the Site Assistant as an XSLT wizard of sorts. You point the Site Assistant to a hosted database, tell it what kinds of stylesheets you want to generate (search, edit, summary report, and so on), and where to put the files. It then generates the files, and you e free to use them as is, or modify them further. If so instructed, the Site Assistant generates a home page with links to the different stylesheets, and can add navigational elements to each page as well. If you have the Site Assistant generate a full suite of pages for a database, youll end up with a fairly full-featured little website that allows you do almost anything you need to via XSLT-CWP.

Using the Site Assistant is simple. When run, the Site Assistant asks to be pointed to a running Web Publishing Engine. After you give it the Web Publishing Engines address, it queries the Web Publishing Engine for a list of hosted databases that have XSL publishing enabled. You then choose one, and continue to the next screen. This first step is shown in Figure 23.20.

Figure 23.20. Choosing a database for use with the Site Assistant.

After youve picked your file, you e presented with a screen that allows you to choose up to seven different kinds of stylesheets. The screen is shown in Figure 23.21.

Figure 23.21. Choosing which stylesheets youd like the Site Assistant to generate.

Most of these choices involve specifying a layout against which the stylesheet should run. Remember that this also amounts to choosing the affected table because each layouts table context determines the target table.

There are a few pitfalls to be aware of when using the Site Assistant. The generation process really works well only when all your actions involve the same base table. If your database contains multiple tables, you need to make sure that all the layouts you reference are based on the same table.

There are also a few mutual dependencies among stylesheets. If you choose Search Records Using Fields From, you should also select View Records in List. The generated search stylesheet tries to use the list stylesheet to display its search results, but unless you ask the Site Assistant to generate that stylesheet, it won exist.

In addition to generating a stylesheet for each of your chosen options, the Site Assistant generates a utilities file called, appropriately enough, utilities.xsl. Even if you never use the Site Assistant again, its worth your while to generate this file and inspect it carefully. It includes a number of powerful techniques for working with XSLT-CWP. If you can thoroughly understand the XSLT techniques contained in this file, youll have some very useful additions to your XSLT-CWP toolkit.

In general, we recommend that you try to get to the point where you write your own files from scratch. The one place we feel otherwise is with subsummary reports. Subsummary reporting is famously irritating to do in XSLso much so that the XSL 2.0 proposal contains specific features for making it easier. For subsummary reporting, we recommend you rely heavily on the files generated by the Site Assistant. Learn how the selected options translate into the final HTML page, and learn which pieces of the page are specific to the Site Assistants mini-site functionality (which you can replace) and which ones are at the core of the report.

One caveat, though: The Site Assistants generated subsummary reports support only one level of summary grouping. To create reports that are two or more levels deep, you need to read the wizard-generated files carefully, understand the applied techniques, and extend them to your multilevel report.

Learning How to Program with CWP

In general, we e not big fans of wizards. They tend to both obscure the way things actually work and impose a limit on the flexibility and power of the underlying tools. We find them to be most useful as a basis for quickly generating an example that you can then dissect by hand to see how things actually work.

One danger with wizards, though, is that because they e automated, they often tend to assume that you e not going to inspect or modify the results. So they often use quite advanced techniques to generate pleasing functionality. Think of how most typical graphical web design tools generate JavaScript rollovers: The rollovers work beautifully, but the tool usually generates some extremely dense JavaScript. If you want to use the tools output without modifications, you e in great shape. If you want to use the output as a basis for learning, you need to deal with some advanced code.

This is more or less the case with the XSL stylesheets generated by the Site Assistant. The generated stylesheets are quite powerful, and are packed with complex functionalityespecially the record list view and the subsummary reports. But they do not generate simple XSL! You need to have a good grasp of intermediate-to-advanced XSL to be able to read the output.

But of course, you need to be a strong XSL programmer in any case to get the best use out of Custom Web Publishing. If you e an XML/XSL novice, heres the learning path wed recommend:

1. Write some simple queries that use plain old XML-CWP. In other words, get accustomed to writing the query strings that the Web Publishing Engine uses to bring back FileMaker data. Experiment with various search criteria and sort fields.

2. Write some simple stylesheets to process search results. We recommend beginning with stylesheets that display search output in a variety of list formats.

3. Generate a set of stylesheets with the Site Assistant. Pay special attention to the files that perform database actions other than searches. Read and understand the utilities.xsl file.

4. Experiment with adding capabilities to the Site Assistant files.

5. Read up on the advanced features of XSLT-Custom Web Publishing in the supplied documentation and expand your knowledge. Practice with features such as email, cookies, and sessions.

Custom Web Publishing is a rich programming environment, and this chapter only scratches the surface. As you progress with CSP, youll want to deepen your mastery of XSL and XML by reading, experimenting, and participating in online forums.