Utilizing the FileMaker PHP API

In previous posts, we detailed a technique to capture the coordinates from a Google map and place these into a record in FileMaker. This is certainly a great way to have your users interact with maps, as long as they are using the FileMaker Pro client. If the solution deploys FileMaker WebDirect, the technique does not work. But we have a way that does and after a number of enquiries about how we did it, we’re finally getting around to documenting this and sharing with others...

The Problem

The issue we’re up against is that previous techniques use the FMP URL protocol to make calls back to the database. WebDirect does not support this. So we need to find a way of displaying a Google map in WebDirect, allow a user to click on the map and then capture those coordinates in a FileMaker record.

It’s worth pointing out that our solution to this is not simple but we’ll step through it bit by bit. Also, due to the nature of the solution, it’s not possible to post a working demo, but we will post the code and details necessary for any reader to use. Of course, there may be other ways of achieving our goal, but this is how we went about it.

Requirements

In order to implement this technique, you will need the following:

• A FileMaker solution hosted on FileMaker Server:
  • This should have a table with records for which you are trying to capture the coordinates – perhaps an address table, for example.
  • It should have a layout based on this table, compatible with WebDirect and a web viewer object in place ready to display the Google map.
• Access to a web server – this can be your own website or potentially the HTTPServer folder on the FileMaker Server.
• A Google API key – this may not be strictly necessary but is recommended. As mentioned in our previous post, it is free to get an API key and the use of the API is free within limits. Be sure to familiarize yourself with the usage guidelines before implementing and sending any solution live.

Integration Concepts

The basic concepts of what we will be doing are:

• Create a PHP page with our map code.
• Create a PHP page that will call our FileMaker script.
• Host these PHP pages on our web server along with the FileMaker PHP API.
• Point our web viewer on our WebDirect layout to this PHP page, passing it some variables when we load the page.
• When the user clicks the map, we will trigger a FileMaker script using the PHP API, passing variables back to the database with our coordinates that we wish to place into fields in the record.
• Parse out these values from our parameter and set fields in our record with these values.

Let’s get started!

Assumptions

For the rest of this article, we will need to assume some conditions and use them ongoing in our example. You can replace these values with your own during implementation:

• Database Filename: XYZ_Database
• Website: https://www.xyz.com
• FileMaker Server address: fmserver.xyz.com
• Table: ADD_Addresses – this is the table in which we are trying to populate records with the latitude and longitude the user selects.
• Fields: ID, City, Country, Latitude, Longitude – here we assume we know the city and country which is close to where we expect the user to click so we can center the map around this area. The latitude and longitude fields are where we will store the clicked coordinates. The ID is the unique record ID (primary key) – generally we use UUIDs for primary keys, but we had some issues when implementing this so, while we kept the UUID, we set up a simple numeric serial number to use for this.
• Layout: ADD.Addresses – this is a layout, based on our table above, which we will use to set the coordinate values. We tend to use a blank layout.
• Script: SetCoordinates – this script is the one we will call after the user has clicked, pass it some parameters and set the coordinate values.
• Username: coordinates_user – this is the name of the user account that opens the database when the coordinates are set.
• Password: something_secret – this is the password of the user account that opens the database when the coordinates are set. You should of course set your own password and not use the demo password.
• Secret Key: 123456 – this can be any random value. Again, do not use the demo value.

Create the map PHP page

So, we need to make a PHP page that will be hosted on our web server/website. This PHP page will show the map to our user in WebDirect via a web viewer and handle the click the user performs to select the required coordinates. This is not hugely different from the code we used in our previous posts. We still use the basic concepts of the Google Maps API to load the map but there’s a couple of differences:

• When we load the map in the web viewer, we will pass it some parameters including (see the web viewer set up section):
  • Our current record ID – we use this when we send back the coordinates to know which record to place the values in.
  • A secret key – a security measure to ensure it was actually WebDirect that requested the script run.
  • A city and country – these are used to center the map to a particular area.
• Instead of calling a FileMaker script using the FMP URL protocol, we call a FileMaker script using the PHP API.

You can download this code here. It is well commented and may not need much adjustment if the rest of the below is followed, but we recommend you read it anyway to see what each section does. The file is named map.php.

In addition, it’s worth pointing out that if your FileMaker Server is protected using a SSL certificate (and your FileMaker Server isprotected with a SSL certificate, right?), then wherever you end up hosting these PHP files, they should also be protected with SSL or your users will see warning errors when the SSL and non-SSL content tries to load in their browser.

Create the FileMaker script PHP page

When the user clicks, the Google Maps JavaScript handles the dropping of the pin on the map, but we need to call the script to run. This is done with a second PHP file that contains the database name, address etc and the script we are calling, the layout we’re using, and parameters to send in. This is not complex, but it does need adjusting to have the right details for your environment.

You can download this code here. The file is named fmperformscript.php.

Upload files to the web server

Now that we have our PHP page for displaying the map, and our PHP page to call our script, let’s get these uploaded to our web server. Create a new folder on the root called _filemaker. Upload map.php and fmperformscript.php to this folder. This assumes that our path to display the map in our web viewer will be https://www.xyz.com/_filemaker/map.php.

That’s great, but we’re not done. We need to upload the FileMaker PHP API to the same folder. You can find this on the installation of FileMaker Server in the following locations:
Windows: \Program Files\FileMaker\FileMaker Server\Web Publishing\FM_API_for_PHP_Standalone.zip 
Mac: /Library/FileMaker Server/Web Publishing/FM_API_for_PHP_Standalone.zip 
Uncompress this file and upload the resulting FileMaker folder and FileMaker.php file to the same folder as above.

So, after all that you should have the following listed in the _filemaker folder on the web server:

• FileMaker folder
• FileMaker.php file
• map.php file
• fmperformscript.php file

 

Set up the Web Viewer

Now that we have the file on the web server that will display the map for our users, we need to point the web viewer to this file. Open the calculation dialog for the web viewer on your WebDirect layout and put this in there (replacing attributes as needed for your environment of course): 
"https://www.xyz.com/_filemaker/map.php?id=" & ADD_Addresses::ID & "&secretKey=123456&city=" & ADD_Addresses::City & "&country=" & ADD_Addresses::Country

So, with this we are pointing to the map.php file and sending in the record ID, secret key (which you will change!), and the city and country to center the map on.

Set up FileMaker Server

There’s not much to do here, but you do need to ensure that PHP Publishing is enabled. Log into your admin console, select the Web Publishing menu on the left, then the PHP tab on the top menu and check the Enable PHP Publishing box. If you’re using a hosting provider, it’s likely that this is switched on already.

Set up your user in the FileMaker file

Recall that we set up a user and password in the fmperformscript.php file? We need to make sure we have that user set up correctly. In the FileMaker file, open the Security dialog and ensure you have a user with the same username as entered in the PHP file, set the password as per the PHP file (you’re changing this password from the demo one here, right?), and ensure the privilege set the user is assigned has the Access via PHP Web Publishing option enabled. We highly recommend that the privilege set you set up for this user be as locked down as possible. Absolutely do not use the Full Access privilege set. Restrict the privilege set to the layout, script and tables/fields that it needs access to in order to perform its function and nothing else.

Set up the script to set the coordinates

When the script, named SetCoordinates, is called via fmperformscript.php, there are four variables that are passed in the parameter, separated by | characters. These values are:

1. Latitude
2. Longitude
3. Record ID
4. Secret Key

You can parse these out however you wish. The below is one idea and deliberately not optimized to keep it simpler. But the general idea is parse out these parameters, exit if the secret key is not correct, otherwise find the record we need to adjust and set the latitude and longitude fields.

Set Variable [ $SP; Value:Get ( ScriptParameter ) ]
# Test if secret key passed is correct. Exit if not.
If [ GetValue ( Substitute ( $SP ; "|" ; ¶ ) ; 4 ) ≠ "123456" ]
Exit Script [ ]
End If
# Go to Addresses layout and perform find for record in question - ID passed in script parameter
Go to Layout [ “ADD.Addresses” (ADD_Addresses) ]
Enter Find Mode [ ]
Set Field [ ADD_Addresses::ID ; GetValue ( Substitute ( $SP ; "|" ; ¶ ) ; 3 ) ]
Perform Find [ ]
# Set coordinate fields with values passed in script parameter
Set Field [ ADD_Addresses::Latitude ; GetValue ( Substitute ( $SP ; "|" ; ¶ ) ; 1 ) ]
Set Field [ ADD_Addresses::Longitude ; GetValue( Substitute ( $SP ; "|" ; ¶ ) ; 2 ) ]
Commit Records/Requests [ Skip data entry validation; No dialog ]

Decide how you wish to handle the parameters, and ensure this script is set up in your database, named correctly, and check that the user you set up above has the rights to execute this script.

Conclusion

We started out this post saying this is not a simple task. As the above demonstrates, it’s not, but it is a foot in the door of Custom Web Publishing and what can be done with the PHP API.

You can download the PHP files for this solution here.