Chapter 3: Getting Started

Working with FileMaker Pro To make good use of WEB·FM you need to be very familiar with FileMaker Pro. It is beyond the scope of this manual to serve as a tutorial for FileMaker Pro, but there are some basic characteristics and functions that you need to be aware of. First, let's deal with some basics that you need to know in order to make WEB·FM really work for you.

Also, review the official HTML 4.0 specification from the World Wide Web Consortium at:

http://www.w3.org/TR/REC-html40/

Naming Hints

Although not required, single word database file names and field names may make your work a little easier. If you are creating a database for the first time for use with WEB·FM, keep field names short and, if possible, avoid spaces. Name your databases succinctly, and stick to the standard alphabet. Avoid using odd characters such as "/","#","< >", etc..

Another excellent idea is to append ".fm" to the end of the name of your database file. It gives you an extra margin of security (explained in the section on security). However, it's not absolutely necessary, so don't worry if you already have your database file names and relationships all set up.

Reserved Field Names

WEB·FM is designed to call upon certain database fields with specific names. Reserved fields are fields often used or required by WEB·FM which allow you to deliver formatted HTML as a response to a database request. You will find more detail on what to put into these fields when you get to the section on Page Generation. For now, just be aware that you should keep them in reserve for use with WEB·FM.
html
The html field generally contains basic "hit list" information for each individual record in a found set that is returned by WEB·FM to the web browser. Typically, it also provides a link to the detail field or Template file which enables a user to select one specific record from the found set for retrieving more detailed information.
detail
The detail field is sometimes used in place of a Template file to deliver detailed information specific to a record you want to return to a web browser. Detail is created as a text calculation field that concatenates (links together) the information from other fields in a specific record and prepares them for delivery in formatted HTML.
header
The header field is typically created as a global field in FileMaker Pro. WEB·FM automatically gets header HTML from the header field whenever the Find or FindAll commands are used. If you leave this field out of your database, a default header defined in the Admin database is supplied.
footer
The footer field works in exactly the same manner as the header, except it's placed at the bottom of the page.
error
The error field allows you to return a customized error message to the web browser whenever a database task can not be completed (e.g. no records are found that match the search criteria). WEB·FM will look for this field whenever an error occurs in the search process. If you leave this field out of your database, WEB·FM will supply a default error.
www
If formatted as a global repeating field with 20 repetitions, the www field will temporarily capture many of the client HTTP request parameters received by the web server. These parameters or "environment variables" can serve various purposes. For more information see the section on Advanced Features.
username, password
The username and password fields are required for editing or deleting an existing record. They should normally be indexed fields of type text. These fields enable every record to have a different username and password for record-level security.
cookie
The cookie field is equivalent to, and may be used in place of, the username and password fields. This field enables authorization to edit or delete an existing record using a browser HTTP cookie value.
recid
The RecID field is actually an automatic, internal database field not visible in Define Fields. Never create a database field with this name. WEB·FM will sometimes find a specific record using a RecID value.
recnum
Every database should have an indexed unique serial number field, normally of type number. This field is useful to WEB·FM in searching for and identifying individual database records. If you are starting your database from scratch, create this field with the option to auto-enter a serial number. If you are modifying an existing database, you need to create the serial number field, Find All records in your database, and use FileMaker Pro's Replace command (found in the Edit menu) to enter a new set of serial numbers.
Now that you are aware of reserved field names, let's look at what you do with some of those fields. Publishing a Database File WEB·FM 4.0 relies partly on Template files and partly on database calculation fields to dynamically build and deliver HTML documents for publication on the web. Template files are easier to use and design, but HTML calculation fields can be far more powerful. In the case of calculation fields, WEB·FM's job is to grab HTML from these fields and serve them to the web browser. By relying on calculation fields you have complete control over the HTML formatting of your documents, including direct access to over 100 powerful calculation functions supported by FileMaker Pro.

The following few pages go through the precise process of writing an HTML page inside a FileMaker Pro calculation field. We will take a look at the required "html" calculation field, and the optional "detail" calculation field. Keep in mind that only the "html" calculation field is required for the purpose of returning a found set of records. Most of your dynamic web pages that return a single record of information will be Template files as discussed in Chapter 7: Page Generation.

  1. Make a copy of an existing database file you have already, or make a new database file altogether with fields for a solution you wish to publish on the web.

  2. Go to "Define FieldsÉ" and create a new field of type calculation with name "html". The "html" field is the most important field you will add in order to web-enable your database.

  3. In the "Specify Calculation" dialog for this field enter the calculation formula in the screen shot shown below.

  4. Replace "DATABASE+NAME" with the actual name of your database. Any spaces in the database name should be replaced with a "+" character.

  5. Replace "FIELDNAME" with an actual field name from your database.

  6. If you have a unique serial number field with a name other than RecNum, then replace "RecNum" with the name of your unique serial number field.

  7. Select "TEXT" as the calculation result and click OK.

    NOTE Steps 8 and 9 below are optional. They are presented here only as an example of a complex detail calculation. To return a "detail" field, the "html" calculation formula shown above should be modified, replacing "html=detail.html" with "html=detail".

  8. Go to "Define FieldsÉ" and create a new field of type calculation with name "detail".

  9. In the Specify Calculation dialog for this field enter a simple calculation formula for evaluating a detailed HTML document for a specific database record. The screen shot below is a complex example from the EdExpert.fm database.

  10. Click the Storage Options button and check the option for "Do not store calculation results Ñ calculate only when needed".

  11. Exit "Define FieldsÉ". ABOUT QUOTATION MARKS One naggy little problem with the creation of calculation fields is that proper HTML calls for quotation marks surrounding a URL location or entity attribute. FileMaker Pro interprets a double quote surrounding a URL location or entity attribute as the beginning or end of a text string and hence will not generate the double quote in the resulting HTML text.

    Fortunately, there are other options for including quotation marks in a calculation formula. The easiest is to use a single quote mark anywhere a quote mark in a text string is needed. The HTML specification allows for either single or double quotes surrounding a URL location or entity attribute. This does not apply to what's known as"smart" or "curly quotes", so go into your FileMaker Pro document preferences and turn "curly quotes"off. Additional Hints Calculation fields can increase the size of a database very quickly. Also, editing a calculation field again and again to get proper HTML can be time consuming when the database is large and FileMaker Pro performs a recalculation every time a modification is made. To make the task of creating and tweaking your database fields less painful, it's a good idea to set the "Storage Options" for the field's calculation to "Do not store calculation results Ñ calculate only when needed".

    However, this recommendation may not apply to the "html" field containing only a small amount of information that is typically returned in a "hit list". Certainly, indexing of HTML calculation fields can and should always be turned off.

    Returning a Custom Header and Footer

    WEB·FM provides a default setting utilizing the variables Header and Footer which allow you to return a customized header or footer from global fields that you set up in the database.

    Use "Define FieldsÉ" in FileMaker Pro and add new fields to the target database of type Global with the name "header" and "footer". In Browse mode paste the HTML for a custom header into this "header" field and custom footer HTML into the database "footer" field. Now, whenever a database query occurs with the Find or FindAll commands, the custom HTML in these two fields will be returned to the web browser as portions of the HTML document. The "header" and "footer" HTML can be returned when other commands are used, but in such a case it must be explicitly specified in a FORM or a Link by using the INPUT variables "header" and "footer".

    Example:

    <INPUT TYPE=hidden NAME=header VALUE=header>
    <INPUT TYPE=hidden NAME=footer VALUE=footer>

    Returning an Error When No Records Are Found

    Global fields in FileMaker Pro allow you to create a cell of information that is the same in every record. With regard to WEB·FM, Global fields work very well as HTML delivery systems for elements that will be the same on any page (header and footer fields, for example), as well as self-contained messages that you want delivered when something is amiss (error messages would be the most common example of this type of use).

    Use "Define FieldsÉ" in FileMaker Pro and add a new field to the target database of type Global with the name "error". In Browse mode paste the HTML for a custom error message into this database "error" field. Now, when a Find results in no records found, the HTML in the "error" field will be returned to the web browser by default.