BlogFileMaker

JavaScript Integration in the FileMaker 19 Platform

By May 20, 2020 May 22nd, 2020 8 Comments

Using JavaScript in your FileMaker apps has been possible for a number of years now, and there are a great many examples, demos, and resources available in our community. Notable among those is our free Carafe framework (Carafe.FM).

Two new script steps and one new function in FileMaker 19 significantly lower the threshold to embrace JavaScript (JS) and those three pieces of functionality cover the three main challenges:

  • How do you call a JavaScript function?
  • How do you feed it the necessary data based on your FileMaker Data?
  • How do you get a result back?

Why JavaScript?

If you are already using JavaScript in your FileMaker apps, you will find the new functionality very easy to incorporate into what you are already doing. It will allow you to do what you are doing in an easier way. If you are not using JavaScript yet, you may be wondering why you should.

For a number of years now, many of us have been pointing to the power of JavaScript and demonstrating how it fundamentally changes how we architect FileMaker apps.

JavaScript has the computational power to process data faster than the other FileMaker functions and scripts can, especially when many iterations are involved. JavaScript also offers a wide array of User Interface widgets and data visualizations that complement other FileMaker features.

Our oldest Soliant blog post dates back to 2014 when FileMaker released FileMaker 13v2, and it allowed you to trigger a script through a URL using the ‘fmp’ URL handler. From that point forward, it was easy to use that in JavaScript to complete the loop and bring the JavaScript result back to FileMaker.

JavaScript integration got a little easier when FileMaker 16 was released because now you can easily construct JSON objects and arrays, which many useful JavaScript libraries expect as their input. We started on a JavaScript integrations library in 2016 that culminated in our streamlined Carafe.FM bundles.

The power of JavaScript has been demonstrated often, and we are huge proponents. And now it becomes even easier.

How does it work?

At its core, the new functionality works very much like before: you need a web viewer to hold an HTML document that contains your JavaScript code. The HTML does not need to actually show anything if your goal is to just leverage the computational power of JS. Figure 1 shows the most basic HTML that serves as the source for the web viewer on the right. As you can see, the web viewer is blank since we do not intend for it to show anything; in this case, we just need it as the vehicle for the JavaScript function named receiveJSON(input).

Screenshot of Layout Mode with the web viewer on the right and source on the left

Figure 1. Web viewer on the right with source on the left

Before 19, you would have to find a way to collect your FileMaker Data and format it into something that JavaScript understands well: arrays, JSON, comma-delimited and substitute that into the HTML source text. Then you’d need to find a way to run the JavaScript function, usually by setting the web viewer so that page it loads triggers and executes the JavaScript. When it is done, you have the HMTL call back to FileMaker through the fmp url mechanism.
The examples in the blog posts mentioned earlier use that mechanism.

One of the big downsides of the fmp url mechanism is that it doesn’t work gracefully in WebDirect; it opens a new tab which spawns a new WebDirect session. And there are also URL length restrictions in play that limit how much data you can pass back to FileMaker as the script’s parameter. And to make matters more complex, the length of a URL varies by operating system from a few thousand characters to around 80,000.

With 19, you now have a new JS function FileMaker.PerformScript(). This new JS function works much better than using an fmp url, especially in WebDirect, and in general, it is now completely cross-platform as well. Plus it allows for enormous results to be returned. In our testing, we gave up after generating a result that was 100 million characters long.

Note that this JS function runs asynchronously: it does not wait for the FM script to finish, so you cannot use it to get a result back from the FM script.

Also, since FileMaker 16, the user’s privilege set had to allow for the “fmurlscript” extended privilege to use the fmp url mechanism. In 19, there is no such requirement since everything remains strictly within FileMaker itself, and that generally increases the security of your solution.

Below is a side-by-side example of the old way and the new way to illustrate the differences. The example used is a simple JavaScript that takes an input string and reverses it. “muffins” becomes “sniffum.”

FileMaker 13 through 18

The web viewer (object name ‘wv’) gets set with precalculated HTML syntax:

Screenshot of web viewer object set with precalculated HTML syntax

Click image to enlarge

Lines 6 and 9 construct the HTML and JavaScript syntax to account for the differences in URL behaviors between macOS and Windows due to the URL length restriction discrepancy mentioned earlier.

The string that needs reversing is made part of this block of text that is then set as the web viewer’s source.

It is line 11 when the web viewer is set, and that action loads the HTML and executes the JavaScript.

The HTML and JavaScript look like this:

Screenshot of the HTML and JavaScript

Click image to enlarge

The line in red is where the JavaScript is executed.

The lines in green are how the HTML page is set up to redirect to an fmp URL that runs the script and passes the JavaScript result as a parameter to the FileMaker script.

FileMaker 19

Here, the HTML code and JavaScript code already exist, and the web viewer is already loaded. That in and by itself does not run the JavaScript like before.

The JavaScript is executed by using the new Perform JavaScript in Web Viewer script step and giving it the name of the JavaScript function and the parameter it needs: the string to reverse.

Screenshot of Perform JavaScript in Web Viewer script step

Click image to enlarge

The HTML and JavaScript code is now much simpler, and you use the new FileMaker.PerfromScript() JS function to call your FileMaker Script and give it the result.

There is now no difference between macOS and Windows or iOS or WebDirect.

Screenshot of the script function

Click image to enlarge

Your web viewer can now be a static library containing many JS functions because they can just sit there passively waiting to be called. The web viewer does not need to be loaded to activate them: you call them by name with the new script step.

Note that the new Perform JavaScript in Web Viewer script step is NOT server-side compatible, so you cannot use it in PSoS, server-side schedules, or through the Data API, XML, or PHP APIs.

That new script step and the JavaScript function are the heart of the simplified JavaScript integration. It makes JavaScript a lot easier to implement and a lot more consistent across the operating systems and various FileMaker client platforms.

The example used above is all about making use of the raw computational power of JavaScript. The other big use cases for JavaScript are in User Interface and data visualizations. You will find a lot of those in our Carafe.FM open source toolkit: from calendars to flexible table views, maps, navigation widgets, and high-end drill-down charts:

Carafe.fm - Sankey Bundle

Carafe.fm - Datatables Object Bundle

Carafe.fm - CodyHouse Breadcrumbs and Multi-Step

Carafe.fm - Liqud Fill Gauge

Carafe.fm - D3 Collapsible Force Layout

Carafe.fm - Maps

One of the challenges in using these UI widgets and data visualizations is that often you need to grab a lot of FileMaker data to pass on to the underlying JavaScript library. That task has now become easier as well with a brand-new script step in 19: Execute FileMaker Data API. This step allows you to compose a query and get the resulting FileMaker data in JSON format.

First and foremost: despite its name, this script step does not call the FileMaker Server Data API REST service; the name is a bit unfortunate in the sense that “Data API” is already strongly associated with the REST service. It does use the same internal Data API engine in that it uses the same query syntax and the same JSON format for the resulting data.

This new script is somewhat similar to the executeSQL() function:

  • You can use it to get data from any part of your solution, independent of the user’s current context.
  • You cannot use it to create or edit data (this could change in a future release)
  • You cannot use to run scripts (this could change in a future release)

But it is different in that you will get data back based on the layout you specify: all the fields, including portals that are on the target layout, will be returned to you.

The query syntax is described in the Data API help, it’s a JSON object, and in its simplest form, you specify just the layout you want to use and the number of records it should return. The query can, of course, be more complex in that you can specify multiple search criteria, limit and offset the found set, sort the data, and so on. See the Data API help for the options, but keep in mind that the options to run scripts, for instance, are not supported in this release.

Screenshot of a query

Figure 2. A query


Screenshot of the resulting JSON

Figure 3. The resulting JSON

Where this script step comes in handy is in passing the data straight to a JavaScript function. JavaScript is extremely fast at parsing JSON, so there is no time lost in translating your FileMaker Data into JSON before you send it to the web viewer. No longer do you need to substitute data into the web viewer’s HTML source. You can feed this JSON straight into the JavaScript function you call with the Perform JavaScript in Web Viewer script step by specifying it as the parameter when calling your JavaScript function.

Screenshot of the 'Perform JavaScript in Web Viewer' options window and calling a JavaScript function

Figure 4. Calling a JavaScript function and passing it a parameter

Here too, we have tested this with huge amounts of JSON data and have not found any limitations yet on how much data you can pass to a JavaScript function.

The new script can, of course, also be used for many other purposes, including sending data to external APIs for purely for internal FileMaker consumption. This script step is fully supported on all clients, WebDirect, on server, and through the Data API.

In closing

Using JavaScript in your FileMaker apps just became a whole lot easier; we are looking forward to seeing what our community comes up with in this area. Keep your eyes open for an updated release of Carafe.FM

Wim Decorte

Wim Decorte

Wim is a Senior Technical Solution Architect at Soliant. He is a FileMaker 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17 and 18 Certified FileMaker Developer and the author of numerous Tech Briefs and articles on FileMaker Server. Wim is one of the very few multiple FileMaker Excellence Award winners and was most recently awarded the FileMaker Community Leader of the Year award at the 2015 FileMaker Developer Conference. He is also a frequent speaker at the FileMaker Developer Conference and at FileMaker Developer groups throughout the world. In addition to being a renowned expert on FileMaker Server, Wim also specializes in integrating FileMaker with other applications and systems. His pet project is the open source fmDotNet connector class that he created.

8 Comments

  • Avatar Dick says:

    Hi Wim,

    I’ve got a few examples working, but can’t get your example working. Keep getting an error 5.

    This is the html/javascript:

    function reverseMyString (input){
    var txt = input;
    var last = “”;
    var s = “”;
    var lgth = input.length;
    while (lgth){
    input = input.substring(0,lgth);
    last = input.slice(-1);
    s +=last;
    lgth = lgth -1;
    };
    FileMaker.PerformScript (‘return_from_js’ ; s );
    }

    • Wim Decorte Wim Decorte says:

      Error 5 usually means a syntax error in the JavaScript. Where you use FileMaker.PerformScript, the separator between the parameters should be a comma instead of a “;”.

      • Avatar Dick Honing says:

        Hi Wim,

        thanks for your fast reply and help! I’m fairly new to JavaScript so I still got to learn the proper syntax. I’m already using a syntax validator (https://esprima.org/demo/validate.html) but unfortunately, you’ve got to take the FileMaker.PerformScript line out in order for it to work.

        But now that I know this, I should be fine with most of the other JavaScript code 🙂

        Thanks again and best regards – Dick

        • Wim Decorte Wim Decorte says:

          Another tool you can use is Microsoft’s VS Code. Free and extremely powerful and can validate JS syntax plus easy to use to actually write your code. Works on both macOS and Windows.

  • […] Wim Decortes Javascript post is an excellent overview […]

  • Avatar Jonathan Ackerman says:

    Do you need to run FMS 19?

    i tried using FileMaker.PerformScript and got it working fine in FM Pro 19 but not webdirect,
    the javascript loads fine in WD but will not execute the script in WD.

    this is my sample:

    FM Test WD

    Click me to change my text color and run a script.

    function myFunction() {
    document.getElementById(“demo”).style.color = “blue”;
    FileMaker.PerformScript(“nr”,”x”);
    }

    ideas?

    thank you!

Leave a Reply

Need to adjust your business processes quickly? We're helping clients use technology to keep their teams productive and running smoothly in these times of uncertainty. Our team can guide yours if you need help in these areas.

Talk to a Consultant