Installing FMWebFrame

Note: For special instructions on how to install the FMWebFrame Demo application on a Mac that is running Mavericks and FileMaker Server (in a a single-machine deployment), click here.

The steps involved in installing FMWebFrame include:

• Configuring your database for FMWebFrame.
• Adding the FMWebFrame PHP code to your Web application.
• If necessary, installing the FileMaker API for PHP.
• Setting up a custom 404 error handler for your Web application.
• Configuring FMWebFrame's settings.
• Including FMWebFrame in your PHP scripts.

Configuring Your Database

To configure your database for FMWebFrame:

1. Copy the FMWebFrame table from the sample database that is included with FMWebFrame.
2. Paste the FMWebFrame table into your database.
3. An FMWebFrame layout should have automatically been created for you. If necessary, change the name of the layout to: FMWebFrame
   (If you'd like, you can configure that layout so that it does not appear in layout menus. But otherwise, please don't make any changes to it.)
4. Copy the FMWebFrame FileMaker script (named "FMWebFrame") from the sample database that is included with FMWebFrame.
5. Paste the FMWebFrame script into your database.
6. If you do not already have a FileMaker account setup for use by the FileMaker API for PHP, please set one up. The account needs be assigned to a privilege set that has "view only" permissions on the FMWebFrame layout, and "executable only" on the FMWebFrame script. Also, the privilege set that the account is in should have the "fmphp" extended privilege assigned to it. The account also needs to have View, Edit, and Create privileges on any tables that you want to be able to upload files to (via "fmPutContainer"), and View privileges on any tables that you want to be able to perform quick finds on (via "fmQuickFind").

Adding FMWebFrame to Your Application

To add FMWebFrame to your application, put a copy of the "FMWebFrame" folder (available in the download) in your application's PHP folder. Ideally, it should be placed in the root of your Web application.

Installing the FileMaker API for PHP

In order for FMWebFrame's caching functions to work properly, FMWebFrame needs direct access to the FileMaker API for PHP files. Therefore, the FileMaker API for PHP should be manually installed in such a way that you can provide the path to it. For instructions on how to install the FileMaker API for PHP, see "Manually installing the FileMaker API for PHP" in Chapter 2 of the "FileMaker Server 13 Custom Web Publishing with PHP" documentation, which is available here: https://fmhelp.filemaker.com/docs/13/en/fms13_cwp_php.pdf

We recommend installing the API in a folder in the root of your Web application. The folder should be named "FileMaker" and within it should be the FileMaker.php file, and the API's own "FileMaker" sub-folder.

To specify the path to the FileMaker API for PHP, use FMWebFrame's FMAPI_PATH setting as discussed below ("Configuring FMWebFrame's Settings").

Setting Up A Custom 404 Error Handler

In order to use FMWebFrame's container publishing function, you'll need to configure a custom 404 error handler for your Web application. How you do that depends on the type of Web server that you are running and the operating system that it is running on. If you are in a hosted environment, and are unfamiliar with setting up custom error handlers, then your Web hosting provider might be able to assist you.

The server that the FMWebFrame Demo Web site is being hosted on is running Linux and Apache. To configure the 404 error handler, we simply added an ".htaccess" file to our server, and added this line to it:

ErrorDocument 404 /application/404.php

The 404.php file can be as sophisticated as you'd like. However, we recommend that it include this code so that FMWebFrame's container functions work properly:

// Initialize FMWebFrame.
@require_once ( dirname(__FILE__) . '/FMWebFrame/fmwebframe.php' );

// Check to see if the request is for a container.
fmGetContainer( $fm_databases );

You'll find examples of both the .htaccess and 404.php files that we used for the Demo Web site in the FMWebFrame download.

Configuring FMWebFrame's Settings

You configure FMWebFrame by adjusting the "settings.php" file, which is located in the FMWebFrame folder. We've set the default values for the settings so that they will require as few changes as possible.

However, in some cases, you will need to adjust the settings. We think you'll find that the settings file is well documented. Regardless, here's a quick overview of what the various settings do:

• HTTP_ROOT_URL: This is the root URL for your Web application. For example: http://www.fmwebframe.com If your Web application isn't in the root, then specify the folder that it is in. For example: http://www.fmwebframe.com/myapp Be sure to exclude the trailing backslash from the URL. (In other words, use "http://www.fmwebframe.com" and not "http://www.fmwebframe.com/".)
• FMAPI_PATH: This is the operating system path to the FileMaker API for PHP.
• CACHE_PATH: The FMWebFrame Demo Web app is configured with a subfolder that it uses for all temporary files, including the cache, containers, and uploaded files. That folder is named "temp" and is located in the root of the Web application. However, if you'd like to use an alternative folder, or place the temp folder in another location, use the CACHE_PATH setting to tell FMWebFrame where the folder is.
• CONTAINER_PATH: Like CACHE_PATH, the CONTAINER_PATH setting can be used to specify an alternate folder in which published containers are stored.
• UPLOAD_PATH: Can be used to specify an alternate folder in which uploaded containers are temporarily stored during processing.
• UPLOAD_URL: This is the URL that resolves to the folder specified via the "UPLOAD_PATH" setting. FMWebFrame uses this URL to get the uploaded file and place it in the proper container field within the FileMaker database.
• TEST_DB_CONNECTIONS: FMWebFrame can automatically test your database connections before handling requests. To do so, set the TEST_DB_CONNECTIONS setting to TRUE. For high volume Web applications, you might want to set this FALSE to reduce the number of requests sent to the database.
• $fm_databases: This is a PHP array that FMWebFrame uses to establish database connections. The default settings file includes an array element that is configured for the sample database. To add a connection for your database, add a similar array element. Be sure to properly specify the "hostspec" (the IP address or name of your FileMaker database server), the database name, and the username and password of a FileMaker account that you want to use to access the database. (To configure that account properly, see "Configuring Your Database" above.)
• SITE_SHIELD_METHOD: FMWebFrame includes a virtual firewall that can be used to restrict access to the Web application based on visitor IP addresses. For details, see both the inline comments of the settings file as well as the documentation for the fmSiteShield function.
• $site_shield_ips: This is the PHP array that the fmSiteShield function uses to allow or deny visitors access to the Web application.

Including FMWebFrame In Your PHP Scripts

To include FMWebFrame in a PHP script, use PHP's "require_once" function to include the FMWebFrame.php file. For example:

require_once ( dirname (__FILE__) . '/../FMWebFrame/FMWebFrame.php' );

You might need to adjust the path to the FMWebFrame folder based its location relative to your script.