What is an API?
If you really want to dig into the answer to this question, head over to Wikipedia and knock yourself out! For our purposes, the following definition will suffice:
An application programming interface (API) is a particular set of rules ('code') and specifications that software programs can follow to communicate with each other. It serves as an interface between different software programs and facilitates their interaction, similar to the way the user interface facilitates interaction between humans and computers.
So, from within FileMaker we're going to communicate with Google Maps through the API. Now that's taken care of...
What is Javascript?
Again according to the mighty Wikipedia:
JavaScript is a high level, dynamic, untyped, and interpreted programming language. Alongside HTML and CSS, it is one of the three essential technologies of World Wide Web content production; the majority of websites employ it and it is supported by all modern web browsers without plug-ins.
Awesome. Since it's supported by all browsers, our web viewer object in FileMaker can be used with Javascript. It's a powerful programming language but we're not here to delve into this side of things. There are plenty of resources available if you wish to get more familiar with Javascript.
Integration Concepts
The basic concepts of what we will be doing are:
- Place a web viewer on a layout.
- Get this web viewer to display a Google Map using the API Javascript code. There are a variety of ways to do this, including adding the code directly into the web viewer or placing the code in a text object and referencing that. For our demo we have the code in a text field and we reference that in the web viewer so it's easy to look at and adjust as needed.
- The Javascript code waits for a click, and when one is detected, it clears any previous map markers that may be present and drops a new marker in the clicked location.
- Immediately after this, we call a FileMaker script in our database using the FMP URL protocol, passing parameters which set variables with the latitude and longitude. Then in our script, we use the values in these variables to set the latitude and longitude fields.
- As a bonus feature, we also have a starting address field, which is used when the map is first loaded to center the map on this location. The address is geocoded (converted to latitude and longitude) and then these coordinates become the center of the map.
Integration
If you wish to integrate capturing coordinates into your FileMaker solution, what do you need to be aware of?
Google Maps Javascript API Resources - you can check out the resources for the API here. There are code samples and suggested uses that you may not even be aware exist. Lots of cool stuff.
API Key - this demo does not have an API key, but it is suggested and recommended that you get one of these from Google. It is free to get one 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.
Fields - the FileMaker Latitude and Longitude fields are referenced in the script that sets the coordinates into the fields. The HTML andStart Address fields are referenced in the web viewer.
Script - the SetCoordinates script is referenced in the Javascript code located in the text field on the HTML tab.
Filename - the name of the FileMaker file is also referenced in the Javascript code.
There are plenty of comments in the code on the HTML tab to assist porting this over to your own solution.
Compatibility
This demo should be compatible with FileMaker Pro 13 or 14 and FileMaker Go 13 or 14. It is recommended that you have the latest updates installed for the applications.
A note of caution regarding FileMaker Go: A known bug exists where FileMaker Go may not execute the script when the call from the web viewer is made. This is related to the '$' and '~' characters that may be in the FMP URL in the Javascript code. The workaround as noted in the code is to replace '$' with '%24' and replace '~' with '%7e' (don't include the quotes).
The FMP URL protocol is not supported in WebDirect, and therefore this demo will not work in WebDirect.
Update 2015-09-09: As noted in HomeBase Software's post on the same subject, this demo will not work when deployed as a runtime solution as the FMP URL protocol is configured when FileMaker Pro is installed. There might be a way to dig into the OS and set up the protocol manually, but we have not attempted this and it falls outside of the scope of this article.
Finally, the demo file...
You can download the demo file here.
While this demo is not compatible with WebDirect, we have implemented grabbing coordinates into FileMaker from a web viewer located on a WebDirect layout. It's a lot more involved but we'll look at doing a blog post on this technique in the near future.
Have fun with the demo and implementing the technique in your own solution. If you need help, don't hesitate to get in touch.
Finally, huge thanks and gratitude go out to Julio Plasencia for his assistance and introducing us to the FileMaker/Javascript world when we first started down this road. As with many in the FileMaker community, his willingness to help and share has been unreal and greatly appreciated, making it a community well worth being a part of.
Update 2015-09-14
Check out our second post on this subject, which modifies the demo file to have a marker drop when the record loads if previously selected coordinates exist.
