FileMaker Server 9 ® Custom Web Publishing with XML and XSLT
© 2007 FileMaker, Inc. All Rights Reserved. FileMaker, Inc. 5201 Patrick Henry Drive Santa Clara, California 95054 FileMaker is a trademark of FileMaker, Inc., registered in the U.S. And other countries, and ScriptMaker and the file folder logo are trademarks of FileMaker, Inc. All other trademarks are the property of their respective owners. FileMaker documentation is copyrighted. You are not authorized to make additional copies or distribute this documentation without written permission from FileMaker.
Contents About this guide Chapter 1 Introducing Custom Web Publishing About the Web Publishing Engine How a Web Publishing Engine request is processed Custom Web Publishing with PHP Custom Web Publishing with XML and XSLT Comparing PHP to XML and XSLT Reasons to choose PHP Reasons to choose XML and XSLT Chapter 2 About Custom Web Publishing with XML and XSLT Creating dynamic websites with the Web Publishing Engine About Custom Web Publishing with XML About Custom Web Publishing with XSLT About developing
FileMaker Server Custom Web Publishing with XML and XSLT Chapter 4 Accessing XML data with the Web Publishing Engine Using Custom Web Publishing with XML Differences between the Web Publishing Engine and FileMaker Pro XML Import/Export How the Web Publishing Engine generates XML data from a request General process for accessing XML data from the Web Publishing Engine About the URL syntax for XML data and container objects About the URL syntax for XML data About the URL syntax for FileMaker container obj
| Chapter 6 Developing FileMaker XSLT stylesheets Using XSLT stylesheets with the Web Publishing Engine About the FileMaker XSLT Extension Function Reference About the FileMaker XSLT Starter Solution About the URL syntax for FileMaker XSLT stylesheets About the URL syntax for FileMaker container objects in XSLT solutions Using query strings in FileMaker XSLT stylesheets Specifying an XML grammar for a FileMaker XSLT stylesheet About namespaces and prefixes for FileMaker XSLT stylesheets Using statically de
FileMaker Server Custom Web Publishing with XML and XSLT Chapter 7 Staging, testing, and monitoring a site Staging a Custom Web Publishing site Testing a Custom Web Publishing site Examples of stylesheets for testing XML output Monitoring your site Using the web server access and error logs Using the Web Publishing Engine application log Using the Web Server Module error log Using Web Publishing Core internal access logs Appendix A Valid names used in query strings About the query commands and paramete
| –modid (Modification ID) query parameter –query (Compound find request) query parameter –recid (Record ID) query parameter –relatedsets.filter (Filter portal records) query parameter –relatedsets.max (Limit portal records) query parameter –script (Script) query parameter –script.param (Pass parameter to Script) query parameter –script.prefind (Script before Find) query parameter –script.prefind.param (Pass parameter to Script before Find) query parameter –script.
FileMaker Server Custom Web Publishing with XML and XSLT
Preface About this guide This guide assumes you are experienced with XML and XSLT, developing websites, and using FileMaker® Pro to create databases. You should understand the basics of FileMaker Pro database design, and should understand the concepts of fields, relationships, layouts, portals, and containers.
FileMaker Server Custom Web Publishing with XML and XSLT
Chapter 1 Introducing Custom Web Publishing With FileMaker Server, you can publish your FileMaker database on the Internet or an intranet in these ways. Instant Web Publishing: With Instant Web Publishing, you can quickly and easily publish your database on the web.
FileMaker Server Custom Web Publishing with XML and XSLT About the Web Publishing Engine To support Instant Web Publishing and Custom Web Publishing, FileMaker Server uses a set of software components called the FileMaker Server Web Publishing Engine. The Web Publishing Engine handles interactions between a web user’s browser, your web server, and FileMaker Server.
Chapter 1 | Introducing Custom Web Publishing 13 Custom Web Publishing with PHP The FileMaker API for PHP provides an object-oriented PHP interface to FileMaker databases. The FileMaker API for PHP enables both data and logic stored in a FileMaker Pro database to be accessed and published on the web, or exported to other applications. The API also supports complex and compound find commands for extracting and filtering data stored in FileMaker Pro databases.
FileMaker Server Custom Web Publishing with XML and XSLT Comparing PHP to XML and XSLT The following sections provide some guidelines for determining the best solution for your site. Reasons to choose PHP 1 PHP is a more powerful, object-oriented procedural scripting language, but is relatively easy to learn. There are many resources available for training, development, and support.
Chapter 2 About Custom Web Publishing with XML and XSLT Creating dynamic websites with the Web Publishing Engine The Web Publishing Engine provides Custom Web Publishing for FileMaker Server using XML data publishing and server-processed XSLT stylesheets. Custom Web Publishing provides several benefits: 1 Customization: You can determine how web users interact with FileMaker data, and how the data displays in web browsers.
FileMaker Server Custom Web Publishing with XML and XSLT The Web Publishing Engine uses your stylesheets to dynamically obtain data from a FileMaker database whenever a web user sends an HTTP request and a URL that references one of your XSLT stylesheets. The Web Publishing Engine uses a stylesheet to transform and format the XML data, and generates the resulting HTML page that the web user can work with.
Chapter 2 | About Custom Web Publishing with XML and XSLT 17 Web publishing requirements What is required to publish a database using Custom Web Publishing To publish databases using Custom Web Publishing with XML or XSLT, you need: 1 a FileMaker Server deployment that includes 1 a web server, either Microsoft IIS (Windows) or Apache (Mac OS X) 1 the FileMaker Database Server, enabled for Custom Web Publishing 1 the Web Publishing Engine, installed and configured 1 one or more FileMaker Pro databases h
FileMaker Server Custom Web Publishing with XML and XSLT Where to go from here Here are some suggestions to get started developing Custom Web Publishing solutions: 1 If you haven’t already done so, use FileMaker Server Admin Console to enable Custom Web Publishing. See FileMaker Server Help and FileMaker Server Getting Started Guide.
Chapter 3 Preparing databases for Custom Web Publishing Before you can use Custom Web Publishing with a database, you must prepare the database and protect it from unauthorized access. Enabling Custom Web Publishing in a database You must enable Custom Web Publishing in each database you want to publish. You can individually enable Custom Web Publishing with XML or Custom Web Publishing with XSLT, or you can enable both technologies in each database.
FileMaker Server Custom Web Publishing with XML and XSLT 1 If the Guest account is enabled and has a privilege set enabled that includes a Custom Web Publishing extended privilege, all web users automatically open the database with the access privileges assigned to the Guest account. If the Custom Web Publishing extended privilege is assigned to the Guest account: 1 Web users are not prompted for an account name and password when opening a file.
Chapter 3 | Preparing databases for Custom Web Publishing 21 Web server support for Internet media types (MIME) Your web server determines the support for the current MIME (Multipurpose Internet Mail Extensions) types registered for the Internet. The Web Publishing Engine does not change a web server’s support for MIME. For more information, see the documentation for your web server.
FileMaker Server Custom Web Publishing with XML and XSLT FileMaker scripts and Custom Web Publishing The ScriptMaker™ feature in FileMaker Pro can automate frequently performed tasks, combine several tasks. When used with Custom Web Publishing, FileMaker scripts allow web users to perform more tasks or a series of tasks. FileMaker supports about 70 script steps in Custom Web Publishing.
Chapter 3 | Preparing databases for Custom Web Publishing 23 1 Any script that modifies data should include the Commit Record/Request step, because data changes aren’t visible in the browser until the data is saved or “submitted” to the server. This includes several script steps like Cut, Copy, Paste, and so on. Many single-step actions should be converted into scripts to include the Commit Record/Request step.
FileMaker Server Custom Web Publishing with XML and XSLT
Chapter 4 Accessing XML data with the Web Publishing Engine You can obtain and update FileMaker data in Extensible Markup Language (XML) format by using the Web Publishing Engine. In the same way that HTML has become the standard display language for communication on the World Wide Web, XML has become the standard language for structured data interchange. Many individuals, organizations, and businesses use XML to transfer product information, transactions, inventory data, and other business data.
FileMaker Server Custom Web Publishing with XML and XSLT 1 The Web Publishing Engine can access XML data from a FileMaker portal, but FileMaker Pro cannot. 1 The Web Publishing Engine can access data in a container field, but FileMaker Pro cannot. 1 The Web Publishing Engine provides real-time access to FileMaker data via HTTP or HTTPS, but FileMaker Pro cannot. Note For information on using FileMaker Pro to import and export data in XML format, see FileMaker Pro Help.
Chapter 4 | Accessing XML data with the Web Publishing Engine 27 General process for accessing XML data from the Web Publishing Engine Here is an overview of the process for using the Web Publishing Engine to access XML data in a FileMaker database: 1. In the FileMaker Server Admin Console, make sure XML Publishing is enabled. See FileMaker Server Help. 2.
FileMaker Server Custom Web Publishing with XML and XSLT 1 is optional and specifies the port that the web server is using. If no port is specified, then the default port for the protocol is used (port 80 for HTTP, or port 443 for HTTPS). 1 is the name of the FileMaker XML grammar. Possible values are fmresultset.xml, FMPXMLRESULT.xml, FMPXMLLAYOUT.xml, or FMPDSORESULT.xml. See “Using the fmsresultset grammar” on page 31 and “Using other FileMaker XML grammars” on page 34.
Chapter 4 | Accessing XML data with the Web Publishing Engine 29 1 If a container field stores a file reference instead of an actual object, then the container field’s element contains a relative path that refers to the object. For example: /images/logo.
FileMaker Server Custom Web Publishing with XML and XSLT Depending on the grammar you specify in the URL request, the Web Publishing Engine will generate an XML document using one of the grammars. Each XML document contains a default XML namespace declaration for the grammar. See the next section, “About namespaces for FileMaker XML.” Use one of these grammars in your document or web page to display and work with FileMaker data in XML format.
Chapter 4 | Accessing XML data with the Web Publishing Engine 31 Using the fmsresultset grammar The XML element names in this grammar use FileMaker terminology, and the storage of fields is separated from the type of fields. The grammar also includes the ability to identify summary, calculation, and global fields. To use the fmresultset grammar, specify the following name of the fmresultset grammar in the URL requesting the XML document from the Web Publishing Engine: fmresultset.
FileMaker Server Custom Web Publishing with XML and XSLT element The element of the fmresultset grammar contains one or more and elements, each containing attributes for one of the fields of the result set.
Chapter 4 | Accessing XML data with the Web Publishing Engine Example of XML data in the fmresultset grammar The following is an example of XML data generated with the fmresultset grammar. PAGE 34FileMaker Server Custom Web Publishing with XML and XSLT Using other FileMaker XML grammars The other FileMaker XML grammars contain information about field types, value lists, and layouts. FMPXMLRESULT is functionally equivalent to fmresultset. To access value lists and field display information in layouts, you must use the FMPXMLLAYOUT grammar. The FMPXMLRESULT and FMPXMLLAYOUT grammars are more compact for data interchange.
Chapter 4 | Accessing XML data with the Web Publishing Engine 35 Example of XML data in the FMPXMLRESULT grammar The following is an example of XML data generated with the FMPXMLRESULT grammar. PAGE 36FileMaker Server Custom Web Publishing with XML and XSLT For date, time, and timestamp fields, data for value lists are formatted using the “fm” format for that field type. The “fm” formats are MM/dd/yyyy for date, HH:mm:ss for time, and MM/dd/yyyy HH:mm:ss for timestamp. See “Using the date, time, and day extension functions” on page 72.
Chapter 4 | Accessing XML data with the Web Publishing Engine 37 About UTF-8 encoded data All XML data generated by the Web Publishing Engine is encoded in UTF-8 (Unicode Transformation 8 Bit) format. This format compresses data from the standard Unicode format of 16 bits to 8 bits for ASCII characters. XML parsers are required to support Unicode and UTF-8 encoding.
FileMaker Server Custom Web Publishing with XML and XSLT Use this query command name To execute this command –find Find record(s). –findall Find all records. –findany Find a random record. –findquery Perform complex or compound find request. –layoutnames Retrieve names of all available layouts for a hosted and web-shared database. –new Add new record. –scriptnames Retrieve names of all available scripts for a hosted and web-shared database.
Chapter 4 Use these query parameter names | Accessing XML data with the Web Publishing Engine 39 With these query commands –script.prefind.param (pass a parameter value Optional with –script.prefind to the script specified by –script.prefind) –script.presort (perform script before sort) Optional with –find, –findall –script.presort.param (pass a parameter value to the script specified by –script.presort) Optional with –script.presort –skip (skip records) Optional with –find, –findall –sortfield.
FileMaker Server Custom Web Publishing with XML and XSLT If one of the above steps generates an error code, the request processing stops; any steps that follow are not executed. However, any prior steps in the request are still executed. For example, consider a request that deletes the current record, sorts the records, and then executes a script.
Chapter 4 | Accessing XML data with the Web Publishing Engine 41 Troubleshooting XML document access If you have trouble accessing XML documents with the Web Publishing Engine, verify that: 1 The extended privileges in the database are set for XML Custom Web Publishing and assigned to a user account. See “Enabling Custom Web Publishing in a database” on page 19. 1 The database is hosted on the Database Server component of the FileMaker Server deployment, and is opened by FileMaker Server.
FileMaker Server Custom Web Publishing with XML and XSLT
Chapter 5 Introduction to Custom Web Publishing with XSLT You can use FileMaker XSLT stylesheets to transform, filter, or format XML data for use in a web browser or in other programs and applications. This chapter introduces FileMaker XSLT stylesheets, and a tool to help you get started creating XSLT stylesheets—FileMaker XSLT Site Assistant. For more detailed information about how FileMaker XSLT stylesheets are constructed, see chapter 6, “Developing FileMaker XSLT stylesheets.
FileMaker Server Custom Web Publishing with XML and XSLT Getting started using Custom Web Publishing with XSLT If you know standard XML and XSLT, then you can immediately start using the Web Publishing Engine after learning a few unique details about FileMaker XML and XSLT publishing, such as how to use the FileMaker XSLT extension functions and query commands and parameters. XSLT Site Assistant is a tool to help you create stylesheets and learn how they are constructed.
Chapter 5 | Introduction to Custom Web Publishing with XSLT 45 General steps for using Custom Web Publishing with XSLT Here is a summary of the steps for using Custom Web Publishing with XSLT: 1. In the Admin Console, make sure XSLT Publishing is enabled. See FileMaker Server Help. 2. Using FileMaker Pro, open each FileMaker database that you’re publishing and make sure the database has the fmxslt extended privilege enabled for Custom Web Publishing with XSLT.
FileMaker Server Custom Web Publishing with XML and XSLT Using FileMaker XSLT Site Assistant to generate FileMaker XSLT stylesheets FileMaker XSLT Site Assistant is an application you can use to create basic XSLT stylesheets as a starting point for use with Custom Web Publishing with XSLT. XSLT Site Assistant is a good way to learn how FileMaker XSLT stylesheets are constructed. You can then use your own XSLT stylesheet authoring or text editing tools to modify the stylesheets as necessary.
Chapter 5 | Introduction to Custom Web Publishing with XSLT 47 Starting XSLT Site Assistant Note To use XSLT Site Assistant, you must have Java Runtime Environment 5 or Java Runtime Environment 6 installed. To start XSLT Site Assistant: 1. Open a browser to the FileMaker Server Web Publishing Tools page. Go to the following URL: http://:16000/tools Where is the machine on which the FileMaker Server resides. 2.
FileMaker Server Custom Web Publishing with XML and XSLT XSLT Site Assistant also generates the utilities.xsl stylesheet for defining errors and common XSLT templates that are called by several XSLT Site Assistant stylesheets. For information about other sections of the XSLT Site Assistant stylesheets, see chapter 6, “Developing FileMaker XSLT stylesheets.
Chapter 5 | Introduction to Custom Web Publishing with XSLT 49 Troubleshooting XSLT stylesheets If you have trouble using the XSLT stylesheets, verify that: 1 The extended privileges in the database are set for Custom Web Publishing with XSLT and assigned to a user account. See “Enabling Custom Web Publishing in a database” on page 19. 1 The database is hosted and opened on the Database Server component of FileMaker Server. See FileMaker Server Help.
FileMaker Server Custom Web Publishing with XML and XSLT
Chapter 6 Developing FileMaker XSLT stylesheets This chapter contains information about how FileMaker XSLT stylesheets are constructed and how to use the FileMaker XSLT extension functions. Using XSLT stylesheets with the Web Publishing Engine When developing and using XSLT stylesheets to request FileMaker XML data via the Web Publishing Engine, be aware of the following points: 1 To use an XSLT stylesheet with the Web Publishing Engine, you must specify the name of the XSLT stylesheet in a URL.
FileMaker Server Custom Web Publishing with XML and XSLT About the FileMaker XSLT Extension Function Reference This release includes a FileMaker database called XSLT Reference.fp7 that contains brief descriptions and examples of each of the FileMaker XSLT extension functions. The function reference database can be found in the following directory on any machine in your FileMaker Server 9 deployment (master or worker). Mac OS /Library/FileMaker Server/Example/XSLT Windows :\Program Files\FileMak
Chapter 6 | Developing FileMaker XSLT stylesheets 53 1 is the XSLT stylesheet filename. 1 can be a combination of one query command and one or more query parameters for Custom Web Publishing with XSLT. See “Using query strings in FileMaker XSLT stylesheets” on page 54, and appendix A, “Valid names used in query strings.
FileMaker Server Custom Web Publishing with XML and XSLT 1 If a container field stores a file reference instead of an actual object, then the container field’s element contains a relative path that refers to the object. For example, if logo.jpg was in the Web folder inside the FileMaker Pro folder, the container field’s element is: /images/logo.
Chapter 6 | Developing FileMaker XSLT stylesheets 55 For example, in a processing instruction: Important If you don’t specify an XML grammar for a FileMaker XSLT stylesheet, the error “QUERY -ER0001” is displayed. See appendix B, “Error codes for Custom Web Publishing.
FileMaker Server Custom Web Publishing with XML and XSLT where: query string-fragment is a string that contains the name-value pairs in the following format: name=value&name2=value2.... where: name is a string that is the name of a query command, query parameter, or database field. value is an arbitrary length string value. For query parameters and field names, use the particular value you want to define, such as “–db=products”.
Chapter 6 | Developing FileMaker XSLT stylesheets 57 3. Uses the current setting for the request and output pages default text encoding option for the Web Publishing Engine. When the Web Publishing Engine is first installed, the initial default text encoding setting for requests is UTF-8. You can change the Web Publishing Engine’s text encoding settings by using the Admin Console. See FileMaker Server Help.
FileMaker Server Custom Web Publishing with XML and XSLT About the encoding of XSLT stylesheets In addition to the encoding for requests and output pages, the encoding of your XSLT stylesheets must be specified in the encoding attribute of the XML declaration at the top of the stylesheet. You can use any of the text encodings listed in the table on page 57. For example, this declaration specifies UTF-8 as the encoding of the stylesheet:
Chapter 6 | Developing FileMaker XSLT stylesheets 59 Using the FileMaker XSLT extension functions and parameters The FileMaker XSLT extension functions are defined to be in the fmxslt namespace. Make sure you include a declaration of the fmxslt namespace in the element at the start of your XSLT stylesheet. See “About namespaces and prefixes for FileMaker XSLT stylesheets” on page 55.
FileMaker Server Custom Web Publishing with XML and XSLT An XML document fragment is loaded into the request-query parameter in the following grammar: ] Note The query information is defined to be in the namespace fmq="http://www.filemaker.com/xml/query".
Chapter 6 | Developing FileMaker XSLT stylesheets 61 Using the Web Publishing Engine base URI parameter The Web Publishing Engine defines the base Uniform Resource Identifier (URI) parameter to be the host and port where the Web Publishing Engine is installed. The base URI allows requests for XML data from FileMaker databases to be resolved in relation to the Web Publishing Engine host.
FileMaker Server Custom Web Publishing with XML and XSLT To load a password-protected XML document that requires a different user name and password than what was specified in the parent request, then use the following syntax to specify the user name and password as part of the URI that is passed to the document() function: http://username:password@hostname/path?querystring To load an XML document that is not based on a FileMaker database, use the document() function without FileMaker query commands or
Chapter 6 | Developing FileMaker XSLT stylesheets 63 Using content buffering When content buffering is disabled, the Web Publishing Engine streams the result of an XSLT transformation directly back to the client. Content buffering is always disabled unless you explicitly enable it. If you enable content buffering, the Web Publishing Engine stores the transformed content until the entire transformation is finished. Content buffering is required for XSLT stylesheets that manipulate headers.
FileMaker Server Custom Web Publishing with XML and XSLT If the Web Publishing Engine detects that the client allows cookies, then the fmxslt:session_encode_url() function stores the session ID in a cookie instead of the URL. Note Session information does not persist after the Web Publishing Engine is restarted. Using the session extension functions Use the following session extension functions to manipulate session variables.
Chapter 6 | Developing FileMaker XSLT stylesheets 65 Here is an example of creating a session and then storing a favorite color in the session: true PAGE 66FileMaker Server Custom Web Publishing with XML and XSLT Notes 1 In each of the three forms of the fmxslt:send_email () function, the smtpFields parameter is a URL-encoded string of any length that contains the address and subject information using the following format, which is based on RFC 2368, the mailto URL scheme: username@host?name1=value1&name2=value2... where username@host specifies a recipient.
Chapter 6 | Developing FileMaker XSLT stylesheets 67 1 The fmxslt:send_email(String smtpFields, String xsltFile, Node xml, boolean includeImages) function sends an email message consisting of XML data that is processed by the email stylesheet you specify in this function. 1 For the xsltFile parameter, specify the name of the email stylesheet by entering a URL that is relative to the main processing stylesheet file for the request.
FileMaker Server Custom Web Publishing with XML and XSLT The following example demonstrates how to set the value of the header. Suppose you are using a stylesheet to output a vCard. There is a potential problem that when a browser tries to load the stylesheet page, the browser could interpret the .xsl file as a stylesheet rather than a vCard. If you use the header called Content-Disposition, you can specify that there is an attachment with an extension of .vcf.
Chapter 6 | Developing FileMaker XSLT stylesheets 69 Using the string manipulation extension functions You can use the string manipulation functions to change the encoding of strings of any length. String manipulation extension function Data type returned fmxslt:break_encode(String value) string Description Returns an HTML break-encoded string. Characters such as “&” (ampersand) are replaced with “&”. New line characters such as line feeds and carriage returns are replaced with
.
FileMaker Server Custom Web Publishing with XML and XSLT Comparing strings using Perl 5 regular expressions You can use the fmxslt:regex_contains() extension function to compare strings using Perl 5 regular expressions. A regular expression comparison is an advanced type of text matching that enables you to determine if a string matches a specified pattern.
Chapter 6 | Developing FileMaker XSLT stylesheets 71 A common application of this function is to display the checkbox value list in a web page and select the checkboxes in the web page that are selected in the database.
FileMaker Server Custom Web Publishing with XML and XSLT Using the date, time, and day extension functions You can use extension functions to get the current date, time, or day, and to compare any two dates, times, or days. The functions in the following table use the “fm” formats regardless of locale. The “fm” formats are MM/ dd/yyyy for date, HH:mm:ss for time, and MM/dd/yyyy HH:mm:ss for timestamp.
Chapter 6 Date, time, day extension function Data type returned | Developing FileMaker XSLT stylesheets 73 Description fmxslt:compare_time(String time1, String time2) number This function compares two time values. It returns a negative number if time1 is before time2. It returns a positive number if time1 is after time2. It returns a 0 if time1 is identical to time2. Both times must be specified in the “fm” time format.
FileMaker Server Custom Web Publishing with XML and XSLT Letter Date or Time Component Presentation Examples E Day in week Text Tuesday; Tue a Am/pm marker Text PM H Hour in day (0-23) Number 0 k Hour in day (1-24) Number 24 K Hour in am/pm (0-11) Number 0 h Hour in am/pm (1-12) Number 12 m Minute in hour Number 30 s Second in minute Number 55 S Millisecond Number 978 z Time zone General time zone Pacific Standard Time; PST; GMT-08:00 Z Time zone RFC 822 ti
Chapter 6 | Developing FileMaker XSLT stylesheets 75 1 General time zone: Time zones are interpreted as text if they have names. For time zones representing a GMT offset value, the following syntax is used: 1 GMTOffsetTimeZone. GMT Sign Hours:Minutes 1 Sign. + or 1 Hours. Digit or Digit Digit 1 Minutes. Digit Digit 1 Digit. One of the following: 0 1 2 3 4 5 6 7 8 9 Hours must be between 0 and 23, and Minutes must be between 00 and 59.
FileMaker Server Custom Web Publishing with XML and XSLT Checking the error status of extension functions You can use the following extension function within an XSLT stylesheet to check the current error status of the most recently called FileMaker XSLT extension function and handle errors that occur during the processing of your pages: fmxslt:check_error_status() When the fmxslt:check_error_status() function is called, the Web Publishing Engine returns the current error code value for the most recent
Chapter 6 | Developing FileMaker XSLT stylesheets 77 2. Define the extension component and extension functions, with the code that actually implements your extension function. function getValueColor(value) { if (value > 0) return ("#009900"); else return ("#CC0000"); } This example returns a color value based on an input value.
FileMaker Server Custom Web Publishing with XML and XSLT The example below shows a JavaScript XSLT extension function that retrieves a current stock price from Yahoo and makes it available via an XPath function: PAGE 79Chapter 6 | Developing FileMaker XSLT stylesheets 79 Apple Stock Price:
When the Web Publishing Engine processes this stylesheet, it requests the stock information from Yahoo. The get_quote() function parses the stock quote data and returns the data to the stylesheet.
FileMaker Server Custom Web Publishing with XML and XSLT
Chapter 7 Staging, testing, and monitoring a site This chapter provides instructions for staging and testing a Custom Web Publishing site before deploying it in a production environment. Instructions are also provided for using log files to monitor the site during testing or after deployment. Staging a Custom Web Publishing site Before you can properly test your site, you must copy or move the required files to the correct locations on the staging server(s).
FileMaker Server Custom Web Publishing with XML and XSLT 1 is optional and specifies the port that the web server is listening on. If no port is specified, then the default port for the protocol is assumed (port 80 for HTTP, or port 443 for HTTPS). 1 is optional and specifies the folder(s) inside the xslt-template-files folder where the XSLT stylesheet is located. 1 is the name of the stylesheet with an .xsl extension.
Chapter 7 | Staging, testing, and monitoring a site 83 Examples of stylesheets for testing XML output Here are two examples of XSLT stylesheets that are useful for testing XML output. 1 The following stylesheet example outputs the requested XML data without doing any transformation. This stylesheet is useful for displaying the actual XML data that the Web Publishing Engine is using. PAGE 84FileMaker Server Custom Web Publishing with XML and XSLT Using the web server access and error logs Apache (Mac OS): The Apache web server generates an access log file and an error log file. The Apache access log file, which is in the W3C Common Logfile Format by default, is a record of all incoming HTTP requests to the web server. The Apache error log is a record of problems involving processing HTTP requests. For more information on these log files, see the documentation for the Apache web server.
Chapter 7 | Staging, testing, and monitoring a site 85 Using Web Publishing Core internal access logs The Web Publishing Core software component of the Web Publishing Engine generates two internal access log files that are a record of each time the Web Publishing Core is accessed. 1 The wpc_access_log.txt access log is a record of all end-user requests to generate XML and to use FileMaker Server Instant Web Publishing. These requests are routed from the web server directly to the Web Publishing Core.
FileMaker Server Custom Web Publishing with XML and XSLT
Appendix A Valid names used in query strings This appendix describes the valid names of query commands and parameters you can use in a query string when accessing FileMaker data using the Web Publishing Engine. About the query commands and parameters The following is a complete list of the query command names and query parameter names: Query command names Query parameter names –dbnames (See page 91.) –db (See page 94.) –delete (See page 91.) –encoding (XSLT only) (See page 94.) –dup (See page 91.
FileMaker Server Custom Web Publishing with XML and XSLT Guidelines for using query commands and parameters When using query commands and parameters in a query string, keep the following guidelines in mind: 1 A query string must contain only one query command; no more and no less. For example, a query string can contain –new to add a new record, but it can’t contain –new and –edit in the same query string. 1 Most query commands require various matching query parameters in the query string.
Appendix A | Valid names used in query strings 89 About the syntax for a fully qualified field name A fully qualified field name identifies an exact instance of a field. Because fields with common names can be based on different tables, you must use fully qualified names, in some cases, to avoid errors. The syntax for specifying a fully qualified field name is: table-name::field-name(repetition-number).record-id where: 1 table-name is the name of the table that contains the field.
FileMaker Server Custom Web Publishing with XML and XSLT For example, the following URL edits a record in a portal where the parent record has the record ID of 1001. Dependents is the name of the related table, Names is the name of the related field in the portal, and the 2 in Names.2 is the record ID of a portal record. http://192.168.123.101/fmi/xml/fmresultset.xml?–db=employees&–lay=family&–recid=1001 &Dependents::Names.
Appendix A | Valid names used in query strings 91 If you don’t use the .global syntax to identify a global field in a query string, the Web Publishing Engine evaluates the global field along with the remainder of the query string without setting the global field value first. For example: http://192.168.123.101/fmi/xml/fmresultset.xml?–db=employees&–lay=departments&Country.
FileMaker Server Custom Web Publishing with XML and XSLT –edit (Edit record) query command Updates the record specified by the –recid parameter, populating the fields with the contents of any field name/value pairs. The –recid parameter indicates which record should be edited. Required query parameters: –db, –lay, –recid, one or more field name(s) Optional query parameter: –modid, –script Note For information on editing records in a portal, see “Editing records in a portal” on page 89.
Appendix A | Valid names used in query strings 93 1 The query request declarations, consisting of the query identifier declarations and request operations. 1 The search field and value definitions for each query identifier. 1 The –findquery command, at the end of the complete statement. For more information on using the –query parameter, see “–query (Compound find request) query parameter” on page 98.
FileMaker Server Custom Web Publishing with XML and XSLT –view (View layout information) query command If the FMPXMLLAYOUT grammar is specified, retrieves layout information from a database and displays it in the FMPXMLLAYOUT grammar. If a data grammar (fmresultset or FMPXMLRESULT) is specified, retrieves the metadata section of XML document and an empty recordset. Required query parameters: –db, –lay Optional query parameter: –script Examples: To retrieve layout information: http://192.168.123.
Appendix A | Valid names used in query strings 95 Optional with: all query commands in an XSLT request Example: http://192.168.123.101/fmi/xsl/my_template/my_stylesheet.xsl?–db=employees&–lay=departments &–grammar=fmresultset&–encoding=Shift_JIS&–findall See “Setting text encoding for requests” on page 56.
FileMaker Server Custom Web Publishing with XML and XSLT fieldname.op (Comparison operator) query parameter Specifies the comparison operator to apply to the field name that precedes the operator. Comparison operators are used with the –find query command. Value is: The operator you want to use. The default operator is “begins with”.
Appendix A | Valid names used in query strings 97 Example: http://192.168.123.101/fmi/xsl/my_template/my_stylesheet.xsl?–grammar=fmresultset&–db=mydatabase &–lay=mylayout&–findall See “Specifying an XML grammar for a FileMaker XSLT stylesheet” on page 54. –lay (Layout) query parameter Specifies the database layout you want to use Value is: Name of the layout Required with: All query commands except –dbnames, –layoutnames, –scriptnames, and –process (XSLT requests only). Example: http://192.168.123.
FileMaker Server Custom Web Publishing with XML and XSLT Examples: http://192.168.123.101/fmi/xml/fmresultset.xml?–db=employees&–lay=departments&–max=10&–findall http://192.168.123.101/fmi/xml/fmresultset.xml?–db=employees&–lay=departments&–max=all&–findall –modid (Modification ID) query parameter The modification ID is an incremental counter that specifies the current version of a record.
Appendix A | Valid names used in query strings 99 is a request definition for each request declaration. Each request definition consists of a search field and value definition. A minus (–) sign starts the request definition. Syntax: –=&–.value= For example: –q1=typeofanimal&–q1.value=Cat –q2=name&–q2.value=Fluffy Example: Find records of gray cats that are not named “Fluffy.” http://host/fmi/xml/fmresultset.
FileMaker Server Custom Web Publishing with XML and XSLT Examples: http://localhost/fmi/xml/fmresultset.xml?–db=FMPHP_Sample&–lay=English&–relatedsets.filter=none&–findany http://localhost/fmi/xml/fmresultset.xml?–db=FMPHP_Sample&–lay=English&relatedsets.filter=layout &–relatedsets.max=all&–findany http://localhost/fmi/xml/fmresultset.xml?–db=FMPHP_Sample&–lay=English&–relatedsets.filter=layout &–relatedsets.max=10&–findany –relatedsets.
Appendix A | Valid names used in query strings 101 Optional with: –script Example: http://192.168.123.101/fmi/xml/fmresultset.xml?–db=employees&–lay=departments&–script=myscript &–script.param=Smith%7CChatterjee%7CSu&–findall –script.
FileMaker Server Custom Web Publishing with XML and XSLT 1 To pass in multiple parameters, you can create a string delimiting the parameters and have your script parse out the individual parameters. For example, pass “param1|param2|param3” as a list with the “|” character URL-encoded as this: param1%7Cparam2%7Cparam3 1 To treat the text parameter as a value that is not text, your script can convert the text value.
Appendix A | Valid names used in query strings 103 –sortorder (Sort order) query parameter Indicates the direction of a sort Value is: The sort order.
FileMaker Server Custom Web Publishing with XML and XSLT –styletype (Style type) query parameter Generates an XML-stylesheet processing instruction within the output document—setting the value of the type attribute (type=text/css or type=text/xsl)—so you can use client-side, cascading stylesheets (CSS) or XSLT stylesheets with your XML document. See “Using server-side and client-side processing of stylesheets” on page 40. This parameter is used in conjunction with the –stylehref parameter.
Appendix B Error codes for Custom Web Publishing The Web Publishing Engine supports three types of error codes that can occur for Custom Web Publishing: 1 Database and query string errors. The Web Publishing Engine generates an error code for a published database whenever an XML data request occurs. See the next section, “Error code numbers for FileMaker databases.” 1 Web Publishing Engine errors.
FileMaker Server Custom Web Publishing with XML and XSLT Error Number Description 3 Command is unavailable (for example, wrong operating system, wrong mode, etc.
Appendix B | Error codes for Custom Web Publishing 107 Error Number Description 117 The data source is missing 130 Files are damaged or missing and must be reinstalled 131 Language pack files are missing (such as template files) 200 Record access is denied 201 Field cannot be modified 202 Field access is denied 203 No records in file to print, or password doesn’t allow print access 204 No access to field(s) in sort order 205 User does not have access privileges to create new records;
FileMaker Server Custom Web Publishing with XML and XSLT Error Number Description 407 One or both match fields are missing (invalid relationship) 408 Specified field has inappropriate data type for this operation 409 Import order is invalid 410 Export order is invalid 412 Wrong version of FileMaker Pro used to recover file 413 Specified field has inappropriate field type 414 Layout cannot display the result 415 One or more required related records are not available 416 A primary key
Appendix B | Error codes for Custom Web Publishing 109 Error Number Description 711 Import translator cannot be found 714 Password privileges do not allow the operation 715 Specified Excel worksheet or named range is missing 716 A SQL query using DELETE, INSERT, or UPDATE is not allowed for ODBC import 717 There is not enough XML/XSL information to proceed with the import or export 718 Error in parsing XML file (from Xerces) 719 Error in transforming XML using XSL (from Xalan) 720 Error
FileMaker Server Custom Web Publishing with XML and XSLT Error Number Description 807 File is not a FileMaker Pro file or is severely damaged 808 Cannot open file because access privileges are damaged 809 Disk/volume is full 810 Disk/volume is locked 811 Temporary file cannot be opened as FileMaker Pro file 813 Record Synchronization error on network 814 File(s) cannot be opened because maximum number is open 815 Couldn’t open lookup file 816 Unable to convert file 817 Unable to o
Appendix B | Error codes for Custom Web Publishing 111 Error Number Description 1202 Too many parameters in the function 1203 Unexpected end of calculation 1204 Number, text constant, field name or "(" expected 1205 Comment is not terminated with "*/" 1206 Text constant must end with a quotation mark 1207 Unbalanced parenthesis 1208 Operator missing, function not found or "(" not expected 1209 Name (such as field name or layout name) is missing 1210 Plug-in function has already been r
FileMaker Server Custom Web Publishing with XML and XSLT Error Number Description 1410 Extended error (ODBC) 1411 Extended error (ODBC) 1412 Extended error (ODBC) 1413 Extended error (ODBC) Error code numbers for the Web Publishing Engine When the Web Publishing Engine is in Development mode, it generates a specific error page when an error occurs in the Web Publishing Engine itself.
Appendix B | Error codes for Custom Web Publishing 113 Error code value Description MCS-603 The HTTP request for “x” returned an error of type “x” MCS-604 The resource “x” could not be loaded because of an unexpected error MCS-605 The resource “x” could not be loaded because the content-type was invalid MCS-606 The resource “x” could not be loaded because of an XML error in the document MCS-607 The resource “x” could not be loaded because of an authentication problem MCS-700 An unexpected e
FileMaker Server Custom Web Publishing with XML and XSLT Error code value Description Messaging Errors 10200 Unknown messaging error 10201 Message formatting error 10202 Message SMTP fields error 10203 Message “To Field” error 10204 Message “From Field” error 10205 Message “CC Field” error 10206 Message “BCC Field” error 10207 Message “Subject Field” error 10208 Message “Reply-To Field” error 10209 Message body error 10210 Recursive mail error - attempted to call send_email() in
Index A access log files for web server, described 84 access privileges 20 accounts and privileges enabling for Custom Web Publishing 19 Guest account 20 scripts 22 Admin Console for Web Publishing Engine 27 Administration Console for Web Publishing Engine 45 application log 76, 84 ASCII characters, in XML documents 37 authenticated base URI parameter 61 authentication of web users 19 basic 60 password 61 auto-enter attribute 32 available scripts 93 B base URI parameter 61 Basic Authentication for web user
FileMaker Server Custom Web Publishing with XML and XSLT deleting portal records 90 Development mode, Web Publishing Engine 112 document type definitions (DTDs) 30, 34 document() function 61 documentation 9 documentation information 9, 18 documents, loading via document() function 61 –dup query command 91 E –edit query command 92 electronic documentation 9 elements database error code 30 in FMPXMLLAYOUT grammar 35 in FMPXMLRESULT grammar 34 in fmresultset grammar 31 email messages extension functions
| fmxslt:get_datetime() function 73 fmxslt:get_day() function 72 fmxslt:get_fm_date_format() function 72 fmxslt:get_fm_time_format() function 72 fmxslt:get_fm_timestamp_format() function 72 fmxslt:get_header() function 67 fmxslt:get_long_date_format() function 72 fmxslt:get_long_day_format() function 72 fmxslt:get_long_time_format() function 72 fmxslt:get_session_object() function 64 fmxslt:get_short_date_format() function 72 fmxslt:get_short_day_format() function 72 fmxslt:get_short_time_format() function
FileMaker Server Custom Web Publishing with XML and XSLT K keywords for enabling Custom Web Publishing 19, 27, 45 L –lay query parameter 39, 97 –lay.response query parameter 39, 97 layout information, using in stylesheet 62 –layoutnames query command 93 layouts, switching for an XML response 39 limiting portal field rows 100 loading additional documents 61 log files 82, 85 described 83 logging via element 76 pe_application_log.txt 84 pe_internal_access_log.
| –process query command 58, 93 processing a Web Publishing Engine request 12 processing XSLT stylesheets 93 Production mode, Web Publishing Engine 113 protecting published databases 20 publishing on the web connecting to Internet or intranet 17 container field objects 21, 48 database error codes 105 protecting databases 20 QuickTime movies 21 requirements for 17 using XML 15, 27 using XSLT 15, 45, 51 Q query information, accessing in request 59 –query query parameter 98 query strings 37, 54, 87 adding rec
FileMaker Server Custom Web Publishing with XML and XSLT statically defined query strings in XSLT stylesheets 55 storing information in sessions 63, 64 strings comparing via Perl regular expressions 70 using string manipulation extension functions 69 –stylehref query parameter 103 stylesheets about 43 checkboxes, checking for values in 70 client-side 40 comparing strings via Perl regular expressions 70 content buffering, using 63 cookie extension functions 68 date and time format strings 73 date, time
| W web browsers receiving output 12 role in XML requests 26 role in XSLT-CWP requests 44 Web folder, copying container field objects 21 Web Publishing Core illustrated 26, 44 internal access logs 85 Web Publishing Engine Admin Console 27 Administration Console 45 application log 84 benefits of 15 described 12 Development mode 112 generated error codes 105 generating pages from XSLT stylesheet 44 generating XML data 26 generating XML documents 27 Production mode 113 request processing 12 web server log fil
FileMaker Server Custom Web Publishing with XML and XSLT enabling in database 19 error status of extension functions, checking 76 examples of stylesheets 43 extension functions for FileMaker 59 FileMaker-specific XSLT parameters 59 generating pages from XSLT stylesheet 44 –grammar parameter 54 header functions, using 67 JavaScript extensions 76 layout information, using 62 namespaces for 55 query strings for 54 Query Strings Reference 88 server-side stylesheets 43, 51 string manipulation extension fun
