FileMaker Server 7 Advanced Custom Web Publishing Guide
© 2004 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. FileMaker documentation is copyrighted. You are not authorized to make additional copies or distribute this documentation without written permission from FileMaker.
Contents Chapter 1 Introducing Custom Web Publishing About this guide Creating dynamic web sites with the Web Publishing Engine About Custom Web Publishing with XML About Custom Web Publishing with XSLT About the tools for developing XSLT stylesheets Web publishing requirements What is required to publish a database using Custom Web Publishing What web users need to access a Custom Web Publishing solution Connecting to the Internet or an intranet New features in Custom Web Publishing with XML and XSLT File
Custom Web Publishing Guide Accessing XML data via the Web Publishing Engine About namespaces for FileMaker XML About FileMaker database error codes Retrieving the document type definitions for the FileMaker grammars Using the fmresultset grammar Description of elements in the fmresultset grammar Example of XML data in the fmresultset grammar Using other FileMaker XML grammars Description of elements in the FMPXMLRESULT grammar Example of XML data in the FMPXMLRESULT grammar Description of elements in t
Contents 5 Using FileMaker XSLT stylesheets in a web site or program Troubleshooting XSLT stylesheets 45 46 Chapter 5 Developing FileMaker XSLT stylesheets Using XSLT stylesheets with the Web Publishing Engine About the FileMaker XSLT Extension Function Reference 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 namespa
Custom Web Publishing Guide Chapter 6 Testing and monitoring a 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 71 71 72 72 73 73 73 Appendix A Valid names used in query strings About the query commands and parameters Obsolete request names and parameters Guidelines
Contents 7 –max (Maximum records) query parameter –modid (Modification ID) query parameter –recid (Record ID) query parameter –script (Script) query parameter –script.prefind (Script before Find) query parameter –script.presort (Script before Sort) query parameter –skip (Skip records) query parameter –sortfield (Sort field) query parameter –sortorder (Sort order) query parameter –styletype (Style type) query parameter –stylehref (Style href) query parameter –token.
Custom Web Publishing Guide
Chapter 1 Introducing Custom Web Publishing With FileMaker® Server 7 Advanced, you can publish FileMaker databases on the Internet or an intranet in these ways: 1 Custom Web Publishing using Extensible Markup Language (XML) 1 Custom Web Publishing using Extensible Stylesheet Language Transformations (XSLT) stylesheets 1 Instant Web Publishing. See the FileMaker Instant Web Publishing Guide.
Custom Web Publishing Guide About this guide This guide assumes you are experienced with XML and XSLT, developing web sites, and using FileMaker Pro to create databases.
Introducing Custom Web Publishing 11 1 Control and filtering of published data: By using XSLT stylesheets, you can control and filter the data and the type of database information you want to publish, which prevents unauthorized use of the database. You can also hide metadata, such as database and field names. 1 Based on open standards: You have more access to tools, resources and skilled personnel for Custom Web Publishing solutions.
Custom Web Publishing Guide 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, the following are required: 1 1 1 1 1 1 a Windows- or Mac OS X-based computer running FileMaker Server, enabled for Custom Web Publishing one or more FileMaker Pro databases hosted by FileMaker Server the FileMaker Server Web Publishing Engine, installed and configured a web server, either Microsoft IIS on Windows
Introducing Custom Web Publishing 13 1 Like FileMaker Pro, access to data, layouts, and fields is based on the users’s account settings defined in the database’s access privileges. The Web Publishing Engine also supports several other security enhancements. See “Protecting your published databases” on page 18. 1 Web users can perform complex, multi-step scripts. About 70 script steps are now supported on the web. See the next section, “FileMaker scripts and Custom Web Publishing.
Custom Web Publishing Guide 1 If your scripts contain steps that are unsupported, for example, steps that are not web-compatible, use the Allow User Abort script step to determine how subsequent steps are handled. 1 If the Allow User Abort script step option is enabled (on), unsupported script steps will stop the script from continuing. 1 If Allow User Abort is off, unsupported script steps are skipped over and the script continues to execute.
Introducing Custom Web Publishing 15 Script step Behavior in Custom Web Publishing solutions Go to Field You cannot use Go to Field to make a particular field active in the web browser, but you can use this script step in conjunction with other script steps to perform tasks. For example, you can go to a field, copy the contents, go to another field and paste the value. To see the effect in the browser, be sure to save the record with the Commit Record script step.
Custom Web Publishing Guide Where to go from here Here are some suggestions for what to do and where to find information in the documentation to get started developing Custom Web Publishing solutions: 1 If you haven’t already done so, use FileMaker Server Administration and the Web Publishing Engine Administration Console to enable Custom Web Publishing. See FileMaker Server Administration Help and the FileMaker Server Advanced Web Publishing Installation Guide.
Chapter 2 Preparing databases for Custom Web Publishing Before you can use Custom Web Publishing with a database, there are some steps you must take to 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 either Custom Web Publishing with XML or Custom Web Publishing with XSLT, or you can enable both technologies in each database.
Custom Web Publishing Guide 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.
Preparing databases for Custom Web Publishing 19 About publishing the contents of container fields on the web The contents of a container field, such as an image file, can either be stored inside a FileMaker database, or stored as a file reference using a relative path. Note The Web Publishing Engine does not support movie file streaming. Web users must download an entire movie file before being able to view the movie.
Custom Web Publishing Guide
Chapter 3 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.
Custom Web Publishing Guide 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.
Accessing XML data with the Web Publishing Engine 23 To access XML data in a portal, set the view for the database layout to View as Form or View as List. If a user or script changes the view of the database layout to View as Table, only the first related record (first row of the portal) is accessible as XML data. 3.
Custom Web Publishing Guide 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 fmresultset grammar” on page 27 and “Using other FileMaker XML grammars” on page 29.
Accessing XML data with the Web Publishing Engine 25 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.jpg Note The referenced container object must be stored in the FileMaker Pro Web folder when the record is created or edited, and then copied or moved to a folder with the same relative location in the root folder of the web server software.
Custom Web Publishing Guide 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.
Accessing XML data with the Web Publishing Engine 27 Using the fmresultset 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.xml For example: http://192.168.123.
Custom Web Publishing Guide The element represents a portal. Each related field in a portal is represented by the element contained within the element. If there are multiple related fields in a portal, the field definitions for the related fields are grouped within a single element.
Accessing XML data with the Web Publishing Engine 29 /fmi/xml/cnt/data.
Custom Web Publishing Guide To use the FMPXMLLAYOUT grammar, specify the following grammar name with the –view query command in the URL requesting the XML document from the Web Publishing Engine: FMPXMLLAYOUT.xml For example: http://192.168.123.101/fmi/xml/FMPXMLLAYOUT.xml?-db=employees&-lay=family&-view Note When specifying the FMPXMLRESULT and FMPXMLLAYOUT grammars, be sure to enter the grammar name in uppercase.
Accessing XML data with the Web Publishing Engine 31 Village Market Camille Pissarro /fmi/xml/cnt/data.
Custom Web Publishing Guide Example of XML data in the FMPXMLLAYOUT grammar The following is an example of XML data generated with the FMPXMLLAYOUT grammar. 0 PAGE 33Accessing XML data with the Web Publishing Engine 33 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.
Custom Web Publishing Guide Use this query command name To execute this command –findany Find a random record –layoutnames Retrieve names of all available layouts for a hosted and web-shared database –new New record –scriptnames Retrieve names of all available scripts for a hosted and web-shared database –view Retrieves layout information from a database if the FMPXMLLAYOUT grammar is specified.
Accessing XML data with the Web Publishing Engine 35 Switching layouts for an XML response The –lay query parameter specifies the layout you want to use when requesting XML data. Often, the same layout is appropriate for processing the data that results from the request. In some cases, you might want to search for data using a layout which contains fields that, for security reasons, don’t exist in another layout you want to use for displaying the results.
Custom Web Publishing Guide query parameters, which prevent the use of unauthorized query commands and query parameters, such as database names. See chapter 4, “Introduction to Custom Web Publishing with XSLT” and chapter 5, “Developing FileMaker XSLT stylesheets.
Chapter 4 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 two tools to help you get started creating XSLT stylesheets—the Site Assistant and the CDML Converter. For more detailed information about how FileMaker XSLT stylesheets are constructed, see chapter 5, “Developing FileMaker XSLT stylesheets.
Custom Web Publishing Guide 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, such as how to use the FileMaker-specific XSLT extension functions and query commands and parameters. The Site Assistant and the CDML Converter are tools to help you get started creating stylesheets and learn how they are constructed.
Introduction to Custom Web Publishing with XSLT 39 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 Web Publishing Engine Administration Console, make sure XSLT Publishing is enabled. See the FileMaker Server Advanced Web Publishing Installation Guide. 2.
Custom Web Publishing Guide Using the FileMaker Site Assistant to generate FileMaker XSLT stylesheets The FileMaker 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. The 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.
Introduction to Custom Web Publishing with XSLT 41 Starting the Site Assistant To start the Site Assistant, do one of the following: 1 Double-click the FileMaker Site Assistant application icon. 1 Windows: Click the Start button, and choose FileMaker Site Assistant from the Programs menu. FileMaker Site Assistant Using the Site Assistant For detailed information and step-by-step procedures for using the Site Assistant, see the Site Assistant Help.
Custom Web Publishing Guide 1 The element is used to access query information in a request or HTML form data. For example, this element can be used in the Site Assistant stylesheets to access the current request query information to determine the current location in a found set of records and to create links to the previous and next record. See “Accessing the query information in a request” on page 55.
Introduction to Custom Web Publishing with XSLT 43 Starting and using the CDML Converter Important It is recommended that you first copy all of the files from the cdml_format_files folder (if you chose to use it) and all of the files from your FileMaker Pro Web folder to a temporary working folder, and do the conversion processing on the copied files. Note When converting a source file to an XSLT stylesheet, the CDML Converter keeps the same filename but changes the filename extension to .xsl.
Custom Web Publishing Guide 6. Locate and select the folder where you want to save the XSLT stylesheets on your hard disk, then click Select. 7. Click Start. The CDML Converter converts the CDML format files and saves a conversion log with the converted XSLT stylesheets in the destination folder you specified. The conversion log is also shown in the CDML Converter window. 8. Click Done.
Introduction to Custom Web Publishing with XSLT 45 1 If the converted XSLT stylesheets include a FileMaker date or time extension function, such as fmxslt:get_date(), then the function uses the configured locale for FileMaker Server. See “Using the date, time, and day extension functions” on page 66. After conversion, you must manually change and localize date and time formatting strings that are passed to these functions, such as changing Month/Day/Year to Day/Month/Year.
Custom Web Publishing Guide Note For web sites, it’s a good practice to include an XSLT stylesheet as a home page that doesn’t require users to enter a query string to access it. The Site Assistant can create a home.xsl that doesn’t require a query string because it uses the processing instruction. For example, if you copied your stylesheets (including a home.
Chapter 5 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.
Custom Web Publishing Guide About the FileMaker XSLT Extension Function Reference The FileMaker Server Advanced CD includes a FileMaker database called XSLT Reference.fp7 that contains brief descriptions and examples of each of the FileMaker XSLT extension functions. You can open the FileMaker XSLT Extension Function Reference in the Custom Web Publishing Reference folder on the FileMaker Server Advanced CD.
Developing FileMaker XSLT stylesheets 49 For example: /fmi/xsl/cnt/data.jpg?-db=products&-lay=sales&-field=product_image(1)&-recid=2 Note In the generated XML for a container field, the value for the -field query parameter is a fully qualified field name. The number in the parentheses indicates the repetition number for the container field, and is generated for both repeating and non-repeating fields. See “About the syntax for a fully qualified field name” on page 77.
Custom Web Publishing Guide Specifying an XML grammar for a FileMaker XSLT stylesheet The recommended XML grammar to use with Custom Web Publishing with XSLT is the fmresultset grammar, which has been designed for ease of use with XSLT. See “Using the fmresultset grammar” on page 27. You can also use the older FMPXMLRESULT or FMPXMLLAYOUT grammars. To access value lists and field display information in layouts, you must use the FMPXMLLAYOUT grammar. See “Using other FileMaker XML grammars” on page 29.
Developing FileMaker XSLT stylesheets 51 Using statically defined query commands and query parameters You can prevent the unauthorized use of query commands and query parameters with your FileMaker XSLT stylesheet by statically defining the query commands and parameters that you want to use when XML data is requested.
Custom Web Publishing Guide Setting text encoding for requests The Web Publishing Engine performs the following steps in the order shown until it determines the encoding of an XSLT request: 1. Checks if the charset attribute is set in the Content-Type request header. 2. Checks if you specified an encoding with the –encoding query parameter. You can specify this parameter in a URL or as a statically defined query parameter in the processing instruction.
Developing FileMaker XSLT stylesheets 53 Specifying an output method and encoding You can specify an output method and encoding of output pages by using the method and encoding attributes of the element. Both of these attributes are optional. The method attribute specifies the type of output, which can be “html”, “text”, or “xml”. No other method types are supported. If you don’t specify a method, the Web Publishing Engine uses the “html” method.
Custom Web Publishing Guide Using tokens to pass information between stylesheets You can use the –token query parameter in a URL or as a statically defined query command to pass any user-defined information between stylesheets without using sessions or cookies. The –token query parameter is optional with all query commands. The user-defined parameter value can be any character string that is URL encoded. For example: http://192.168.123.101/fmi/xsl/template/my_stylesheet.
Developing FileMaker XSLT stylesheets 55 Accessing the query information in a request You can use a FileMaker XSLT parameter to access query information in a request in a URL or HTML form data. For example, you can access the current request query information to determine the current location in a found set of records, and create links to the previous and next record.
Custom Web Publishing Guide Obtaining client information You can use the following FileMaker XSLT parameters to obtain information from the Web Publishing Engine about a web client’s IP address, user name, and password: Include these parameter statements in your XSLT stylesheet before the top element.
Developing FileMaker XSLT stylesheets 57 Loading additional documents To load an additional XML document during the processing of an XSLT stylesheet, use the standard XSLT document() function with a URI to the XML document. The document() function returns the requested XML as a node-set that can be stored in an element. To load an XML document that contains data from a FileMaker database, use the document() function with FileMaker query command and parameters.
Custom Web Publishing Guide For example, suppose you wanted to create a pull down menu for a field named Color that is populated with the values from a value list named shirts that are defined in a layout in a FileMaker database. Here’s how you can use the document() function to load the layout information into a XSLT variable: PAGE 59Developing FileMaker XSLT stylesheets 59 By default, the Web Publishing Engine will use a cookie to store the session ID. To accommodate clients that do not allow cookies, you can use the fmxslt:session_encode_url() function to add the Session ID to the URL. To guarantee compatibility in all situations, it is recommended that you encode all URLs written out to the page with the fmxslt:session_encode_url() function.
Custom Web Publishing Guide Session extension function fmxslt:set_session_object(String session-name, String name, Object value) Data type returned Description XSLT object (number, string, boolean, or node-set) Stores an XSLT object (a number, string, boolean, or node-set) under a session, which can be later retrieved using the fmxslt:get_session_object () function. This function also returns the previously stored object under the specified session object name.
Developing FileMaker XSLT stylesheets 61 Sending email messages from the Web Publishing Engine You can use the Web Publishing Engine to generate email messages, which is useful for custom web solutions. To have the Web Publishing Engine send an email message, use one of the following three fmxslt:send_email () extension functions in an XSLT stylesheet. You can use these functions to send one or more separate messages.
Custom Web Publishing Guide 1 The individual values for the smtpFields parameter, such as the subject, must be a URL-encoded string. For example, the “&” character must be specified as “&” and blank spaces must be specified as “%20”. The entire string for the smtpFields parameter must be XML-encoded. (See the example at the end of this section.) 1 For each of these functions, a value of true() is returned if the email message is successfully sent; otherwise false() is returned.
Developing FileMaker XSLT stylesheets 63 Notes 1 The name used in the fmxslt:get_header() and fmxslt:set_header() functions, and the value in the fmxslt:set_header() function can be a string of any length. 1 The fmxslt:set_header() function and the fmxslt:set_status_code() function require the processing instruction. See “Using content buffering” on page 58. The following example demonstrates how to set the value of the header. Suppose you are using a stylesheet to output a vCard.
Custom Web Publishing Guide 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
.
Developing FileMaker XSLT stylesheets 65 String manipulation extension function Data type returned fmxslt:url_decode(String value, String encoding) string Description Returns a URL-decoded string using the character encoding you specify for the encoding parameter, which can be: US-ASCII, ISO-8859-1, ISO-8859-15, ISO2022-JP, Shift_JIS or UTF-8. Use this function in situations where you must specify the character encoding used in a URL encoded string in order to decode the string properly.
Custom Web Publishing Guide [ ] Large If a user selected Red only, then the field would contain the string “Red.” To determine whether the field contains “Blue”, you could use the following function call: fmxslt:contains_checkbox_value(,'Blue') where is the XPath to the element for the checkbox field. The function would return “false” in this example.
Developing FileMaker XSLT stylesheets 67 1 Long day format is: EEEE (in all locales) For example: “Sunday” Date, time, day extension function Data type returned Description fmxslt:get_date() string Returns the current date in the short format. fmxslt:get_date(String format) string Returns the current date in the format you specify. Enter the string “short” or “long” for the format parameter. fmxslt:get_time() string Returns the current time in the short format.
Custom Web Publishing Guide The functions in the following table use custom date formatting strings that specify a date and time format. See the next section, “About the date and time format strings.” Date, time, day extension function Data type returned Description fmxslt:get_datetime(String dateFormat) string Returns the current date and time using the date and time format strings.
Developing FileMaker XSLT stylesheets 69 Letter Date or Time Component Presentation Examples z Time zone General time zone Pacific Standard Time; PST; GMT-08:00 Z Time zone RFC 822 time zone -0800 Pattern letters are usually repeated, as their number determines the exact presentation: 1 Text: For formatting, if the number of pattern letters is four or more, the full form is used; otherwise a short or abbreviated form is used if available.
Custom Web Publishing Guide The following examples show how date and time patterns are interpreted in the U.S. locale. The given date and time are 2001-07-04 12:08:56 local time in the U.S. Pacific Time time zone. Date and Time Pattern Result "yyyy.MM.dd G 'at' HH:mm:ss z" 2001.07.04 AD at 12:08:56 PDT "EEE, MMM d, ' 'yy" Wed, Jul 4, '01 "h:mm a" 12:08 PM "hh 'o' 'clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time "K:mm a, z" 0:08 PM, PDT "yyyyy.MMMMM.dd GGG hh:mm aaa" 02001.July.
Chapter 6 Testing and monitoring a site Test your Custom Web Publishing site before deploying it. You can use log files to monitor the site during testing or after deployment. Testing a Custom Web Publishing site Before notifying users that your Custom Web Publishing site is available, it is important to verify that it looks and functions as you expect. 1 Test features like finding, adding, deleting, and sorting records with different accounts and privilege sets.
Custom Web Publishing Guide 1 When debugging a stylesheet, you can use the following example of an HTML
