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 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 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.
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.
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.
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.
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:
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.
Write some simple stylesheets to process search results. We recommend beginning with stylesheets that display search output in a variety of list formats.
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.
Experiment with adding capabilities to the Site Assistant files.
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.
Part I: Getting Started with FileMaker 8
Using FileMaker Pro
Defining and Working with Fields
Working with Layouts
Part II: Developing Solutions with FileMaker
Relational Database Design
Working with Multiple Tables
Working with Relationships
Getting Started with Calculations
Getting Started with Scripting
Getting Started with Reporting
Part III: Developer Techniques
Developing for Multiuser Deployment
Advanced Interface Techniques
Advanced Calculation Techniques
Advanced Scripting Techniques
Advanced Portal Techniques
Debugging and Troubleshooting
Converting Systems from Previous Versions of FileMaker Pro
Part IV: Data Integration and Publishing
Importing Data into FileMaker Pro
Exporting Data from FileMaker
Instant Web Publishing
FileMaker and Web Services
Custom Web Publishing
Part V: Deploying a FileMaker Solution
Deploying and Extending FileMaker
FileMaker Server and Server Advanced
Documenting Your FileMaker Solutions