The most recent release of FileMaker Pro, version 19, the Claris’ first Open Platform Release. Todd has already talked about this. In his post, he describes the ways in which FileMaker the platform is opened to other developers coming in to add functionality. We at Geist Interactive worked closely with Claris to build FileMaker add-ons for the platform–those add-ons we’ve all heard about in previews or heard about in podcasts (here and here). Here is everything we learned about how to create add-ons using the current FileMaker 19 release. We’ve wrestled with the process, found many issues, and have worked with Claris to fix those issues. So here’s what we’ve learned (or at least most of it; we’ll follow up this post with additional ones describing more details).
What is an Add-On?
An add-on is a package of FileMaker tables (including data–see the Data section to understand this), table occurrences, layouts, scripts, custom functions, themes, custom menus, and layout objects that work together to add additional functionality to a custom app. An add-on can be complex, like a Kanban board (using a web viewer, three layouts, and multiple scripts and multiple custom functions), or an add-on can be a simple collection of global fields and scripts that process credit card information. We’ve already seen even the simplest add-on of a button bar that displays a checked or unchecked icon. Pretty cool!
The following document explains how to create an add-on. The process, at its basic level, involves grouping a set of objects together on a defined layout and then running a new FileMaker 19 script step to package up the relevant items in the file as an add-on..
The end result of this simple process is an add-on that is added to the following application folder.
- Library/Application Support/FileMaker/Extensions /AddonModules folder (on macOS).
- AppData\Local\FileMaker\Extensions\AddonModules (on Windows).
Once added to this folder, the add-on will be available in the developer’s copy of FileMaker Pro and then installed into a custom app. From there the add-on will be available to everyone who uses the application.
- The file in which you’re creating the add-on must have a unique File ID. This is generated when creating a new file or by clicking “Reset All. . . “ button in the Manage > Security > Advanced Settings > File Access Dialog. We recommend creating a new FileMaker file each time you want to create a new add-on.
- The name of the file will be the name of the add-on. You can change the name once the add-on has been created, but it’s easier to have the file be the correct add-on name.
- This process creates an add-on that consists of tables, fields, table occurrences, scripts, custom functions, layouts, custom menus, and objects. This process ignores security related features (accounts, privilege sets, etc). This process will also include any sample data in the file.
- Once installed by the developer, the add-on is available to everyone using the app.
- Each time you generate an add-on from a FileMaker file, you should first go into the AddonModules Folder and delete the previous version. While this add-on process will probably be okay writing over the existing file, we haven’t tested this to confirm. So deleting it is the safest option.
- If you do want to change the name of the add-on, you have to do so in the AddonModules folder. Below describes how you can change the name and add other details about the add-on.
- There’s a difference between ‘installing’ and add-on and applying the add-on to your layout. The former action, you only do one time. You install the add-on, which includes adding all the schema, scripts, layouts, etc. to the target FileMaker file. Once installed you can apply the add-on many times to layouts in your file.
Making an Add-On
Here’s how you create an add-on to be installed and used in a FileMaker file. This process will create the entire package of your add-on; anything in the file you’re using to create will be included except for the items described above and the ‘special layout’.
A Special Layout (or many special layouts)
The first thing you do is create a special layout (or many special layouts if you wish to support localizations of other languages). This layout is the place you’ll create the layout object payload–the group of objects that will be dragged onto a layout in your file. This layout will NOT be packaged as part of the add-on. It is only a place to create the payload.
You can have items on this layout that are used for your development but will not be part of the add-on. See the “Object Groups” section below for further details.
In your new FileMaker file, create a layout using a table occurrence that makes sense for your add-on. This underlying table will be packaged as part of the add-on, and your add-on, if using fields from that layout, will be bound to the table occurrence. If you do not plan on using this table occurrence for anything (storage of data or relationships) you can delete the table occurrence, leaving this layout with no context.
It can be a utility table that has no real connection to the add-on. Or this layout can be integral to your add-on, as it contains fields used in the add-on.
Give the layout the name of
__FMAddonTemplateDirectives_ and add a ISO 639.1 language code to the end. “en”, for example. So the layout is named
!! Make sure there are two underscores at the beginning.
The file in which you’re creating the add-ons can have multiple ‘special’ layouts, each with a different language code suffix in the name. The add-on process will create add-ons for each localization you’ve defined in the layout names. See the Localization section below.
Most add-ons will contain layout objects. The collective set is called, for this document “Layout Object Payload” (this name is only for this blog post; you do not need to name the group).
On this layout, create your objects. These can be fields of the underlying table, or buttons with scripts attached, or anything else that can be on the layout.
Place the objects where you’d like, consider their anchoring as well. And style them as such.
Theme and Styles Considerations
The style of the objects should be considered. Whatever style each of the objects contains will be part of the add-on package. Any discrepancies between these objects’ styles and the file in which the add-on will be placed will be noted as local styling on the object.
Group the Objects
Once you have all the objects on the layout and in the positions you want them, group them together. Use only one group on the layout. The add-on process will include any objects in the group on the layout. This means you can have other buttons on the layout that are part of your build process (see below). Anything outside the one group will NOT be part of the add-on.
It is possible to for your objects to have names. Further, you can make each add-on object have unique names in the event you want two instances of the same add-on included on a layout.
For example, if you create a charting widget with a web viewer, you can use this widget multiple times on the same layout, and, with the unique object name, target a specific instance.
See the “Add-On Names” section below to understand how to make unique names for your add-ons.
Layouts, Scripts and Custom Functions
An add-on can contain additional layouts that work with the add-on to provide the full functionality. For example, an add-on can have a layout as a card window to display the details of the clicked-on card or row of the Kanban board.
Any layouts, scripts and script folders, and custom functions you create in this file will be part of the add-on package. They will install in their proper place. These add-on parts are used to complete the add-on’s functionality. For example, a script attached to a button that is part of the add-on can open a card window (one of the layouts you created).
Some notes about the layouts:
- If you have a layout that contains a custom menu and that menu is set as the default for the layout, that custom menu will get packaged up, but the custom menu will NOT be the default.
- Remember: you can have any number of layouts as part of the package. The only layout that will not be bundled are the
- Upon this special layout you can place additional buttons and objects as you wish. If they are not part of the main group they will NOT be included in the package. Remember, however, any buttons with scripts attached that are meant for ‘developer only’ will still be included in the package; there’s no way at present to exclude scripts from the package.
An add-on is a package everything in your ‘add-on-creation’ file, and that includes tables. The add-on can also include sample data inside any additional tables you’ve included. This is useful, along with the layouts you’ve included in the add-on package, to show how the add-on works once installed. We recommend adding Sample data in a table that is clearly marked “SAMPLE”.
Packaging Up the Add-On
Once you have the proper tables, scripts, custom functions, names and groups set up, run a script that performs the step “Save a Copy as Add-on Package”. See the attached file as an example. We’re using a separate file to run this script step so this script does NOT become part of the add-on (It will if the script is in the add-on file).
The options of this step include the
Window Name and
- pass in the window name of this window.
- This option will generate a new UUID for all the objects of the add-on. This is vital if you use the same file to create different add-ons, such as a template file. We’ll explain later in another post.
- You do not need to replace UUIDs if you use a new FileMaker file for every add-on.
Running this step will create the add-on. It will bring over all valid parts of this file into the package and place it into a folder in the AddonModules folder, which will open up. Any localized versions you’ve created (any layouts with the proper name and a localization code) will be part of the package.
Using the Add-On
Once installed into this folder location, quit FileMaker and restart the app. When you go to install an add-on (layout mode > left panel > “Add-on” tab–the add-on should be available for your use. As a developer you can then install the add-on one time or MANY times in the app (see below for a discussion on ‘multiple instances’ of the add-on). This will install all the parts of the add-on: the scripts, the tables and table occurrences (if any), the layouts (other than the ‘special’ layout), themes, custom functions, etc. The add-on will then be ready for all users of the app.
Naming Add-On Instances
Sometimes you want to have more than one instance of the same add-on on a layout. That’s possible, for sure. You can set up your add-on during your creation process to get a unique identifier.
To ensure objects have unique names, name the object. Include the string
[<^FMXML_AddonInstanceUUID>] wherever you like in the name. For example, for a kanban widget, you might name it:
Kanban+_[<^FMXML_AddonInstanceUUID>]. Use this string in any other parts of your add-on, including field calculations, script parameters on buttons, etc.
The add-on process will take this string:
[<^FMXML_AddonInstanceUUID>] and replace it with a UUID during the drag-drop action. If you install “Twillio Integration” add-on onto your app three times, each add-on instance will get a different UUID.
As an example: in our Simple Chart FileMaker add-on, the web viewer calculation contains this string as well as the name of the web viewer object. We also use this in parameters on buttons included in the add-on. During the install process, this string gets replaced with a UUID. So even though there’s one set of scripts to run the add-on, each script knows the add-on it should interact with.
The add-on drag/drop process (from the add-on tab to the layout) will update ALL the instances of this string in all parts of the add-on. You can use this feature to make sure that a button as part of the add-on will work with the add-on it is meant to work with.
In the chart widget example above, each add-on has a button with this string as the parameter. Each of the three instances will have a different UUID in the button’s script parameter. So each button will work with only its add-on.
Adding Info to the FileMaker Add-on Module
The add-on package can include additional information about the add-on. For each language you choose to support, you can add the following information:
|Title||This is the name of the add-on. Here’s where you can update the name and this name will show up in the install dialog of the Addon Tab.|
|Description||You can include a description here to give users information about what to expect in its functionality.|
|Category||A defined category. This is how add-ons will be grouped in the install dialog.|
|Features||Include an array of features, one feature per array-element.|
|Optimized||Include information about this add-on’s optimization with different devices. (I would also include whether the add-on works on MacOS, Windows, and WebDirect if you’re using a web-viewer widget add-on.|
Additionally, you can include an icon for your addon. Replace the icon.png files in the add-on module’s folder
Onward, and To Be Continued
Give FileMaker add-ons a try. Try to make one. Start simple. The road will be bumpy, but we’ve got yah. Reach out at firstname.lastname@example.org for quick answers to your questions, or post in the Claris Community.
There’s a lot more to discuss about the FileMaker add-ons. We’ll make an effort to get more blog posts out giving out all the other details we’ve come to learn in this process. We need to explain about localization, about FileMaker language versions and add-on localizations, etc. We also need to explain how to create an add-on with related table occurrences. That’s a whole other yarn ball to unwind. So stay tuned to this blog for more on FileMaker 19 add-ons.