Chapter 6: FORM Basics

Most often, you will access information in your database through an HTML fill-out form. Mandatory attributes for the FORM element include METHOD and ACTION, where METHOD specifies how the form contents are sent to the web server, and ACTION is the URL of the web server to which the form contents will be submitted.

WEB·FM uses the ACTION attribute in the FORM element to specify the name of the target FileMaker Pro database to receive the form contents. Including a ".fm" suffix on the end of the database name in the URL will flag the web server in recognizing the request as a database transaction to be handled by WEB·FM. Although recommended that the actual database file name optionally have a ".fm" suffix, it's not required. Still, if you store the database in the web server directory tree, then it is a good idea to name the database with a ".fm" suffix for security reasons.

Because space characters in a URL are illegal, and many database documents include spaces in their name, it's important that we replace these space characters, if any, in the URL with a "+" character.

Example:

In a form you can include INPUT, SELECT, and TEXTAREA tags to specify fields and their interface elements. As you create a form, your primary task is to decide which database fields you want WEB·FM to handle, then place INPUT elements in your form that match the names of those database fields.

IMPORTANT NOTE The field names in the database that you want to Find on or Add to must match EXACTLY the INPUT elements on your FORM. If the INPUT elements on a form do not match the database field names EXACTLY (spelling and punctuation) WEB·FM will not be able to map values to database fields.

An INPUT element of type "submit" is a pushbutton that causes the current form contents to be packaged into a string of "name=value" pairs and sent to an origin web server. WEB·FM expects the name (not the value) of the submit pushbutton to match the command desired for the form. When the name of the submit button is not recognized as a valid command, WEB·FM will default to performing a Find request using the submitted form values. Legal commands are:

Find
FindAll
FindUser
Retrieve
Random
Add
Update
Delete

TIP "A 'submit' element is required in all forms except those containing only a single INPUT element of type TEXT (in which case Return in the text entry area submits the form) or at least one INPUT element of type IMAGE (in which case a click in the image submits the form)."

Building a Find Form

Begin your form with standard DOCTYPE, HTML, HEAD, and BODY elements and follow with a FORM element that specifies the target database.

Example:

Next, place inside the form variables for returning the contents of the 'header', 'footer', 'html' database fields to the web.

Next, place inside the form variables for sorting all found records, while returning only a few.

Next, place inside the form INPUT elements for fields you wish to search on. The following HTML allows a user to search the ExExpert.fm example database by username and company.

Example: Name:

<INPUT NAME="username" VALUE=""> Company:

<INPUT NAME="company" VALUE=""> Specify the Find command in the NAME attribute of the 'submit' pushbutton. Example:

<INPUT TYPE="submit" NAME="Find" VALUE="Submit"> The form you just created allows a user to search by name and company. It then sorts all found records, returning HTML from a maximum of 10 records. Finally, in case no records are found we need to include the Error variable with a value for an error Template file located on disk in the same relative directory as the current URL.

Finding on Relational Fields

To search on a relational database field, include the variable Layout in your form with a value that exactly matches the name of the database layout containing the relational field. Relational and portal fields must exist on the target database layout in order to use them.

Relational fields must be referred to by a special name that begins with the name of the database relationship, followed by two colons "::" and the actual field name.

Example:

N O T E The relationship name is NOT the name of the related database. It is the name you gave the relationship in the "Define RelationshipsÉ" dialog. (For more information, refer to the FileMaker Pro documentation on relational fields).

Using Operators

A typical form will query a target database with an "AND" find criteria. In other words, every query term submitted must be present on a record for that record to be found. To change the method in which records are searched, include the variable Operator in a form with a value for the type of search desired. As mentioned previously, there are 11 options for Operator that are largely self explanatory. These options apply to the entire form and are NOT field specific. "Begins With" is the default query method for a find unless otherwise specified. FileMaker Pro specific symbols for finding duplicates, current date, single character or invalid date or time are NOT by default recognized characters. If a search requiring one of these special characters in the query text is required, you MUST use the "request" value with the Operator variable. The "OR" operator tells WEB·FM to search ALL submitted fields with an OR criteria, with one exception. The Field and Value variables always use the AND operator. Essentially, this provides a combined AND/OR find criteria.

Massaging Found Records

Sorting Found Records

Sort is an INPUT variable whose value is a field name in the target database. When a form is submitted, WEB·FM intercepts this variable and sorts the found records by the field name specified. Nested sorts are possible by simply having two interations of the Sort variable, each having a different value. You can make the Sort variable a select menu or another type so the user can choose which database field to sort on.

Example:

TIP For performance reasons, WEB·FM does not always show a found set of records in the database unless a sort or script is required. To force showing all records found without actually sorting, include the Sort variable but without a field name value.

Sorting found records in ascending or descending order is possible by including the variable Sortorder in a form with a value of "ascending" or "descending". As mentioned before, since WEB·FM sorts records in ascending order by default, it is only necessary to use this variable if you need to sort in "descending" order.

TIP Refer to Chapter 8: Processors for information on using a Filter processor to filter incoming requests using an alternate to the sortorder variable of "sort=up" or "sort=down".

Returning Found Records

Include the variable HTML in a form with a value equal to a database field name containing the HTML to be returned after a successful Find. Should this variable be omitted, the default is to return the database field named "html". Refer to the EdExpert solution for an example of using the HTML variable in a form as a radio button so the user can dynamically choose the database field to return - and hence the preferred HTML formatting for the "hit list" of found records. Example:

After a successful Find, the contents of the field "html" are returned by WEB·FM from each record found. After submitting the search form the web browser will display what is commonly referred to as a "hit list" of found records. The HTML returned to the web browser is the result of FileMaker Pro evaluating the field's calculation formula for each record. The formula includes normal text, HTML tags, and most importantly the values from other database fields who's information is desired. This is accomplished by concatenating fields in the formula with HTML.

The simplest formula for a basic "html" field utilizes the Retrieve command and might look something like this example: "

<LI><A href='EdExpert.fm$retrieve?RecNum=" & RecNum & "&html=detail.html'>" & Company & "</A><P>"

Returning a Range of Found Records

It's often better to return only a range of found records rather then all records found with a successful find. Use the variable Max in your form with a numeric integer value equal to the maximum number of records you wish to return with a single database Find.

Example:

Refer to the section on [token] support for information on including a "Next Page" link for displaying the next or previous [max] set of found records.

Creating a New Record

Begin a new record the same way you started the previous FORM; by creating a URL that tells WEB·FM what database to work with.

Example:

Next, include INPUT elements that match exactly the field names in the FileMaker Pro database that you are working with.

Example:

Name: <INPUT NAME="first name" VALUE=""><P>
Company: <INPUT NAME="company" VALUE=""><P>

Tell WEB·FM what action to perform by naming the submit pushbutton "Add".

Example:

It's always a good idea to target a specific database layout for creating a new record. Performance will be improved because WEB·FM will only have to interface with a small subset of database fields (those on the target layout) and not all fields in the entire database. The layout variable you place on your fill-out FORM will look something like this:

It's important to include on your form the HTML variable for specifying a Template file containing a response page. In the case below, WEB·FM will return a Template file for a detail confirmation page with record values dynamically substituted.

Example:

The complete submission form might look like this:

<FORM METHOD="POST" ACTION="EdExpert.fm ">
<INPUT TYPE="hidden" NAME="layout" VALUE="data entry">
<INPUT TYPE="hidden" NAME="html" VALUE="detail.html">
Name: <INPUT NAME="first Name" VALUE=""><P>
Company: <INPUT NAME="Company" VALUE=""><P>
<INPUT TYPE="submit" NAME="add" VALUE="submit">
</FORM>

Having created the two most basic (and most often used) forms, let's take a look at some ways WEB·FM allows you to include greater functionality.

Support for Data Validation

Performing data validation on submitted field values (before a new record is created) is limited to checking whether the submitted value for a field is empty or not. To enable data validation, go to "Define Fields..." in FileMaker Pro and open the Data Validation dialog for the desired field and check the "Not empty" option. You MUST also enable the "auto-enter data" option for this field and have it automatically enter a space, otherwise an error will likely occur.

Should an INPUT element be submitted with no value when data validation for this field is enabled in the database, WEB·FM will not create the record and instead return a basic validation error message.

Support for Checkboxes

A form may contain multiple INPUT elements with the same name. Multiple checkboxes, for example, often have the same name but different values. When creating a new database record, WEB·FM will enter the values of fields with the same name into the database field with return delimiters so that FileMaker Pro can display the information as checkboxes on the database layout. The exception is with repeating and portal fields.

Support for Repeating Fields

If a database field is formatted as a Repeating field, WEB·FM will enter the values of fields with the same name into the repeating cells. A field defined as repeating in the database, but formatted on the target layout as a normal field will receive all values only in the first repeating cell with return delimiters. Make sure there are enough repetitions for the submitted data or an error will occur.

Support for Relational/Portal Fields

WEB·FM will add information to relational and portal fields, provided a target layout is specified using the Layout variable, and the name of the INPUT element on the submitted form is named properly. The name of the field should equal the name of the database relationship followed by two colons "::" and ending with the actual database field name in the related database.

Example:

If multiple values for a portal field are received, WEB·FM will create a new portal row for each value.

Incoming HTTP request substitution [tokens]

[username] Username for current authentication scheme

[password] Password for current authentication scheme

[browser] Client Browser

[domain] Domain name or IP address of client

[referer] Referring document

[cookie] Use with CookieCutter Processor to insert client "cookie" values in HTTP request header into the request form arguments.

Example:

Editing A Database Record

WEB·FM 4.0 significantly enhances features for record-level security. A revised FindUser command supports most Find command features, but with record-level user authentication requirements. This means users can flexibly Find and modify their own, and only their own, records in databases where the permission to Browse records is disabled. Moreover, a client Cookie value may also be used in place or absence of a valid password when finding or updating database records.

Use the FindUser command to return an update form with existing record information. By using FindUser, this update form is not returned unless the user has a valid username and password, or browser "cookie" value.

Example:

If you expect more than one record to be found with FindUser, you should return a "hit list" of found records from the database first, and then select the desired record from this list using a record number identifier.

Example:

Use the Update command on a form if you wish to modify an existing database record with submitted form values. The Update command is equivalent to the Add command, only a new record is not created. Instead, WEB·FM performs a find for a single record, then verifies authorization to update this record. If authentication checks pass, submitted form values will replace existing cell values in the found record.

W A R N I N G Submitting INPUT elements with values that are empty will DELETE existing database cell values.

To Update an existing database record WEB·FM must first find the correct record to update. An update form should contain the following INPUT variables. If no Field and Value variables are specified, WEB·FM still attempts to find the correct record using the username and password, or browser cookie value. In this case, though, [RecID] is a token which gets replaced with the record identifier when the update form is initially retrieved. You may use RecID or the name of another serial number field for the unique record identifier.

Unless you have the administrator password, it is not possible to edit an existing record without first creating new "username" and "password" (or "cookie") fields. Authorization to update is given if the request passes one of the following checks.

Browser username/password exactly matches Admin username/password. Browser username/password exactly matches record username/password. INPUT username/password exactly matches record username/password. Browser cookie value exactly matches record cookie.

Be very careful when updating portal fields. WEB·FM will replace existing portal field values with new values in the order sent by the web browser. There is real potential to edit an incorrect portal row, so test carefully with different browsers before deploying a solution that requires editing existing portal rows.