It’s been a few weeks since the Claris FileMaker add-ons were put into the product. A lot has happened since then. People have explored them using the sample data and even their own. The community is now filled with questions about these new packages of functionality. People are discovering what can be done with them. They’re also discovering little things of which to be aware. So this post is a compilation of what folks have learned about the FileMaker add-ons. I present them in no order. Just find the heading that’s of interest to you and read details about that particular nuance.

Scripts

There are a few more scripts that I’ve not mentioned previously. Here’s a description a few more of them.

The Schema Script

There’s a script inside the “Event Handlers” folder that checks your file’s schema for layouts and fields on one specific layout (the one you choose in the configurator). As with other scripts, you don’t need to do much with this. Additionally you really don’t have to even modify it. I wouldn’t give this script a second thought. But if you do need to know, here are some short details:

  • Do not change the name of the script.
  • The script is called by the web viewer’s JavaScript code as you open the configurator. For each dropdown on that screen, this script provides the choices: first the layouts in your file, and then the fields on the individual layout you choose.
  • It gathers a lot of info about your file: layouts, scripts, value lists.
  • It requires a ‘best-practice’ file name. See that section below.
  • The script reads from the config for the instance of the add-on with which you’re working, and it uses values in the config as the starting point for the configurator. If you’ve already chosen a field for the primary key, for example, that field name is extracted from the config (in the ConfigStore field) and displayed in the configurator.
  • Once you’ve selected a layout, this script runs again to pull the fields on that layout. So each time you change the layout in the dropdown, the field list is regenerated (per type of field).
  • It uses FileMaker 19’s Execute FileMaker Data API script step, specifically using the metadata query.
  • All the fields on the layout are separated into field type arrays.

That’s really all you need to know about this. There’s no instance I can conjure that requires you to manipulate this script in some way.

Get WebViewer Object Name Script

This utility script simply gets the name of the web viewer object in which a script is working. It receives the AddonUUID from the parent script and adds the prefix to it, sending it back to the parent script.

There’s nothing to concern yourself here. It just does its thing and moves on.

Save Config Script

As with the other two scripts, this one is pretty untouchable. Its sole purpose is to receive the configuration from the JS when you press “Save” on that screen and store it in the ConfigStore field.

I mean if you really wanted to, you could override the Config choices made in the configurator. Since JSON is coming from the configurator, you could update a key before it gets stored in the field. Heck you might even be able to ignore the configurator all together and instead use this script to update what’s stored in the field.

Little Quirks

Pause / Resume Script Step

The pause/resume scripts inside the add-ons scripts can cause a problem for certain users. Claris has identified the problem here, and suggests the work-around. Hopefully this will be fixed in a future update of the product and the add-ons for newly-installed add-ons. But you can fix it now.

The problem is that the Pause /Resume script step was set with 0.5 as the pause interval. That doesn’t work for some users, as they’re running FileMaker Pro on a machine with a system language that doesn’t match the region. You can easily fix this by changing the 0.5 to 1/2. And that is what you’ll have to do if you’re currently using an add-on.

The scripts that contain this step are few. Using FMPerception, I am able to find them:

They are, in case you can’t see the image, ShowConfig (line 25) and SaveConfig (lines 54 and 69).

Layout Zooming

There was one question in the community about how the web viewer reacts to layout zooming. The poster typically zoomed layouts to 150%. The web viewer on that layout followed the zoom, which sort of unsharpened the add-on.

Unfortunately that’s how it is. There’s no way to counteract the layout zoom with a web viewer zoom. I’m not sure that’s even possible. It’s likely the layout zoom overrides the web viewer zoom.

So consider that as you design layouts.

Customization

Many folks have asked about customizing a FileMaker add-on further than what is offered in the configurator. Since the add-on is built to be a complete package, the JavaScript code that runs it is packaged up into the HTML field inside the add-on’s table. It’s pretty impossible to get in there and modify something like the color or the width of a particular item.

When we built the add-ons, we worked with Claris to decide what to expose in the configurator. The goal was not to overwhelm a developer with every possible choice; building a configurator with nearly as many choices as the current inspector is tough, and just gives too many choices. So we made decisions on what would be customizable. Generally basic color/theme choices are available, as well as a lot of options in the specific add-on itself.

If any developer wishes more customization, she’s free to build an add-on that suits her needs. We can help with that, for sure, building an add-on that is defined exactly how it works for an app.

We’d love to see some sort of actual add-on inspector incorporated into the current layout mode that gives more choices. I don’t know how that would work, but it is an interesting dream.

Naming Things

Layout Names

After the add-ons were released, I started seeing a few bugs reported about a particular layout not showing up in the configurator’s inspector. After some poking around, I found that layout names with quotation marks in them would cause the the entire layout drop-down to fail. The Schema script (described above) collects the layouts in the file as an array. We know that each string element in an array is quoted, so if a layout name has a quotation mark in it, the array cannot be generated properly. Single quotes might work (not tested), but generally, I’d say, stick to naming layouts without quotation marks in the name.

File Names

Like layout names, File Names are important. Developers have found that the configurator fails to render when the file contains a dot in it: File.Name.fmp12, for example. I think it’s agreed that dots are bad for names; they’re used to designate a file path, not a file name.

Script Names

Be careful with the script names as well. Don’t change the names of scripts where that warning is written at the top. These scripts are called from the JavaScript. The JS has each script name hardcoded into it, and the JS Function looks for the script by name (not by script ID) when it goes to call the script.

Licensing

All of the add-on were built using free MIT-licensed JavaScript libraries. You can use them for commercial apps, for many apps, and for many customers.

Onward

There’s probably more that we’ll discover about add-ons in the coming months, and in the coming months, the entire structure of the add-ons might change. We’ll keep you updated on the latest bugs, discoveries, and changes to the FileMaker add-ons.

In Part 2 of All that we Know on Add-ons (part 1 is here), we talked about how to create add-ons that include a simple child relationship. The sole purpose of that add-on was to add a child table and have it automatically relate to the context of the layout in which we drop the UI elements. This simple relationship might prove useful in many cases: add a notes or addresses table easily. But for complex relationships, we need to create filemaker add-ons with join relationships.

To keep our heads straight, pictures and a real-world scenario (or at least a common join-table use case) will help us understand this. We’ll use a Schedule table that shows all the classes in which each student is enrolled.

Considerations

Here’s a small list of considerations about FileMaker add-ons with join relationships

  1. Just like in our discussion about add-ons with relationships (part 2), we’re creating this add-on from the related table context. That means, in this case, we’ll be creating it from the join table perspective. The base table of the add-on layout is “Schedule”.
  2. Each table has their proper keys. The Schedule (or join table) contains a generic foreign key field (as described in part 2), and it contains the foreign key for the far right table (the Classes table). And of course, the tables contain primary key fields. The default fields feature of FileMaker 19 will create the primary key fields for you.
  3. A package is one or more tables (among other FileMaker things). As you install the add-on, the tables inside the package get added to the schema once. Even if you place the add-on many times in your file, each instance will use the exact same table.
  4. An add-on must also include the far right table. In this case, the add-on contains the Classes table. There’s no need to create the relationship between Schedule and Classes. It’ll be automatically created on install.
  5. Adding an add-on to a layout automatically creates the relationships between that layout’s table occurrence and the add-on’s tables, provided you’ve set up the package correctly.
  6. Remember: there’s a difference between ‘installing’ the add-on and dragging it to your layout. The difference is very apparent in these kinds of add-ons.

Our first step is to set up the portal showing the schedule records. Again, since we’re on the context of the schedule, use the “Show Records from Current Table” option of the portal set up.

As we can do with all other portals, we can put any fields from the context or relationship inside the portal. Notice in the image, I have “Classes::ClassName” field in the portal. That’s fine. Yes, it’s an unrelated field since we didn’t create the relationship, but you can still place the field on the layout.

Group this object.

Next, we need to tell the add-on package which fields is the primary key and which fields are the foreign key fields. Place those fields on the same layout and name them as follows:

Schedule::ForeignKey: R1|LeftTable This is the field that will be part of the relationship to the context upon which the add-on is dropped.

Schedule::ForeignKey_Classes: R1|JoinTable: The foreign key meant for the relationship to the Right table (in this case, the Classes table).

Classes::PrimaryKey: R1|RightTable. This is the primary key of the Classes table (yes, it’s okay if you put the unrelated field on the table).

NOTE: The name is important in its structure. Each field name needs three pieces:

  • A relationship name: this can be anything as long as it’s the same for all three fields.
  • A “|” (pipe character)
  • and one of three names: “LeftTable”, “RightTable”, “JoinTable”

Now group just the fields together and name the group

__FMAddonDynamicRelation_

and complete the name with the relationship name you used in the field names. My example would be:

__FMAddonDynamicRelation_R1

At the end of the set-up, this is what you have on the add-on creation layout.

At this point, I have a perfectly-set up layout. I can now create an add-on using the same process I’ve described before. Simple. Those two grouped items will be part of the package. Finally, on the install . . . let’s see what happens.

Installing

As we do with other add-ons, we can install this join-relationship add-on. Additionally, the install process adds to the file the package tables, fields, scripts, and layouts. In this case, the Classes and Schedule tables are installed.

Further, when you drag the add-on onto a layout, you only get the grouped objects. The group of fields is NOT part of what you drag on. Instead they’re indicators to FileMaker of the relationships to create.

Here’s what the Manage Database looks like when you install the add-on.

And here’s what it looks like when I drag the add-on onto a Student layout.

After all this is done, we have a join-table relationship installed into the app. The process takes a few moments to set up correctly, but once done, the process adds a lot of good functionality to these add-ons.

We’re continuing our discussion of the new FileMaker 19 add-ons. Claris has released a great video on these add-ons, but, in this series of posts, we’re taking a deep dive into how the add-ons work. In this post we look at how to use multiple instances of the FileMaker add-ons.

The Point of the Add-ons

One of the biggest reasons to use an add-on is that it can be used many times throughout your file. Just like a portal or a button bar, the calendar add-on or the photo gallery add-on is flexible enough to use all over.

As a FileMaker developer you don’t have to know how this works; just know that it works. Your use of an add-on multiple times in the file will not disrupt any of the other add-ons. Here’s a silly example.

Two Timers To Track Times

These two timers are separate instances of the same Timer add-on.

They work with two sets of the timer’s required fields. They have their own configurations (one has a blue button/gray background, and the other has a red button/white background).

Each add-on runs independently of each other; indeed, you can kind of see it here (in the button text), the first timer is running and the second timer has stopped.

Each Timer is Unique

The magic behind this idea is that each timer is given a unique Addon UUID when you drag/drop the add-on to a layout. You can see this unique ID in a few places:

  1. The add-on’s FileMaker buttons (such as the configurator button or the back/forward arrows) script parameter
  2. The name of the web viewer object in the Inspector
  3. The web viewer’s calculation

Of course all of these match, and have a specific purpose.

Multiple Instances of FileMaker Add-ons: The Deets

Let’s make sure we have something clear in our heads:

  • When we install the add-on, all the scripting, layouts, etc comes in as a complete package. The scripts come in once.
  • When we drag/drop the add-on onto a layout, we’re creating a new and unique instance of it. The UUID gets generated and attached to the places you see above.
  • If you were to copy an add-on, you’re copying the UUID as well, so there will be two add-on groups with the same UUID. Can’t have that.

Now that we have that clear (if not, go back and read it again), all add-ons of the same type use the same scripts, so the UUID is passed to scripts to let the script know which one to work with in some manner. The “Show Config” script gets the UUID attached to the button and grabs the config from the ConfigStore field using that UUID. Because the web viewer is named with the UUID, the script knows which web viewer on a layout to activate and manipulate.

This idea of the UUID is incredibly important. You don’t want to change it, unless you want to go to the trouble of updating it all over.

The Only Other Thing

I believe the only other thing you really need to know about multiple instances and the UUID is the script containing the words “WebViewer Object Name”. This script generates the web viewer’s name at runtime, and is used in almost every add-on script. Just FYI.

Oh yeah: if you really want to know how the UUID is generated, I explain that in the post on creating add-ons. Check that out.

Go Forth and Multiply

So use add-ons all over the place. Use a timer ten times in your custom app. Build a dashboard using charting add-ons. Create a layout with two Kanban boards that show different tasks. You got it! It’s easy and the add-ons are built with this in mind.

We’re continuing our discussion of the new FileMaker 19 add-ons. Claris has released a great video on these add-ons, but, in this series of posts, we’re taking a deep dive into how the add-ons work. In this post we look at the FileMaker add-on configurator

The add-ons are meant to be working with little effort. Even at the moment of install they work using sample data and some default settings. At install, you see exactly how they work.

Make it Your Own

There’s no one here, however, that wants the sample data settings to be part of the add-on in their app. Some of the settings too may not fit every customer solution. Both of these issues are easily solved with the add-on Configurator.

So let’s take a look at how to configure the add-ons. We’ll look at the configurator generally, and then in a follow-up post, we’ll address specific add-on configuration settings.

Configuration, Generally Speaking

The configurator dialog is a window installed as part of the add-on package. The layout contains only a blank web viewer, and this layout is used as a card window. And finally, every instance of an add-on–whether used multiple times on a layout or multiple times in a file–will use this one configuration layout.

As part of the layout object that you drag over, a button with a gear icon is included. This activates the “Show Configurator” script. This button is set to be invisible on iPhone or if a user is logged in with a non-full access account. The script uses the UUID of the add-on (generated on drag/drop), and opens the configurator.

Once the configurator is open, you’re presented with some mini pages that contain drop downs or text fields or checkboxes to enter your configuration for this particular add-on instance (remember, you can have multiple instances of the same add-on throughout your file).

In many add-ons there are the same pages: Required, Settings (or options), and Filter. The required fields are required, and the add-on will not save until those fields are filled in.

Required & Optional

I’ve discussed already the required fields for each add-on, but I need to point out one more thing: Most add-ons require a layout in the first drop-down.

This choice is vital: you have to select a layout on which contains all the fields you wish to use in the add-on. All the required fields as well as the optional fields you want to use in the display. For example, the Kanban add-on requires some fields and gives you optional fields. Each of these fields need to be on the layout you choose.

The layout you choose should be one you’d like to use to show the record when it is clicked on in the add-on. Here’s a couple of tips when picking a layout:

  1. Be sure and put all the fields on the layout: either visible and part of the design or off to the right of the visible area.
  2. You can use fields from a related context, but you might run into some slow-down of gathering data.
  3. Before you actually set up the add-on, create all the required and any optional fields in the data table.

Settings

Many add-ons give the developer some ways to customize the add-on. It could be as simple as button color. Whatever the settings, each add-on has default settings that you can change.

Filter

We’ve discussed before the filter mechanism. It is part of the configurator, so you can read up on that. There’s not a whole lot more to talk about there.

Scripting

The button that opens the configurator runs a script partially named “Show Configurator”. This button contains the AddonUUID as a parameter. Here’s an example:

JSONSetElement ( ""; 

  ["AddonUUID" ; "701F0F8B-BED4-48D0-948D-B7E5F2D1171B" ; JSONString]

)

As we’ve talked before about add-ons generally, this UUID is generated when you drag the add-on to your layout. Further, this UUID in the parameter is the same as the UUID for the web viewer object. The UUID attached to the button allows for you to use multiple instances of the add-on all through your file or on the same layout. Each button will have the UUID of its web viewer package, thus be tuned only for that instance.

The Config

It’s important to know where this FileMaker add-on configurator gets the options. For each instance of an add-on, the configuration–that is, the field choices and settings–is stored as a JSON object inside the add-on’s table in the ConfigStore field with the add-on’s UUID as the key.

{
   "701F0F8B-BED4-48D0-948D-B7E5F2D1171B":{
      "AdditionalInfoField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "AssignedTo":{
         "required":false,
         "type":"select",
         "value":""
      },
      "CardDraggable":{
         "required":false,
         "type":"checkbox",
         "value":true
      },
      "CardStyle":{
         "required":false,
         "type":"select",
         "value":"Tasks::BackgroundColor"
      },
      "DataSourceLayout":{
         "reScanOnChange":true,
         "required":true,
         "type":"select",
         "value":"Tasks"
      },
      "DescriptionField":{
         "required":false,
         "type":"select",
         "value":"Tasks::Description"
      },
      "FilterField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "LabelField":{
         "required":false,
         "type":"select",
         "value":"Tasks::Label"
      },
      "LaneSortOrder":{
         "value":[
            "To Do",
            "In Progress",
            "Done"
         ]
      },
      "PrimaryKeyField":{
         "required":true,
         "type":"select",
         "value":"Tasks::PrimaryKey"
      },
      "QueryField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "SortField":{
         "required":true,
         "type":"select",
         "value":"Tasks::SortOrder"
      },
      "StatusField":{
         "required":true,
         "type":"select",
         "value":"Tasks::Status"
      },
      "StatusSort":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleStatus"
      },
      "Style":{
         "required":false,
         "type":"select",
         "value":"Red"
      },
      "TitleField":{
         "required":true,
         "type":"select",
         "value":"Tasks::Title"
      }
   },
   "DEV_UUID":{
      "AdditionalInfoField":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::AssignedTo"
      },
      "AssignedTo":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::AssignedTo"
      },
      "CardDraggable":{
         "required":false,
         "type":"checkbox",
         "value":true
      },
      "CardStyle":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::Style"
      },
      "DataSourceLayout":{
         "reScanOnChange":true,
         "required":true,
         "type":"select",
         "value":"KanbanSampleData"
      },
      "DescriptionField":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::Description"
      },
      "FilterField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "LabelField":{
         "required":false,
         "type":"select",
         "value":"KanbanSampleData::Start Date"
      },
      "LaneSortOrder":{
         "value":[
            "To Do",
            "In Progress",
            "Done"
         ]
      },
      "PrimaryKeyField":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleData::PrimaryKey"
      },
      "QueryField":{
         "required":false,
         "type":"select",
         "value":""
      },
      "SortField":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleData::Sort"
      },
      "StatusField":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleData::Status"
      },
      "StatusSort":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleStatus"
      },
      "Style":{
         "required":false,
         "type":"select",
         "value":"Blue"
      },
      "TitleField":{
         "required":true,
         "type":"select",
         "value":"KanbanSampleData::Name"
      }
   }
}

Notice that in the above Config, I have two properties, one for the add-on with the UUID beginning with “701F0F8B” and is tuned to the settings I want: the Tasks table fields, the Red style, and so forth. The other with the key of “DEV_UUID”, which contains the settings for the default (on-install) set up. If I end up with ten instances of this add-on throughout my file, there will be ten objects here, each identified with the add-on’s UUID.

If you really, really, really, ever, ever, ever want to wipe this field out there’s a Developer-only script called “Clear Config” that will clear this field. If you do that, all of your configs for all your add-ons will be wiped out. So maybe don’t do this??

Using the Configurator

And finally, as each instance of the add-on is used throughout your file, the add-on setup, the custom functions, and the “Show Config” script work together to get the config out of that field and pass it to the JavaScript code, where it is used all over, telling the JS such things as what colors to use, what layout to pop up to display the data, what fields to use. There’s a lot in this config, and it’s best to leave it alone. Other scripts use the config as well, so

If you want: If you’re really interested you can, at any time, hijack this config and overwrite it with something temporarily. It’s just JSON, and you can target and change anything in here. What you change will update the web viewer.

The FileMaker Add-on Configurator

So that’s the skinny on the FileMaker add-on configurator. It’s an important part of the set up, but really only needs to be touched once during development. After that you’re free to move the button off the layout to the side and use it only when necessary. Heck you don’t even need the button. You can use the same parameter in the button set up in a parent script to call the Show Config script. As long as you pass in the Addon UUID as a JSON object, you can call the configurator via a Developer-only script.

We’re continuing our discussion of the new FileMaker 19 add-ons. Claris has released a great video on these add-ons, but, in this series of posts, we’re taking a deep dive into how the add-ons work. In this post we look at the required fields for the FileMaker Add-ons.

Add-ons Required Fields

Each add-on has one or more required fields for it to work. The dashboard-type add-ons (Kanban, Calendar, Activity Timeline, Photo Gallery) all require the Primary key field of the source data records. That’s a given. The Heatmap add-on doesn’t require a primary key field since it will return all the events of a clicked-on date.

But each add-on has other requirements, and you can see the FileMaker add-on required fields in the configurator. But the configurator is in one part of the add-on, and adding fields is elsewhere, so what follows is a list of all the required fields for each in-product add-on. You can use this list to create the fields in your data tables (or just copy from the SampleData table that comes with each add-on).

An Example Configurator

Remember, these fields do need to be on the target layout, whether on or off screen (off the layout to the right), in order for the add-on configurator to get the data you need.

For fun, I’ll list the non-required fields as well, just so you can make them all at once. These fields provide additional functionality if you choose to add them to your data table.

Calendar

Required Fields

  • Primary Key
  • Title: that which you’ll see on the calendar.
  • Start Date
  • End Date
  • Start Time
  • End Time

Non-Required fields

  • Tooltip
  • AllDay – a number field (1 or 0(empty)) representing the full-day indication
  • Editable: a number field (1 or 0/empty) to indicate if the event can be clicked on and edited.
  • EventStyle: a text field describing the color style the event should be. The FCCalendarStyles value list provides the pre-determined choices.

Kanban

Required Fields

  • Primary Key
  • Name or Title: that which you’ll see on the board.
  • Sort: a number field determining the sort of the cards in each lane. Note: this field get constantly updated as users drag/drop to rearrange the cars on the board. But you can do an initial set of the sort.

Non-Required fields

  • Description: a field holding a description of the task. This is one paragraph with no returns in the text.
  • Label: the label will appear on the top-right of each card. You may want to put a priority level or a date field here.
  • Additional Info: the value in this field will be included in the card if there’s data in the field. It just provides more information about the task.
  • Assigned to: pick a field that holds the assignee name.
  • Card Style: a text field describing the color style the event should be. The KanbanSampleStyles value list provides the pre-determined choices.

Activity Timeline

Required Fields

  • Primary Key
  • Start Date: A timestamp or date field.

Non-Required fields

  • Title
  • Description: a field holding a description of the task. This is one paragraph with no returns in the text.
  • Assigned: pick a field that holds the assignee name.
  • Background: a text field describing the color style the event should be. The ActivityTimeline Styles value list provides the pre-determined choices.

Required Fields

  • Primary Key
  • Photo: This field points to either a container field or a base64-encoded field (see the sample data table). If the file with the add-on is hosted, you can use the container field. Local files require the base64-encoded field.
  • Scale Width: A number field given the relative width of the image. You can calculate this from the original width of the photo. See the SampleData table for examples.
  • Scale Height: A number field given the relative height of the image. You can calculate this from the original height of the photo. See the SampleData table for examples.

Calendar Heatmap

Required Fields

  • Start Date: A timestamp or date field.

Barcode Creator

Required Fields

  • Barcode Source: The data you want to turn into a barcode.
  • Image: Where to place the barcode image.


Timer

Required Fields

  • Time Logged: A field where the time from the timer will be placed when a user stops the timer.
  • Total Time: A field which holds the total time.
  • Time last Started: This field will be given a UTC timestamp when the timer starts, which is used to determine the state of the timer: on or off as users navigate to other records.

Text Editor

Required Fields

  • Rich Text HTML: This is the field where the rich text will be placed and read from when the editor loads.

Simple Chart

Required Fields

  • Field One: A number field with a value that will be graphed on the chart.

Non-Required fields

These non-required fields are additional data points you can plot on the chart.

  • Field Two
  • Field Three
  • Field Four

As we have said before (and I’ll probably say one hundred more times), the Claris FileMaker Add-ons just work. In just a few minutes, you can get a fully functional heatmap or activity timeline running with your data (all records or a found set) in your custom apps. In just a few minutes, you can solve a high-value problem for your customer. Add-ons bring more power to the problem solver.

However, there’s a lot of us that want to know how the add-ons work. So let me explain, generally, how they work. We built these add-ons with the following ideas in mind:

  • They provide a complete package of scripts, layouts, custom functions, and objects.
  • They needed to be self-booting. No special setup is needed.
  • They needed to work on all parts of the platform.
  • In some cases, they needed to refresh themselves or refresh by an action.
  • They need to work with your data and with your choice of settings.
  • Many instances of the add-on can be used throughout the file, even multiple instances on the same layout.

Let me explain these ideas. The ones we skip for now will be detailed further in separate posts.

Types of Add-ons

There are two types of add-ons included in the FileMaker 19 update: Dashboard and single record add-ons.

The Dashboard add-ons include Kanban, Activity Timeline, Calendar, Heatmap, and Photo Gallery. I call them “Dashboard” add-ons because of two reasons: They can work with a found set of records from any table in your entire app, and they can be placed anywhere in your file. The context isn’t important; all the scripting and custom functions can gather the data and code necessary for the add-on.

The Single-Record add-ons include Rich Text Editor, Timer, and Barcode Generator. These require the context that provides them the relevant fields. For example, the Timer add-on needs to be on the “Task” layout so that the user can use the add-on to time her work.

Keep these two types in mind as you work through the rest of this.

Complete Package

As we’ll say repeatedly, these add-ons provide a complete package of functionality. That includes all the tables, layouts, scripts, JavaScript code and custom functions. Here’s a breakdown of each of those.

Tables

There are two tables that are part of each of the add-ons: a SampleData table, and an Addon table, a table named after the add-on.

Sample Data

This table holds records that are used when the add-on first is installed. After dragging the add-on to a layout, the widget gets data out of this sample table so you can see immediately what it looks like working. Feel free to delete this table any time during the process.

Addon Table

The Add-on table contains a few important fields, vital to the workings of the add-on. You wouldn’t want to delete this table while the add-on is installed. The fields here are:

HTML: a text field holding the inlined/minified code that runs the add-on. There’s no need to get into this field and examine its contents; the code is practically unreadable.

ConfigStore: This text field holds a JSON object. This Config object contains one object for each unique instance of the add-on you use throughout the file. It determines the layout from which to get the data, the settings, the filter fields, etc. There’s a lot there. When we talk about multiple instances of add-ons, we’ll go more into detail.

Additional Fields: The additional fields that have global storage are there for additional settings. OriginalTable, OriginalLayout, are fields that temporarily store what’s needed for add-on navigation, and the Query field is an example field of how to do a query. Use that field by default for the query. Take a look at that blog post to learn more about how to use this field.

Layouts

Within a Layout Folder with the specific add-on’s name are two layouts. One is the “Configurator” layout, and the other is the Sample Data layout.

The Configurator layout contains only a single web viewer. This layout is opened as a card window. You can rename this since it’s referenced directly in any scripting.

The SampleData layout is used initially as the target layout for gathering data for the add-on. Once you target your own layout, you can delete this layout.

Custom Functions

The two custom functions that come with each add-on are there to build the data URL for the add-on (AddonDataURL) and to collect the configuration of the target widget from the ConfigStore field (AddonConfig). You should not have to do anything with these. Don’t delete them. I would just let them be, but here’s some info about each one:

AddonConfig: This custom function requires the AddonUUID and pulls from the ConfigStore field that config which matches this AddonUUID. As you first install the add-on, the default config (the “Dev_UUID” config) is pulled and used. This config is eventually sent to the add-on code where the individual settings are picked up and used to render the add-on.

AddonDataURL: This custom function builds the add-ons data URL and merging in the initial props of the add-on (found in the web viewer object). This grabs the entire inlined HTML from that field and substitutes in the props.

Again, you probably don’t need to do anything with these. If you want to add props, you can do that in the web viewer object itself.

Scripts

We’ve organized the necessary scripts into “Public” and “Private” folders inside the Add-on named folder. In upcoming posts, we’ll examine many of the scripts. But just know, those in the “Public” folder can be called from buttons or triggers. The scripts in “Private” don’t need to be touched or examined at all. For fun possibly, in a later post I’ll explain the Private folder’s scripts.

Self-Booting

Each of the add-ons was built to be self loading. No action of the user, whether through a button press or moving to a layout, is necessary for the add-on to work. On its own, the web viewer loads the code, grabs the data, and renders it all.

The add-on is loaded through this web-viewer calculation:

The calculation is fairly straightforward. In the variable declaration of the Let() function, the AddonUUID is generated (see the post about multiple instances) and the config is gathered using a custom function. The InitialProps JSON object is constructed with various values, and then finally the DataURL is loaded into the web viewer with those initial props. From there, the JS takes over and renders the add-on.

Every time a user comes to the layout, this calculation runs and the add-on is loaded with the relevant data.

The Meta properties of the initial props, by the way, a lot of the rendering. For Windows or WebDirect, there’s certain rendering logic the code will execute, and the localization of the add-on is controlled by the Language property.

The Entire Platform

These add-ons are in the FileMaker product, and it was vital to get them working in all parts of the platform. They were tested and we made adjustments based on the needs of, say WebDirect. The new JavaScript functionality allowed us to ensure they work on macOS, Windows, WebDirect, and FileMaker Go.

Refreshing

Add-ons need to be able to refresh so that new data or changed data is visible. So we built mechanisms to do that. We’ll get into the weeds about this in an upcoming post, but here’s the summary. Many of the add-ons will refetch data periodically. They’ll do a complete new find of the data and display the new data in the add-on. Additionally, you can trigger a refresh of the data in the add-on. We’ll get to these in another post.

Work with Your Data

This one is obvious: these add-ons need to work with data in the app (from any table, any set of records (all or a found), and this needs to be set up easily. To accomplish these goals, the add-ons are constructed to use your data through the Configurator.

This is the only place you’ll have to do some set up right away after installing. In browse mode, click the gear icon (usually at the top right of the web viewer) and open the configurator. Here you’ll be given various required choices, a choice of filters (if applicable), and some add-on-specific settings.

Each option has some clarifying help text below, but I’ll point out some extra details:

Each add-on requires a layout choice. In most cases, this layout will be the data-source layout–the layout from which the data comes.

The Dashboard add-ons–Kanban, Calendar, photo Gallery, Heatmap, and Activity Timeline–all require a data source layout. The Single-Record addons–Timer, Barcode Generator, and the Rich Text Editor–each require a layout where the add-on is actually placed.

You choose that layout and the rest of the required settings will be fields from that layout. The choices for each field will come from the fields on the layout, and will filter by the type of field required.

Multiple Instances

You can use multiple instances of an add-on throughout a file or even on a layout. Each add-on can be configured differently in color and in source data fields, and they each run independently. Here’s a silly example, but it does demonstrate the point.

We’ll explore this in greater detail in a future post. There’s a bit to unpack here, so we’ll take a look.

Add-ons Just Work

This Claris FileMaker 19 Add-ons just work. They’re built as a complete package that function as they’re intended. So use them. Explore them and place them in apps for your clients. Use their power to solve complex use cases and move on with other things to solve.

With Claris FileMaker 19, there’s a new world of power opened for us in using web viewer widgets inside our applications. We can create and use calendars, tables, lists, date pickers, charts, data trees, data maps, and thousands of other widgets. With Claris FileMaker 19, there’s a whole lot more power given to the problem solver with JavaScript in FileMaker.

The Problem

The most obvious problem with using JavaScript in FileMaker is learning JavaScript. The language, though developed to be a beginner language, has become complex. There’s lots to learn. There’s concepts, techniques, tricks that a web developer spends years learning. A JavaScript developer will spend most of her career learning, refining, and understanding JavaScript.

We don’t have that time. We don’t have time to watch many of the hundreds of videos out there on JS or even the entire courses. What we need is to find that which will help us in our FileMaker work now.

The solution?

JavaScript in FileMaker

This learning path is all about getting a FileMaker developer using JavaScript in FileMaker in as little time as possible. This thought is not crazy at all. In all the work I’ve done over the past five years, I come back to a few JavaScript concepts and techniques over and over again. The language may be big, but the parts of it we need as FileMaker developers are well defined and smaller than the entirety of the language.

Think of it like a Entity Relationship Diagram: FileMaker on the left, and JavaScript on the right. The word “in” is the relationship. We can look at the JS language through the ‘in’ relationship and see only the parts of JS that is useful right away.

The learning path takes us along five well-trod workflows, that which  we do already in FileMaker. They are:

Five workflows: Perform Actions, Manipulate Data, Load Code, Update the Display, Retrieve Data

This path explores the JavaScript techniques and concepts that perform these five workflows. In Manipulating Data, for example, we’ll look at how to reconfigure an array of data from FileMaker for use in a JavaScript library.  In the Performing Actions workflow, we’ll explore how to create functionality in JavaScript and how to call the function from inside the web viewer or from FileMaker.

There is some technical stuff to know, for sure. We’ll need to understand how to style elements in the web viewer or what the window object means. None of this knowledge is beyond any FileMaker developer.

The Path for Everyone

This is the JavaScript learning path that I suggest any FileMaker developer take. As Cris Ippolite mentioned in a Claris Engage panel recently, this path didn’t come from some professional JavaScript developer. It came from someone (me) who first asked what one can do do with the web viewer, sat down to study how to organize JS libraries in FileMaker (and which would be useful in FileMaker). This path was marked through writing about JavaScript and using it and answering questions in the community.

Taking the Path

Very very soon we’ll have a complete set of instruction and practices around these five FileMaker workflows. Any practices we do will involve FileMaker every step of the way: The new JavaScript functionality, the new Execute FileMaker Data API script step, and the web viewer itself. We’ll build sample projects, and I’ll challenge you to construct this in (a copy of) a current app you’re developing. We’ll also review documentation, books, blog posts, and others’ videos on JavaScript so you see the whole world from the safety of the current path.

Alternatively, you can take the specific JavaScript concepts and techniques and extract from other JS courses what you need to know. Wes Bos is a great web-development teacher (he literally says “I’m here to help you become a really good web developer.”), and I encourage you to review his videos on the specific skills that we have defined in the path. This mode of transport will not be specific to FileMaker, of course, but you can get a lot out of any JavaScript course that will help you in FileMaker.

Onward

Jump on this JavaScript learning path and work with me and hundreds of other FileMaker developers to learn JavaScript in FileMaker. Follow this official Twitter account (@JS-learnjsforfm) and of course, stay tuned to the site for more information and the complete instruction set.

Click here to view a larger version.

On this very afternoon, the day before Claris Engage 2020, we pause to contemplate all that’s going to happen in the next few days. While we will miss seeing old friends or meeting new friends in the hotel lobby, at the fireplace, or sipping on a cocktail at the hotel bar, we are excited about what’s to come.

There’s a lot in store for this short week, and so this is the opportunity to let you know of four important events on our side. Here they are:

Engage with Us and the Community

As we’ve written about before, since we can’t gather in person, we will gather together with new and old Claris friends this year in a Slack Workspace called Auto-Enter. Please join us and meet someone new.

Geist Interactive Sale

Our award-winning dev tools and addons are on sale for you as of right now. Stop by the website to pick up FMPerception, LedgerLink, Otto, or any other tool to help you out. With great products comes great service, and we’ll be here for you to answer questions and support you along the way. The sale applies also to subscription renewals.

There’s no code necessary. Just add items to your cart and you’ll enjoy the savings!

New Product: FMComparison

From Dave Ramsey, the maker of the award-winning dev tool FMPerception comes FMComparison. It’s the fastest diff-tool out there. Simply run the “Save a Copy as XML” command (FileMaker 19 only) on two versions of the same file, and you’ll see all the differences of the newer version compared to the old. It’s an amazing tool with lots of possibilities.

The beta of FMComparison is out now, and those with a valid license of FMPerception will be able to use this tool for free. So join the beta and let Dave know your thoughts.

Geist Interactive Presents!

In two sessions on Tuesday, August 4, Todd will present a demonstration of add-ons and some JavaScript. This will be an introduction to: Add-ons, the new JavaScript functionality, and the new Execute FileMaker Data API script step. Jeremy and Todd will join Claris representatives as part of the Q&A portion of the first session. If you have questions you’d like answered, please send them to support@geistinteractive.com or ask them tomorrow during the time.

The sessions are:

FileMaker 19 Under the Hood: Javascript & Add-ons: (Aug 4, 10:15-11:15 PDT)

Panel: Add-Ons & Open Platform: This Changes Everything: (Aug 4, 12:00 -12:45 PDT)

You can still register for these sessions. Don’t miss out!!

We look forward to the week of excitement in the Claris Community! It’ll be fun and busy and exciting. The next few days are going to fly by and will be incredibly inspiring. We can’t wait. Oh, and FYI: Since the excitement happens Tuesday and Wednesday, we will not be holding office hours this week. Please take the last part of the week and reflect on Claris Engage and watch the awesome on-demand videos.

We at Geist Interactive are thrilled to be a part of the first ever Claris Engage, in this year 2020. Though this first event is a virtual one, we will be part of the the event in the 1’s and 0’s that make up cyberspace. There’s a lot going on, so let’s take a moment to review and point out a few things:

Here’s a rundown of what’s happening.

The Main Channels

Chat with Us & Others in the Community

A Slack workspace where you can join with fellow virtual Claris Engage folks (the folks aren’t virtual, the conference is hosted in the cloud). It’s like a “Watch Party” for the main event. Come and hang out with us and others.

The Lobby Bar

Engage Live

Vendors

The Main Event

August 4th and 5th, Claris is hosting the free Claris Engage. That’s amazing. As I considered this idea, spending two days online engaging with others in the Claris Community, I see a lot of possibilities:

  • At home, in my comfortable office with all my gadgets and toys.
  • I can take a break and go freshen up without anyone noticing I’m leaving the session.
  • I can get lots of sleep.
  • There’s very little walking.
  • And for me, the pool is way less crowded.

Of course, there are a few drawbacks:

  • I won’t be able to eat delicious and generous foods. I can’t say “This is vacation! Three plates of desserts doesn’t count.”
  • I won’t be near other FileMaker folks. No one wearing a badge lanyard will be wandering around to whom I can say hi, or at the very least, give the ol’ subtle nod as we pass each other. You know, maybe I’ll make my three dogs walk around the house with lanyards from past events. Hmmm. . .
  • I don’t have an excuse to hang out at the bar at all hours of the day.
  • And, most importantly, I won’t get to connect to friends, nor will I get to make new ones as easily this year.

The Virtual Sessions

Anyway, the main event, on those two days (and the same two days that the Auto-Enter space will be available) Claris is hosting live webinars with Claris folks and Claris partners to talk about higher-level concepts with this new open-release platform. I’m sure we’ll hear some detailed technique or so, but these sessions are conceptual in nature. They center around performance, and ‘low-code’, design excellence, user experience, and add-ons, to name a few. The Claris leadership will join us virtually in our homes to answer our questions we have about the platform, the future, and (possibly) their pets.

I looked at the session list for those two days. There’s too many to point out–they’re all very good sessions and topics. I look forward to hearing the panel of experts on each one share their conceptual understandings and forward-thinking views of our platform.

But if I must point out a few, here’s what you MUST absolutely ‘attend’:

  • The Opening Keynote: Delivering the Promise of Digital Transformation: (Aug 4, 9:00 AM PDT)
    • Here’s where we get to here CEO Brad Freitag and the leadership team talk about what’s new at Claris and their path and vision forward.
  • FileMaker 19 Under the Hood: Javascript & Add-ons: (Aug 4, 10:15 AM PDT)
    • Todd is part of this panel. They’ll discuss the newly-added add-on functionality and the newly-enhanced JavaScript workflow in the platform. Todd will demonstrate how add-ons are built and the use of JavaScript in those add-ons.
  • Driving Customers towards Modern Design Excellence: (Aug 4, 2:00 PM PDT)
    • This panel is made up of experts in design, including Alexis Allen who talked with us early this year about Workflow Based Design. I personally hope they mention JS add-ons in their discussion 🙂
  • Vision Forward: Claris Platform Futures: (Aug 5, 12:00 PM PDT)
    • It’s a tradition at Claris conferences to see some peek of what’s coming next in our FileMaker and Claris Connect apps. We developers all look forward to this, and we usually work to secure a seat up front to see ‘extra close’ what’s new. This year, we all get front-row seats. Robert Holsey and the other project managers will put on their best smiles and drum up their passion for the platform for us all to see.
  • Looking Ahead to Emerging Technology: (Aug 5, 1:00 PM PDT)
    • I’m interested to see what is emerging from the Wedge (or virtual Wedge, as the case may be) in the form of new technology. We’re all so used to the FileMaker Application. What’s next? I hope a robot, of some sort.
  • Closing session: Awards, Recognition and Our Path Forward: (Aug 5, 4:00 PM PDT)
    • The closing session is always a rousing feel-good session that sends us back to our work (since we’re not travelling at all this year). The awards and recognition lifts our tired spirits and energizes us to continue to solve problems for our clients. The panels, this year, I’m sure will inspire, but these closing remarks by Claris is meant to set us on their path forward. So stick around for these!

Other Events

Immediately after the two days of sessions and panels, the On-Demand sessions will be released. I’ve got two sessions that will be part of this release, so stay tuned to this post and our Twitter for those announcements.

“See” you “@” Claris Engage

We hope to see you there ‘at’ Claris Engage. Please stop by our hang out area and say hi to us and others in the community. And please ‘stop me in the hallway’ and introduce yourself if I’ve not met you yet. Show me your JavaScript work with which you’re tinkering, or ask me questions about JavaScript.

Todd and I talk about FileMaker Primary Keys today in the Context Podcast. Here’s the episode. Listen to it here.

And here are the highlights.

Well-Discussed Topic

The topic of FileMaker primary keys gets talked about a lot in the community, and indeed I asked about it long ago.

The Basics of FileMaker Primary Keys

Primary keys are simple to understand, but implementation takes nuance, and there is a lot to talk about. The nuances sort of come out of our understanding of primary keys.

The simplest database definition: A field (only one Field in FileMaker) that contains a value that uniquely identifies a record in the database in a table in the database. A primary key is an address, sort of. In other databases, you can have multiple fields to be defined as primary keys. In FileMaker, we only can use one, and that’s okay because of the platform we’re in. It’s not that necessary to study other platform’s use of primary keys, but it’s good to know others are out there.

The book Database Design for Mere Mortals by Michael J. Hernandez talks about primary keys, and defines it as being unique across the whole file. We as FileMaker developers can do that, but it’s not necessary.

Primary Keys NOT Supported in FileMaker

In fact, FileMaker doesn’t really have the strict support of primary keys. Primary keys are supported in other databases, so the database engine knows there’s a relationship between the primary key and the foreign key. You have to pick a primary key in other platforms; FileMaker doesn’t require them. In fact, for years, no real mention of the idea of primary keys was mentioned. Starter solutions had field names such as “Match Field”.

A Starter Solution using the primary key “Contact ID Matching Field”

Ways to Generate FileMaker Primary Keys

We make a field be a FileMaker primary key by setting it up as unique and by using it in relationships. Since FileMaker 17, we’ve had default fields (updated in FileMaker 19) which identifies a field in that utility set as a primary key in the XML.

The Get(UUID) function ensures that each primary key value will be unique, even across the whole file. There’s certainly a difference between in-theory and in-practice, and we can be assured that FileMaker will do its best to ensure primary keys are unique. Todd has done tests of creating millions of records and never got a duplicate UUID.

FileMaker Primary keys can be serial number, auto enter, where FileMaker increments the next value by a number. There’s a lot of problems, namely that importing data into a new version of the app could cause issues in that the serial value doesn’t get updated so the next value would not duplicate any existing value. Set Next Serial Number script step helps in this regard, but it’s extra work.

There are custom functions that create primary keys as unique values. The math behind the calculation ensures a very low chance of getting a duplicate.

Get (UUIDNumber) again will not give you a duplicate in practice.

Natural Keys ≠ Primary Keys

Readability of the FileMaker primary key is nothing we should consider. Primary keys shouldn’t mean anything to developer or user, nor should they be visible on a layout. Let your strict relationship logic rely on the math of the UUID functions. It’s really not a value in a field; instead, it is a link.

Natural keys are unique keys that visually identify a record. Student numbers, social security numbers, etc. are natural keys. And these shouldn’t be used as primary keys. Natural keys are valuable for integrations. They shouldn’t be used for relationships. Natural keys are great, and use them. But just for visual identification.

Switching Key Types

If you already use serial numbers as primary keys, you should consider switching to using Get(UUIDNumber) as your method of creating keys. There’s an advantage: the type of field doesn’t have to change. If your last serial number is 45, and the first UUID Number is 893928392919281929 . . . there’s no issue; relationships will still work.

Another reason for switching from serial numbers is syncing. Without UUIDs, syncing will break. Records created on Device 1 and device 2 can have the same serial value in the key, and that’s going to be a major problem when both devices’ data gets synced to the main file.

Does Every Table Need a Primary Key?

Every table doesn’t need a primary key–look ups, value list tables, etc. However, there’s not really a problem to have primary keys in every table (in fact, the default fields ensure this to be the case).

There’s a look up kind of table, one that holds information in it about a unique record. A Country Code table, for example, could use “US” as a primary key since that is unique to the table. As long as we’re not using “US” for relational logic, it’s okay. Look-ups are different.

Primary Key Implementations

FileMaker Primary keys are indexed. Text keys have two indexes, and that can increase the size of the file. But this is rarely a problem.

Default Fields tag a field as a primary key, and those are needed for Add-ons. We think Claris is moving towards supporting primary keys.

Naming FileMaker primary keys: this is up to the developer, but just be consistent. We use <<TableName>>_ID for the primary key.

The Data Migration Tool auto-increments the serial number.

Using Primary Keys with Integrations

Using primary keys with integrations is tricky in many cases. Our product LedgerLink handles the issues, and its method came from Todd’s extensive tinkering with the idea. Here’s a brief summary:

Integrations bring to the table a more complex problem. As far as primary keys are concerned, It is tempting to use the FileMaker primary key as the link between an invoice in Quickbooks Online and a FileMaker app, such as LedgerLink. After all, QBO has all the invoices and so does the FileMaker app. The problem comes in restoring invoices from QBO to your FileMaker app. All the primary keys you used for the links will be gone (the records are deleted) and as invoices are imported into the FileMaker app, new primary keys will be generated. The link breaks.

So the QBO keys (established in QBO and never changing) should be used as the link. Easy? Not so fast. . . In QBO, there is no such thing as invoice lines in the API we get back. Lines of an invoice are packaged up with the invoice, and there’s no foreign keys for each line.
In FileMaker we need primary keys and foreign keys to set up the proper UI and relationship. We can’t use the QBO Ids.

So we really need both. We need to build a system that maintains the link for each invoice to QBO through its IDs but also use Primary keys and foreign keys to build what we need in FileMaker.

Thinking about Primary Keys in Practice

Generally, we have to think, when using Integrations that become your source of truth and from which you might have to restore data into FileMaker, you have to consider this idea and work to maintain the links between the integration’s end point and your FileMaker apps. There’s a lot more; maybe we’ll explore that in a future episode or blog post.