Geist Interactive teamed up with Claris to produce a webinar focused on what JavaScript Can do for your FileMaker Apps. We also discussed how JavaScript fits perfectly into the FileMaker 19 Open Platform Release. Below are a list of resources, next steps and other online resources for people who attended the webinar.

Here’s the video:

Geist Interactive teamed up with Claris to produce a webinar focused on what JavaScript Can do for your FileMaker Apps. We also discussed how JavaScript fits perfectly into the FileMaker 19 Open Platform Release. Below are a list of resources, next steps and other online resources for people who att

Webinar Resources

Here are links to all the libraries we used in the webinar.

  • DataTables: Our number one library for creating a list view with a lot of built-in functionality. Check out Todd’s demo file.
  • Apex Charts: This is a cool, smooth, and modern charting library.
  • Kanban: The way we built a Kanban board as an add-on for FileMaker.
  • FullCalendar: The best and most widely used calendar JavaScript Library.
  • TUI Image Editor: A highly-functional image editor JavaScript Library.
  • PSPDFKit: A commercial JavaScript library that allows a user to annotate onto a PDF.

Geist Interactive Examples, Demos and Learning Tools

  • Jeremy’s JS Playground: A file we put together to lead the training session at DevCon 2018 and 2019. This is the OLD file. Download the next one if you wish to have the updated version.
  • JS Learning Path: A series of familiar FileMaker use cases and exercises in JavaScript.
  • DataTables Config file: A demonstration of using DataTables without knowing any of the JS. You can create settings in a FileMaker record, and use those to create a configuration.
  • DataTables: A list of all the blog posts we’ve done on this library.
  • C3 Charts: Another charting library. The post provides a start and end file and steps on how to integrate.
  • Audio Player: A cool small library to play an audio file in a container field.
  • FileMaker & JavaScript: Additional videos and posts about our JS study.
  • FileMaker & Javascript Training Session Redone: Jeremy posted videos and the files he used during the 2019 DevCon Training Session.

From the Claris FileMaker Community

Online Learning

Documentation

We’re Here to Help

If you have any questions about these resources, if you want to chat about JavaScript, learn JavaScript, or have us develop add-ons and integrations for you, reach out at sales@geistinteractive.com. We’re here for the FileMaker community to power up their apps with JavaScript.

This post is a summary of an episode of The Context Podcast, episode 40, release date 6/16/2020. In this episode, Cris Ippolite joins us to talk about Shortcuts and NFC. Those two features are the stated topic, but, of course, we touch on a lot of other things. So here’s a summary of what we discussed.

Please take a moment to subscribe to the podcast at Apple Podcasts or wherever you get your pods. There, you’ll find great technical episodes as well as our FileMaker Origin Stories series.

Outside of a Web Viewer

Cris shares a surprising finding about some JavaScript add-ons. He discovered, while playing with his demo file for LinkedInLearning, that you can get a part of a JavaScript input field to extend past the boundaries of the web viewer (on macOS only). The color picker-type input in question actually could also cover a FileMaker layout object as well. Cris was startled by this discovery.

Todd reminded us that inside a web viewer there’s a browser: Safari on MacOS, and IE 11 on Windows. He explained that control field types in HTML are provided by the operating system, not the web viewer or the browser itself. You can add styling to these control fields, but if you use the native input, the OS renders the color picker, so the color picker is ‘allowed’ to be outside the web viewer.

WebViewer Widgets

We’ve decided there are three types of web viewer widgets: Fullscreen, “Sneaky”, and Computational. We’ll talk about this more in another blog post, but here’s the quick definitions:

FullScreen Widgets

These widgets cover almost the entire layout. Users interact with the widget wholly. FileMaker buttons can be on the layout, and those buttons can interact in some ways with the widget.

Sneaky Widgets

These widgets are more subtle. They’re simply treated as objects on a layout, incorporated into the workflow-based design of the layout. These widgets sit alongside other objects, including fields.

Computational Widgets

These kinds of widgets are simply used to harness the power of the JavaScript engine and JavaScript libraries to return a value back to FileMaker. Users do not interact with these widgets. Scripts do. For example, if you wanted to find the first Thursday in the month of June, you could do that easier with a JavaScript library.

Machine Learning

As always, Cris is playing with FileMaker in prep for his courses or simply discovering new features. He played with an app called Hotdog/Not Hotdog to demonstrate this new feature. Check out his video.

Shortcuts

Before talking with Cris, I wasn’t convinced Shortcuts were a necessary thing. They were cool, for sure, but I was searching for reasons why I’d use these in a FileMaker app. And I thought ‘shortcuts’ referred to ‘Siri’. Cris schooled me.

This is a bulleted list of details Cris and Todd shared about Shortcuts.

  • Cris first did a session in 2016 on URL Schemes, where apps talk back and forth to each other on iOS. He profiled an app called Workflow.io. This app used to create url schemes between apps. This app turned into the Shortcuts app.
  • In FileMaker 19 we can ‘donate’ FileMaker scripts to the Shortcuts app. This allows us to set a Shortcut in the Shortcut app to run a FileMaker script.
  • Go into FileMaker Security, and enable the extended privilege “Allow URLs to run FileMaker scripts” for each privilege set.
  • You can pass a parameter to the FileMaker script that runs from a Shortcut. This is the same as the fmp url, which Cris suspects is what’s happening under the hood.
  • Transfer the FileMaker app with ‘donated’ scripts to FileMaker Go, open the app and create a shortcut for each of the donated FileMaker scripts.
  • Shortcuts are specific to each device, so even though a script is enabled to run via a shortcut, users of the app on iOS will not automatically be able to use the shortcut.
  • If you are using iCloud to share across devices, you can share a shortcut to all of your devices. This gives you a URL. This could actually be built into a FileMaker app and run onOpen: Do you want to install this shortcut? You can even text the URL to someone.
  • There is a security setting in iOS “Allow Untrusted Shortcuts”. This needs to be enabled.
  • Shortcuts simply run FileMaker scripts. You still have to manage security and permissions in FileMaker.
  • You can create an action in the Shortcut app that runs before the FileMaker script runs. The action can be a question. A user’s response to the question (a voice command) can be sent back to FileMaker as a parameter.
  • FileMaker Go doesn’t have to be open for this to work. Shortcuts will open up FileMaker Go and authenticate if necessary.
  • Cris has a great example: his Dog-Walking App. Check it out.
  • Record control is very important: If you’re using voice control, you need to make sure the record data gets committed. You might even want to use transactions to ensure the data gets saved.
  • Shortcuts don’t have to be just Siri. Shortcuts can be location or proximity based, they can be set on the home screen as buttons on the screen or the watch.
  • Todd brings up a good point: this and other features of FIleMaker 19 blur the lines of how to interact with FileMaker apps. We’re even more free from just having to enter data via a keyboard and mouse.
  • If the file is hosted and not found during the shortcut run, you can get the shortcut to let you know the file is not available.

Location-Based Triggering

There are many different types of location based triggers: Geo-fencing, iBeacons, NFC, and Barcodes

Geofence

  • Polled from the Configure Region Monitor Script Step.
  • Have a latitude and longitude and radius setting to determine coordinates of the ‘box’ that, when crossed, the chosen script should run.

iBeacons

  • Polled from the Configure Region Monitor Script Step
  • Run a script when you get near a physical object in the environment. The range is less than 30 ft. Each iBeacon can be set to trigger a script.
  • There’s tons of examples of using iBeacons.

NFC

  • NFC uses the script step Configure NFC Reading.
  • NFC deals with Near-field Communication. Apple Pay uses this, as Apple went all in on NFC.
  • NFC has been around for a long time, over 2 billion NFC pieces that have been produced.
  • For an NFC trigger, the device has to be within four inches of the NFC tag.
  • NFC tags can be read and written to. We can’t write it in FileMaker (yet).
  • You’re telling a script to run when the NFC tag gets detected. The data stored in the tag can be brought into the script using Get(ScriptParameter).
  • Writing to NFCs is cheap and easy. Buy a bag of of them. Spread them around your home and do things.
  • Again: NFC further helps us to interact with the world.
  • NFC is started via a script. A little card comes up on the lower-third of the iOS device.
  • You can turn off the NFC polling with the timeout option.
  • NFC passes the polling to the iOS device. FileMaker is not trying to find the tag.
  • Cris thinks it will be possible to write to an NFC tag from FileMaker in some future version of the platform.

Tinkering with FileMaker

And finally, I want to reiterate the idea of just playing with this stuff. That’s a great way to learn, even without a specific use case in mind, though I’m sure one will come to you shortly. Cris and Todd demonstrate that by just tinkering with script steps and devices, one will pick up a whole new skill set. Yes, reading blog posts and watching videos is useful, but nothing is as useful as just getting your digital hands dirty. A while back John Renfrew and I talked about this very thing.

So give something new a try. Let us know what you tried and what you learned.

In part 1 of All That We Know on Add-ons, explaining all that we know about this new feature, we talked about how to create add-ons that lend themselves to UI widgets. Calendars, check box button bars, notification popovers, date pickers, timers, etc. all can be dropped into a custom app as they are. Sure you might need to attach some fields to scripts, but essentially these kinds of widgets are a complete package.

There are other types of add-ons that require a more extensive relational set up. That is, you might wish to build an add-on called “Notes” that consists of a related table of notes displayed in a portal. This add-on is meant to be installed anywhere in your file and in many different files. This add-on takes the place of having to build this table, the scripts, and the relationships over and over. Build it once. Package this as an add-on, and boom. Use the add-on many times.

In this post we’ll look at how to create this “Notes” add-on package, which, in database terms, requires a one-to-many relationship. We’ll also explain how to create a many-to-many relationship add-on, such as a “Schedule/ Classes” package.

Considerations

  1. We are creating add-ons from the ‘related table’ context. Since, in this post, we’re using the use case of “adding a notes package to a custom app”, our add-on creation starts with the Notes context (table).
  2. 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.
  3. 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.
  4. 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.

Yes. I know these points are a bit confusing. We’ll clarify them in due time, but I wanted to point these ‘issues’ out to you right away. I’d recommend reading the three considerations again and see if you get an idea of their meaning.

So let’s get packaging!

Creating Related Packages

A Related package is one that will be added to a custom app and be automatically related to some other table in your file. Again, our example is “Notes”. We’re going to illustrate this process with a child table that holds notes for each project in a Project table. This is our end goal:

In a new FileMaker file (called “Notes”) add any fields you want in the package to that Notes table. This table should contain a PrimaryKey field and a ForeignKey field. Here’s my simple example:

Right here we have to stop and explain something very important: the PrimaryKey field MUST be identified in the eventual XML as a primary key field. There’s no way to do this in the Manage Database UI yet. The only recourse we have is to use the defaultFields.xml setup that FileMaker uses for each new table.

Since this Notes table is going to be related to a “Projects” table occurrence, I need the foreignKey field here. Unfortunately I cannot give it a more specific name, like “ProjectKey” or something. Since this add-on is meant for many different scenarios, it’s impossible to specify the name pre-install.

Set up the Layout

The layout needs to have the __FMAddonTemplateDirectives_en name, as we learned previously.

To this layout add a portal. Since the context of this layout is the Notes table occurrence, and eventually this will be a related table, use the “Current Table” option in the portal-setup dialog.

Yes, this is how we create master/detail lists, but the portal is simply showing records from the current table.

Include the relevant fields and style it how you wish.

Also include any scripts you wish such as one to delete the related record.

Include the foreign key field (and its field label) on this layout and give the object a name with the following three parts:

  • A Relationship name: R1
    • Your name can be anything, but it should be unique for each relationship you build.
  • Separator: |
  • Table Position: RightTable

The ForeignKey object is then named, in this example: R1|RightTable

Grouping Objects

The add-on package process requires groups of objects so the XML can be generated properly. As we do in UI add-ons, we have to group certain items and leave out others. With a relationship-based add-on we have to do a bit more grouping. Here’s how to group objects:

Group the UI element–in this case, the portal–like normal. This is the element dragged onto the layout after add-on installation. By the way, you can group the single portal object by also selecting the portal fields in the grouping.

Group the foreignKey field with its field label. Name it carefully with the prefix __FMAddonDynamicRelation_. Finish the name by including the RelationshipName you gave the actual ForeignKeyField: __FMAddonDynamicRelation_R1

Yes, we’re placing a foreign key field on the ‘special’ layout. However, this object will NOT be part of the drag-on package. Its only purpose is to help the XML know which field is meant to be the ForeignKey field.

Create the Add-On

With your handy external file, create the add-on package. Quit FileMaker. Re-open. Your add-on should be available in the AddonModules folder inside the FileMaker Pro Extensions folder, and it should be ready for installation.

Here’s what the Projects file relationship graph looks like without the add-on installed:

At Installation, the layouts, scripts are added to the file. Likewise the Notes table occurrence is added to the RG.

Notice there’s no relationships added as of yet. Don’t worry. Those will be added soon enough. Can you reason why the relationships have not been added? Stop and think about it for a second.

Don’t read ahead!

Seriously. Stop. Come up with the answer first.

Here’s why: During installation the package is just added to the FileMaker file. The add-on package has no ‘idea’ (yes add-ons are almost sentient) which table occurrence to attach itself to. There could be hundreds of table occurrences in an app. Like an alien in a ship, however, the add-on lies in wait ready for a table to latch onto. The latching comes not during this process but during the . . .

Applying an add-on Phase

When you drag the add-on out to a layout, the add-on picks up which table occurrence it should attach itself to. Here I dragged on the Notes add-on to a layout with the “Projects” table occurrence context.

This is what happened in the relationship graph:

As a bonus (or not) this relationship checks the “Auto Create” and “Delete” options.

So that’s how you create add-ons with relationships, with simple relationships. There are caveats. So let me clarify those. Let’s start with this consideration:

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.

This is key, and something to strongly consider:

When you drag an add-on to a layout, a relationship is created between the existing table occurrence and the table in the add-on. It will do this every time you drag the add-on to a layout of a different context. Observe:

I add a new table and layout called “Tasks”. The table occurrence is added to the relationship graph.

I then add the same Notes add-on to this layout.

Look what happens to the relationship graph:

What do you see? The Tasks table is now related to the Notes table. Let’s consider a few factors:

  1. Tasks and Projects are related to the same Notes table occurrence.
  2. Tasks and Projects are now related to each other.
  3. Tasks and Projects use the same foreign key field in the Notes table.

What do you think? Is this an issue or not? We certainly have our opinion, but we’re interested to see what the community thinks as well. Please leave your thoughts here or in the Claris Community forums.

Onward and To Be Continued

This is a long post; let’s leave this one at this point and pick up “Join Table” type relationships in the next post.

Modernize your apps with data visualization, maps, calendars and more.

Open up a new universe with Claris FileMaker apps and JavaScript. Learn why JavaScript is such a good fit for the Claris FileMaker 19 open platform. See several compelling business examples, and find out how you will be able to use JavaScript add-ons for things like kanban boards, calendars, photo editors, animated graphics, and more. The possibilities are virtually endless.

Best of all, you don’t need to know JavaScript

You will learn:

  • What JavaScript brings to the Claris FileMaker.
  • The advantages of FileMaker custom apps built with JavaScript add-ons vs. SasS alternatives.
  • How to get started with helpful resources.

Join us for this 45-minute webinar lead by Todd Geist, Geist Interactive, a Platinum Claris Partner. The presentation will include an overview, demo, and a Q&A session.

Note: this presentation will be in English only.

Date: Tuesday, June 23, 2020
Duration: 45 minutes
Times: 8:00 AM PT, 11:00 AM ET, 3:00 PM GMT, 17:00 CET
RSVP now:
https://content.claris.com/amr-webinar-fm-javascript-06232020-reg-8am

Times: 4:00 PM PT, 7:00 PM ET, 9:00 AM AEST (Wednesday, June 24, 2020)
RSVP now
https://content.claris.com/amr-webinar-fm-javascript-06232020-reg-4pm

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 Process

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.

Some Notes

  1. 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.
  2. 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.
  3. 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.
  4. Once installed by the developer, the add-on is available to everyone using the app.
  5. 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.
  6. 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.
  7. 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.

This heatmap add-on consists of a group of objects (highlighted in the Objects panel on the left). That group consists of the web viewer, a button bar (on the left), and a single button (on the right). Additional objects are on the layout. They are NOT part of the add-on.

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

__FMAddonTemplateDirectives_en

!! 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.

Layout Objects

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).

Create Objects

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.

Add-on Names

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:

  1. 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.
  2. Remember: you can have any number of layouts as part of the package. The only layout that will not be bundled are the __FMAddonTemplateDirectives_ layouts.
  3. 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.

Including Data

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 Replace UUIDs.

Window Name:

  • pass in the window name of this window.

Replace UUIDs: 

  • 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:

TitleThis 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.
DescriptionYou can include a description here to give users information about what to expect in its functionality.
CategoryA defined category. This is how add-ons will be grouped in the install dialog.
FeaturesInclude an array of features, one feature per array-element.
OptimizedInclude 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 support@geistinteractive.com for quick answers to your questions, or post in the Claris Community.

There’s a lot more to discuss about the FileMaker add-ons. You can read more about how to create add-ons here:

Part 2: Creating Add-ons with Relationships

Part 3: Creating Add-ons with Join Relationships

It’s well known that we have advocated for using JavaScript in Claris FileMaker for many years. Both yours truly and Todd, separately and now together, talk JavaScript and its use in our platform. Todd realized the language could be used in FileMaker since the moment the web viewer was introduced in FileMaker 8.5, and I. . . well, eventually I figured it out (FileMaker 15, I think it was). We know that JavaScript is native to the platform (always has been) and provides a better–more interactive and modern–experience for users, whether showing them animated graphs or crunching calculations. It just makes sense to use JS in FM.

Problem

But there were always problems with with the implementation of JavaScript in FileMaker. It wasn’t FileMaker’s fault necessarily. The problems centered around how to get data from FileMaker into the web viewer, and how to get data out of the web viewer effectively. The problems had to do with refreshing the web viewer or the opposite–leaving the chart in the current state. And problems centered around working in all areas of the platform (WebDirect, I’m looking at you!).

Attempted Solution

Todd tried to solve the many problems by creating the FM WebViewer Bridge, a library to pass data back and forth to the web viewer’s code. It worked mostly very well. Many of our products relied on the Bridge, and I taught a training session at FileMaker DevCon 2019 where we spent at least 3 hours working with the Bridge. It worked. Mostly. (WebDirect, I’m still looking at you!)

Real Solution

But now, in Claris FileMaker 19, we no longer have to use the FM WebViewer Bridge. If you’ve ever used it, you can throw it away! Stop using it. This ‘escape hatch’ (as Todd calls these things) is no longer necessary; we have in FileMaker 19 all we need to solve most of the web viewer problems. The new functions provides so much more flexibility and functionality that the Bridge ever could achieve. (This fact, of course, is because Claris built a bridge-like component into FileMaker itself). And if you’ve never used the FM WebViewer Bridge, don’t. Don’t try to learn it. Just forget about it.

Full disclosure: Todd has always advocated for tossing out the Bridge once this functionality arrived and you’re using FileMaker 19; I’m not being insubordinate.

Of course, if you’re still working in FileMaker 16-18 you have to use the FM WebViewer Bridge. If you care about WebDirect, however, FileMaker 19 and the new functions are a must.

Communicating Better with JS Libraries

Claris FileMaker 19 introduces the Perform JavaScript in Web Viewer script step and a JavaScript function named FileMaker.PerformScript(). With these two functions we can work almost perfectly with JavaScript in the web viewer–whether you choose to build them yourselves, of if you choose to use a JavaScript widget add-on. No matter your path, these two pieces of functionality will greatly enhance your users’ experience.

Let me give you a brief description and use of each, but also let me say that Todd and I will be hosting some coding parties and Office Hours once in awhile to demonstrate working with this new bag of functionality in the upcoming weeks. Stay tuned. If you want to work with these functions, we’ll show you how and give you our insights into their use. We’ve spent the last nine months wrestling with the script step and the JS function, so we have lots of insight about how to use these.

Back to the brief description. I’ll include an example I’m working on. Here’s the end result:

It’s it beautiful?

This sliders add-on (or it will be an add-on) was meant to take a found set of records and render them as such. Each question could contain the actual question, a set value, and a disabled option. The way I built this could handle any number of questions and, eventually, different range scales for each question. There’s a lot of possibilitiy.

NOTE: This is a bit of a complex example, but the principles that I illustrate will apply to simple and to complex ones. I’ll include a simple example on this post.

The script that runs this starts by first collecting the questions from the table, collecting the configuration of the sliders (as in the colors, range, etc). The script then loads the JS code from a field into the web viewer.

The Functions Themselves

The Perform JavaScript in Web Viewer Step

This step is our key to interacting with the JavaScript inside a web viewer. It takes a few parameters:

Object Name: the name of the web viewer object on the layout. This is an important parameter (other than being required). You could have on a layout multiple web viewers, and you could have multiple scripts that update each one. So name your web viewer and provide the name here.

Function Name: this is the JavaScript function ( case matters here) that’s in the web viewer (the browser). It’s cool to note here that JavaScript has a lot of built in functions, so you don’t even need a written JS function in the web viewer’s browser.

Parameters: the parameters indicate what you want to pass to the JavaScript function. You can pass 0 or more parameters (called “arguments” on the JS side) into the function for its use. We typically pass a JSON object into the function, but you can pass many parameters. Each one is then picked up by the function and used in some way. Here’s an example (made up, for sure).

In my sliders example, I’m using this step to actually load the data and the configuration into the JavaScript code. Notice line 13 in the image below. I’m using this step to tell the web viewer what function to run–setInitialFMProps()–, and I’m passing to the function a JSON object in the $json variable.

The JavaScript Function

Inside my JS, I’ve got a callback function to FileMaker. It looks like this:

You can see window.FileMaker.PerformScript("ChangeData",obj) is the function.

The ‘window’ part of the function is something I added. I wanted to make sure this function was available globally.

The “ChangeData” is the name of the script. Here Case doesn’t matter; FileMaker can find a script called “Changedata” or “ChangeData” or “changedata”.

And finally, I’m passing back to FileMaker the value of the obj JS variable.

Considerations

If you’re reading this post and have never used JavaScript, you might be a bit lost; never fear. We at Geist Interactive will lead some coding sessions where we walk you through it and answer questions. So look for that.

But if you’re already familiar with working with JS and web viewers, here are some considerations:

  1. The JavaScript function “FileMaker.PerformScript()” must be loaded into the web viewer before you try to call it. It must be available. We use window. to put it in the global space.
  2. You can pass a JSON object from FIleMaker to the JavaScript function you call via a script. But that object is really just a string, so you have to use JSON.Parse to convert it to something JS can read and parse.
  3. Passing a JSON object from JS to FileMaker requires a JSON.Stringify() call on your JavaScript object. You can see the example above.
  4. ERROR: The Perform JavaScript in Web Viewer script step returns error 5 if it wasn’t able to actually call the designated function. Careful to trap for this because the next steps in your script could depend on the web viewer being loaded.
  5. All of this works on WebDirect by the way (WebDirect, I forgive you!).
  6. There is an issue with refreshing the web viewer on WebDirect. We’ll provide more detail in other posts.

There are other considerations to think of, and we’ll explain those shortly. But the key is that these two features provide MUCH BETTER collaboration between FileMaker and JavaScript.

Onward

So give it a try. . .

. . . Or, if you’re not yet learning JavaScript, look out for add-ons and sample files that demonstrate the usefulness of these two steps. As I said in a recent podcast episode, even if you never touch these two steps, the add-ons you eventually use require these, so it’s necessary to have at least a passing understanding of what’s happening.

We’ll be back to demonstrate in videos and live coding sessions how to use these functions. We’ll also provide our recommendations for learning JavaScript. Don’t worry; we won’t require a master’s level understanding of JS. There’s a lot you can do with just a few basic JavaScript skills.

In a previous post, we wrote about the new Execute FileMaker Data API script step. We wrote about its JSON-constructed data-gathering abilities. We’re pretty excited about this step. It’s useful for gathering a found set of records to display in a JavaScript-based add-on and for passing records to an API. But this new script step offers so much more information about the local file in which it is called. This post will explain those and show how to get the FileMaker metadata about the tables and fields.

The More Obvious Feature

If you recall in the previous post, I explained the query object you pass as a parameter, has a default ‘action’ key of ‘read’. Here’s an example query:

{
  "layouts" : "People",
  "limit" : 500,
  "offset" : 1,
  "layout.response":"",
  "query" : [ {"City" : "Denver"}],
  "sort" : [{"fieldName": "LastName" , "sortOrder": "ascend"}]
}

By default, this step performs the action of ‘read’. This key/value pair isn’t included since that’s the only thing this step does.

Getting the FileMaker MetaData

However, late in the game, the engineers added another action to this script step: metaData. Just like in the FileMaker Data API call, you can get the a lot of information about the tables and fields in the file. Actually this script step gives you more information than the web API. Here’s the list of supported queries.

Get All Tables

With the following query, you can get all the table occurrences with data sources and base tables in the calling file.

{ 
  "action": "metaData", 
  "tables": "" 
}

With this query, I can look at LedgerLink’s tables. Here’s the response.

{
   "messages":[
      {
         "code":"0",
         "message":"OK"
      }
   ],
   "response":{
      "tables":[
         {
            "baseTable":"Account",
            "name":"Account"
         },
         {
            "baseTable":"Class",
            "name":"Class"
         },
         {
            "baseTable":"Customer",
            "name":"Customer"
         },
         {
            "baseTable":"PaymentLine",
            "name":"Invoice_PaymentLine"
         },
         {
            "baseTable":"Customer",
            "name":"Invoice_Customer~all"
         },
         "..."
      ]
   }
}

The result of this query is an array of all the base tables and the table occurrence names (the name key). Notice the base table “Customer” is returned twice. That’s because there’s two table occurrences in this file with that table source.

By the way, this is not in the FileMaker Data API. This FileMaker metadata query was created just for the script step.

Get All Fields of a Table

Applied to a specific table occurrence, you can get all the information you need:

{ 
"action": "metaData", 
"tables": "Invoice_Customer~all" 
}

Here’s a partial response:

{
   "response":{
      "baseTable":"Customer",
      "fieldMetaData":[
         {
            "autoEnter":true,
            "fourDigitYear":false,
            "global":false,
            "maxCharacters":0,
            "maxRepeat":1,
            "name":"id",
            "notEmpty":true,
            "numeric":false,
            "repetitionEnd":1,
            "repetitionStart":1,
            "result":"text",
            "timeOfDay":false,
            "type":"normal"
         },
         {
            "autoEnter":false,
            "fourDigitYear":false,
            "global":false,
            "maxCharacters":0,
            "maxRepeat":1,
            "name":"taxable",
            "notEmpty":false,
            "numeric":false,
            "repetitionEnd":1,
            "repetitionStart":1,
            "result":"number",
            "timeOfDay":false,
            "type":"normal"
         },
         {
            "autoEnter":false,
            "fourDigitYear":false,
            "global":false,
            "maxCharacters":0,
            "maxRepeat":1,
            "name":"contactGivenName",
            "notEmpty":false,
            "numeric":false,
            "repetitionEnd":1,
            "repetitionStart":1,
            "result":"text",
            "timeOfDay":false,
            "type":"normal"
         }
      ]
   }
}

Notice it returns the table occurrence’s name and an array of every field in that table. As you can see, the FileMaker metadata provided for each field is plentiful and thorough.

Again, this step is not in the web api!

Get All Layouts

In the web api, you can use the following query to get all the layouts:

{ 
"action": "metaData", 
"layouts": "" 
}

In the Execute FileMaker Data API script step, the response includes table occurrence names. Wow. Look at this response. It even includes the folder structure.

{
   "layouts":[
      {
         "folderLayoutNames":[
            {
               "name":"Splash",
               "table":"meta"
            },
            {
               "name":"About",
               "table":"meta"
            },
            {
               "name":"PivotTable",
               "table":"meta"
            },
            {
               "name":"-",
               "table":""
            },
            {
               "name":"Home",
               "table":"session"
            },
            {
               "name":"Sales",
               "table":""
            },
            {
               "name":"Main Menu",
               "table":""
            },
            {
               "folderLayoutNames":[

               ],
               "isFolder":true,
               "name":"Utilities"
            }
         ]
      }
   ]
}

Get Fields and Table Occurence MetaData from a Layout

{ 
"action": "metaData", "
layouts": "CustomerTest" 
}

And finally, with this query:

You get the information back about the fields (and only those fields) on a specific layout.

{
   "messages":[
      {
         "code":"0",
         "message":"OK"
      }
   ],
   "response":{
      "fieldMetaData":[
         {
            "autoEnter":false,
            "displayType":"editText",
            "fourDigitYear":false,
            "global":false,
            "maxCharacters":0,
            "maxRepeat":1,
            "name":"billAddressCity",
            "notEmpty":false,
            "numeric":false,
            "repetitionEnd":1,
            "repetitionStart":1,
            "result":"text",
            "timeOfDay":false,
            "type":"normal"
         },
         {
            "autoEnter":false,
            "displayType":"editText",
            "fourDigitYear":false,
            "global":false,
            "maxCharacters":0,
            "maxRepeat":1,
            "name":"billAddressCountry",
            "notEmpty":false,
            "numeric":false,
            "repetitionEnd":1,
            "repetitionStart":1,
            "result":"text",
            "timeOfDay":false,
            "type":"normal"
         },
         {
            "autoEnter":false,
            "displayType":"editText",
            "fourDigitYear":false,
            "global":false,
            "maxCharacters":0,
            "maxRepeat":1,
            "name":"billAddressLine1",
            "notEmpty":false,
            "numeric":false,
            "repetitionEnd":1,
            "repetitionStart":1,
            "result":"text",
            "timeOfDay":false,
            "type":"normal"
         },
         {
            "autoEnter":false,
            "displayType":"editText",
            "fourDigitYear":false,
            "global":false,
            "maxCharacters":0,
            "maxRepeat":1,
            "name":"billAddressLine2",
            "notEmpty":false,
            "numeric":false,
            "repetitionEnd":1,
            "repetitionStart":1,
            "result":"text",
            "timeOfDay":false,
            "type":"normal"
         },
         {
            "autoEnter":false,
            "displayType":"editText",
            "fourDigitYear":false,
            "global":false,
            "maxCharacters":0,
            "maxRepeat":1,
            "name":"billAddressPostalCode",
            "notEmpty":false,
            "numeric":false,
            "repetitionEnd":1,
            "repetitionStart":1,
            "result":"text",
            "timeOfDay":false,
            "type":"normal"
         }
      ],
      "portalMetaData":{

      },
      "table":"Customer"
   }
}

Note: by specifying a layout, this script step returns the Table Occurrence name of the layout as well.

Uses

This function of the Execute FileMaker Data API script step is extremely useful. Generally, code that is portable, such as add-ons, often need to ‘sense’ where they are located. They aren’t hard coded into the context of the host solution. This step fills the gaps left in the Design Functions and the ExecuteSQL functions. So there’s a lot of use. Here’s a few other examples.

We’ve been using this new action to query information about the file for JavaScript-based add-ons. We can build a query about a specific table or field and use that to tell the JavaScript the fields from which to return data.

Also, the metadata, as I said above, is the only way to get the table occurrence upon which a layout is based.

Onward

We’re just scratching the surface at what can be done with this FileMaker metadata action. We’ll keep playing with it and exploring more we can do with the Execute FileMaker Data API script step. And we’re interested to see what the Claris community comes up with for this step.

Download a sample file showing what you can do with the Data API

Geist Interactive is ready for FileMaker 19. All of us are fully briefed on the new features, we’ve downloaded our copies, and we’re beginning to use the Open Platform for our clients. We are ready, and if you need us to build you add-ons or modules, if you need us to solve your problems (we are problem solvers, after all) we are ready to do so.

Just as the human team is ready for FileMaker 19, so too are our products and free tools.

Each of our products can be used in the latest version of FileMaker generally. And below I’ll point out specific products and their compatibility with or features of FileMaker 19.

FMPerception

As we stated previously, FMPerception 19 has been updated for FileMaker 19. FMPerception specifically points out in a new column of the Standard Functions, those functions that have a behavior change. We strongly recommend you use your copy of FMPercetion to check this out. If you’re not using FMPerception, download the 14-day trial and see how useful this tool is for Filemaker 19.

GoSign and GoDraw3

GoSign and GoDraw3 rely on the FileMaker web viewer object. They’ve always worked well on FileMaker Go and FileMaker Pro (and continue to do so), but they do not yet work on WebDirect using the new JavaScript functionality.

WidgetStudio

WidgetStudio is our library of web viewer widgets that you can use and enjoy on FileMaker Pro and FileMaker Go. There’s a lot of use for this tool even now in FileMaker 19. However, none of the included widgets yet work with the new JavaScript functionality available in FileMaker 19. Our plan is to create these widgets as add-ons and make them available in various way.

Other Tools

Barcode Creator

There’s no issue here. Barcode Creator has been working well for clients since FileMaker 12.

The HTTP Request Script

Check this tool out. We’ve written about it before and consider it one of our most valuable free modules.

Karbon & Generator

Karbon, Generator, and DamageDetectoR are useful everyday as we work on FileMaker 19. And they work just fine.

Onward

If you have any questions about these tools’ capabilities in FileMaker 19, please reach out. We’re glad to assist. And feel free to download each product’s demo and see how it works for you in FileMaker 19.

FMPerception, the only Realtime Developer Intelligence Tool in the Claris Community, is ready for FileMaker Pro 19’s new and changed features. Dave Ramsey, the creator of the tool, has ensured that FMPerception will help you as you begin to use FileMaker 19 to create apps for your clients. FMPerception features, of course, change to reflect the new version of FileMaker, and we will go into details about each of them below. We recommend you use FMPerception to help you transition to using FileMaker Pro 19, as there are some important things to consider.

And if you’re not using FMPerception, download the 14-day trial and give it a try. You won’t regret it.

Updates for FMPerception 19

FMPerception 19 gives you better tools to learn about your custom app as you develop on your custom app. Below is the list, and below that we’ll go into detail about specific ones.

  • Added support for FileMaker 19’s new standard functions.
  • Added support for FileMaker 19’s new script steps.
  • Included in the Indirection Sources results are two of the new script steps, Execute FileMaker Data API and Perform JavaScript in Web Viewer.
  • There’s a column in the Scripts section to indicate scripts that run from a Siri Shortcut.
  • The Privilege Sets section includes a column indicating when a privilege set allows management of accounts.
  • The Standards Functions section includes a column indicating when the functionality of a function in FileMaker Pro 19 has changed.
  • In the Top-Call Stats report, the IP Address and User Name columns have been placed correctly on Windows (thanks to Jonn Howell).
  • FMPerception will not crash while processing the Top-Call Stats by FileMaker Element on macOS (thanks to Tom Oathoudt)

The benefits of these new features

Let’s point out the details on some of the features listed above.

Indirection Sources

First, FMPerception includes Execute FileMaker Data API and Perform JavaScript in Web Viewer as indirection sources. As you go about your work and update names of fields or scripts or tables or layouts, FMPerception will remind you that you are using these steps (among others) in your scripting. So you should check each step to make sure you’re not breaking those when you rename these objects. FMPerception doesn’t tell you the exact layout name you used in in the Data API script step, but FMPerception does indicate you’ve used that step in your app.

The Perform JavaScript in Web Viewer script step as an indirection source simply alerts you to the fact you’ve used the step in your solution. Since the names of any fields and scripts you might send into the JavaScript using this step are hard-coded, it’s worth knowing where you’re using this step.

Changed Functions

FileMaker Pro 19 includes Get(ApplicationVersion) which changes its behavior. In previous versions of FileMaker, this function returned “FileMaker Pro Advanced” when using that product. There is no “FileMaker Pro Advanced” anymore starting with version 19, so this step only returns “Pro”.

This function is used by many folks to manage some level of compatibility. Often it is used to show objects or conditionally format an object when the advanced version of FileMaker is used. The opposite is true: FileMaker developers also hide (or show) or conditionally format an object when FileMaker Pro Advanced is NOT being used.

From now on, “FileMaker Pro” is the name of the client version, even when the Advanced tools are used. So we as developers need to review our use of this function and update it appropriately.

FMPerception helps with this: the Standard Functions report indicates which functions have been changed (there are a few others), and the report shows you where you’re using those functions.

We strongly recommend you check for functions marked as changed before using FileMaker Pro 19. Export your DDR in FileMaker 18 and open it in FMPerception 19. You’ll see all the instances of these functions.

Use the GUIDs

I sat with Dave and recorded a podcast about these changes. We’ll get that out very soon. In the episode, he mentioned that everyone should activate the use of the GUIDs as we start to use FileMaker 19.

This new feature of FileMaker Pro 19 gives every FileMaker object a unique ID. This is part of the new XML structure of FileMaker. The XML describes each object and it describes the last time each object has been modified from the first time the XML was created. FileMaker developers may want that in some future version of the product. For now, Dave Ramsey recommends we do this:

Run the “Save a Copy as XML” command in the Tools section of FileMaker Pro 19. This generates, for each object, including scripts, tables, fields, layouts, a unique object ID. From that point on, FileMaker Pro keeps track of the number of times that object has been modified.

Once you have the XML copy, just discard it. The whole purpose of this process was to get the GUIDs created for each object.

FMPerception is here and ready for your needs in FileMaker Pro 19. Use this intelligence tool to learn all about your system while you’re developing in your system.

And join us for Office Hours each Thursday at 4pm EDT. Dave Ramsey and the Geist Interactive team will demo features of the tool and answer your questions.

 

FileMaker 19 introduces an incredible leap forward in gathering data in the near-universal data exchange format known as JSON. No longer do we need to write schema just to collect a found set of records into a JSON array of record objects. Now we can use the Execute FileMaker Data API Script step to query any table occurrence in the open and current file, to control that query, and to sidestep annoying limitations and ‘gotchas’ found in other methods. We can now use a method first introduced in the FileMaker Data API (FileMaker Server) and brought to FileMaker Pro and FileMaker Go and FileMaker WebDirect. We are thrilled. We see lots of ways to use this one little new script step. Let’s explore this step and all we can do with it.

Where Did this Step Come From?

As FileMaker becomes more of an Open Platform, we want to send data to services, to JavaScript Widget Add-ons, and to pass data to other parts of the file. We need a better way to construct the data. It makes sense nowadays to construct the data into JSON–in fact most JavaScript libraries and all API services recommend, if not require, the JSON format. Claris listened to its partners and heard the need for something to be added that easily created the JSON without the burden of building extra schema to construct a found set as a JSON array. Partners suggested altering ExecuteSQL or creating a “asJSON” function to meet this need.

An engineer at Claris had the inspiration to make the FileMaker Data API engine available to the calculation engine. It was already in the product; it just needed to be exposed. And we are the better for it.

So now we have a great script step that packages up records as JSON. Let me reiterate: “A step”. As in “One step”.

The Step

The Execute FileMaker Data API script step (a long name, but on point), requires two parameters: a target and a request. The target is the variable or field into which we will place the response, similar to the other amazing step Insert from URL. The request is the JSON object describing the query. With those two simple parameters, we get back a full array of records as JSON objects.

The Request

The request parameter is a simple JSON object describing the query. It is simple because it only needs a few keys. Here’s a working example:

{
   "layouts":"People",
   "limit":500,
   "offset":1,
   "layout.response":"",
   "query":[
      {
         "City":"Denver"
      }
   ],
   "sort":[
      {
         "fieldName":"LastName",
         "sortOrder":"ascend"
      }
   ]
}

This request, hard-coded into an Insert Text script step defines only a few things: the layout upon which the query will be performed, the limit of the number of records to be returned, the query, the offset, and the sort That’s it. To find some records that are displayed on the People layout, we write a query like the one above. Let’s look at each key here:

layouts

The layouts key tells the step upon which layout to perform the query, basically, to do the find. This key is required because this script step really does go to this layout; it opens a new (hidden) window at this layout and sets itself to do the find. Without this key, the step doesn’t know where to perform the query and returns an error in the response.

NOTE: The key is plural, but you only use one layout for the value. FYI!

The layout itself can be any layout: a user-facing layout or, better yet, a layout specifically designed for this query, such as a dev layout (don’t we all have layouts with the prefix “dev_” in the name?). The layout must have all the fields that contain data you want to return in the response.

If you have three fields: City, State, Name, on the layout, those will be included in the response. Though I’ve never worked with it, this is true when using the actual FileMaker Data API. They actually don’t have to be visible on the layout–they can be off-screen–but they must be there.

Curiously the field in which you perform the query–”City” in my case– doesn’t need to be there.

Note: This is whole query, including the “layouts” key is a source of indirection. Use FMPerception to highlight all the places you used this step before changing layout names!

layout.response

This key, rather unfortunately named because of the dot, is a bit of a complexity. Its purpose is to tell the query from what context (that is, what other layout) to return the records. It’s a puzzling one and requires some experimentation.

limit

The limit isn’t required, per se, but if you do not include it, then the step will return the first 100 records. It’s best to set this limit to something higher than what you’ll actually need (more on this later).

offset

The offset simply tells the Data API script step to start at that record. If the the offset is 1, then it’ll return all the records in the set starting at 1.

query

This key defines the records you want to get from the step. And this key can be constructed using any normal FileMaker find string: “=Pre”, “>1/1/2020”, “*”, and “=”, for example.

The query value is an array, and the array can have one or many elements. Each element defines a new find request, and each find request can have multiple criteria. Here’s a few examples:

{
   "layouts":"People",
   "limit":500,
   "offset":1,
   "query":[
      {
         "City":"Denver",
         "Gender":"M"
      }
   ]
}

In this query, I’m searching for all records that include City of Denver and M as the Gender. This is an “and” query–both criteria must be met for the record to be found–it is just like me typing these two values into their respective fields in one find request.

{
   "layouts":"People",
   "limit":500,
   "offset":1,
   "query":[
      {
         "City":"Denver"
      },
      {
         "Position":"Boss"
      }
   ]
}

In this query, I’ve got an ‘or’ find. If I were doing this request in Find Mode on a layout, I’d enter “Denver” in the City field, create a new request and enter “Boss” into the Position field. This returns all records containing either “Denver” or “Boss”.

sort

The sort key is another array of objects. Each object defines by which fields the data should be sorted. You can have multiple objects inside this array to sort by multiple columns.

NOTE: Everything I’m showing here is hard-coded. But you’re a FileMaker developer; you work with JSON every day. You can figure out a way to make this dynamic: global fields (fields with global storage), variables, custom functions. The possibilities are many.

Unused Keys

If you’re familiar with the FileMaker Data API, the one from FileMaker Server, then you might see there are some missing keys. If you’re not familiar with the Data API, then there are missing keys. That’s okay. Read this section still to understand what’s missing; what’s missing gives you further information about this script step’s scope and purpose.

action: Currently the Perform FileMaker Data API only supports ‘read’. That is, you can only use this step to read data. The other actions–create, delete, update, duplicate– are not supported. There is some hope these will be in the future. There is one action, “metadata”, that we can use. We’ll get into this detail in a future blog post.

version: This script step uses a built in Data API engine; we don’t need to specify which one to use.

databases: This step only works on the file in which the script is located. So if you want to get data from another file, you would call this step inside a script in that other file.

Authorization: The authorization is the current-logged in user.

Content-Type: the response is JSON. That’s the point of this step!

The Response

Once the request has been created, the step returns the response. As I noted above, this step actually does open a window and performs the query. It does this without issue across the platform, so you don’t need to worry about compatibility. It’s fast; no one can stop this step midway to view the layout, and the window will close upon completion.

The response you get back is a JSON object with lots of useful information. You get back:

{
     "response" :{
            "dataInfo":{...}, 
            "data":[...]}, 
     "messages":[...]
}

From there you can pull what you need. Let’s look at each key in the response.

response.dataInfo

Here you get a lot of helpful information pertaining to the returned data result. In my query above, I get this:

{         
     "database":"DT_People",
     "layout":"People",
     "table":"People",
     "totalRecordCount":1005,
     "foundCount":22,
     "returnedCount":22
}

Notice the “foundCount” and “returnedCount” are two separate keys. That’s because of the offset. If my “offset” value is 2, then I’d only return the last 21 records because the return starts at record 2.

response.data

This includes the entire found set of records. Each element in the array is the data from the fields on the visible part of the target layout in JSON form.

[
   {
      "fieldData":{
         "Address":"3233 Blake Street",
         "Email":"",
         "FirstName":"Fred",
         "LastName":"Flintstone",
         "PrimaryKey":"2519874603326055443343358368631954311881461403190964389494"
      },
      "modId":"1",
      "portalData":{

      },
      "recordId":"2"
   }
]

The response.data key is an array of objects. Each object contains “fieldData” and other keys.

  • fieldsData: The data from the fields on the target layout
  • modId: the modification count
  • portalData: any related records of the record. We’ll review this in a later post.
  • recordId: the internal FileMaker ID of the record.

messages

Every API response includes some type of key that explains the status of the request. The Execute FileMaker Data API script does as well. Since we’re working with an API response, we gotta play by its rules and consider the message. Here’s the message received when I queried for some records in my table:

{
   "code":"0",
   "message":"OK"
}

Whew. My request was valid. The response sent back a number of records–be that zero, one, or more than one.

Since the query itself is a source of Indirection, the response could come back with an issue. Here’s what it looks like when I changed the name of the layout and forgot to use FMPerception to check to see where I used this step to see if I used this layout:

{
   "code":"105",
   "message":"Layout is missing"
}

Beautiful. The code is not 0, so there’s something wrong. The FileMaker Data API helpfully tells me what the problem.

If a query field is missing from the table, here’s the message:

{
   "code":"102",
   "message":"Field is missing"
}

Short. To the point.

Curiously, it seems the message only returns one code and message though there may be multiple errors in the query. I suppose if you have to look at the query, you can review all of it at one time to catch additional errors.

As of this moment, I don’t see a list of the errors returned. Luckily, as we said before, the message is simple.

To further repeat myself, working with an API–its request and response–we need to use all the right tools and considerations. We need to consider the message we get back from this step before we do anything else in the script, and we need to handle what to do when the response returns a messages.code of anything other than 0. This consideration is part of the world we live in, so we need to adopt this consideration into our practice.

Uses

There’s a ton of possible uses for this new step, and we at Geist Interactive plan on using it now to gather records in JSON format for JavaScript widgets or API payloads. We probably won’t rewrite existing scripts using different methods at this moment, but we will begin to use it for clients and products that support FileMaker 19.

As I was getting familiar with the step and as I was working on JavaScript widgets, I considered how the data can be placed into widgets that I know well. Here’s an example of the result being placed into DataTables:

Love that Dark Mode!

This was easy. The library can accept multiple forms of data, including JSON. So my set up was simple:

Notice the highlighted part. I was able to use “fieldData.FirstName” as the key for Data Tables to pull from each element of the array (the field on the right).

That’s good stuff.

Onward

We will be back in future blog posts talking more about this step. We’ll talk about its uses and considerations and even the cool feature to get metadata from the FileMaker file.

Give the Execute FileMaker Data API script step try. It’s a simple step that returns a lot of information and information neatly structured into JSON.