With Carafe Kitchen, implementing JavaScript into your Claris FileMaker 16+ solutions has become as easy as copying a script. With all the new features in FileMaker that are supporting JavaScript, the one thing that I found lacking and still difficult to overcome was a solid process for managing and implementing JavaScript libraries. After struggling to roll my own implementations that could be maintained easily, I was relieved and excited to find this valuable tool. Carafe Kitchen has been one of the most exciting FileMaker tools for me this year. 

What Is It?

Carafe.fm is a community bundle sharing resource for FileMaker, sponsored by Soliant Consulting. It provides a community for building and sharing JavaScript bundles that have been streamlined for use with FileMaker. You can use it to install JavaScript add-ons, deploy JavaScript libraries that are wrapped into a single script, or even build bundles for the community to share.

To get started, just download one of the Carafe solutions. There are two FileMaker solutions for Carafe that provide easy access to some of the community-driven bundles. They are Carafe Add-on and Carafe Kitchen. While I think the Carafe Add-on is a pretty cool idea, as it allows you to use the add-on feature in FileMaker to dynamically install unlimited bundles into your solution, I really love the simplicity and ease of using the deployment process that the Carafe Kitchen provides. For the purpose of this blog, I am going to focus on Carafe Kitchen, as it has been the tool I prefer.

How Does It Work?

Carafe Kitchen allows you to configure and deploy the various Carafe bundles by wrapping them up into a single script. By doing so, they are easy to modify and adjust after you have put them in your own solution.

You’ll see  a list of bundles that have been submitted by the community. Once you pick the bundle you like, you click to deploy and it is copied to your clipboard by way of the Base Elements plugin. You simply paste the script, containing everything you need sans a web viewer, into your solution. Then, to finish it off, add a web viewer object to a layout, name it “web”, and you can see the results. The process seems magical, and is very clean and simple.

It isn’t a new concept, but it has been well thought out. FileMaker developers have been able to utilize a web viewer and render JavaScript-driven content since FileMaker 16. Implementing JavaScript content efficiently, on the other hand, had previously been a little difficult. You had to wrap up the HTML with JavaScript yourself and come up with different techniques to access and maintain that code. This process sometimes included embedding it in sneaky ways so that it could survive cloning of the solution. It ultimately meant you were managing several workarounds and possibly creating technical debt problems down the road. 

Pros & Cons

Here is a breakdown of the pro’s and the con’s I found during my exploration:

Pros

• Easy deployment process – select the bundle and click deploy

• FileMaker centric code – easy for a FileMaker developer to maintain

• Example data preloaded by default – makes it easy to test 

• Structured example for passing a parameter to the script – makes it easy to pass data as parameter into the script

Cons

• Uses substitute on variables – can be slow on large data sets

• Large JavaScript Bundles may be broken up into several  “Insert text” script steps

Carafe Kitchen has a solid deployment process that is streamlined, keeping the HTML with JavaScript embedded in the script and easily maintainable. It avoids some of the older pitfalls like placing the HTML content on layout objects or hiding it in field data. Instead, it uses  the “Insert Text” script step to create a variable for the content of the web viewer. With the “Substitute” script step, you substitute placeholders in that variable with data from your own solutions. Once the variable has been updated, it finishes by loading a web viewer with the customized variable.

“Insert Text” is great for storing the HTML and JavaScript libraries, but it does have it’s limitations. Because JavaScript library sizes will vary, larger libraries, when packed into bundles, can get big. You may notice several “Insert Text” script steps with larger bundles because this  script step has a character limit which many of the bundles exceed. In order to overcome the “Insert Text” maximum character limit of 30,000, content is broken up into smaller chunks when placed into the script. This can make modifying the JavaScript code in the script a little more challenging, but for minor edits it works fine.

Each script provides an example (test data) so you can preview the JavaScript before attaching your own data. While this is great for small sets of data, gathering the data from your solution for larger sets can present problems and needs to be handled with a bit more care. Some simple script step techniques for small sets of data might include using the FileMaker Data API, ExecuteSQL, or looping through a found set of records and building an array of JSON objects to pass to the script.

How Easy Is It To Deploy A Bundle Into Your Solution?

There are plenty of tutorials to get you going at Carafe.fm, but I’ll give a brief walk through of what I did to implement the Circular Progress Bar bundle into a demo solution. These steps were pretty easy and that is what makes this system so helpful. I went with a basic install, but there are plenty of ways to customize it.

• Download Carafe Kitchen.

• Open Carafe Kitchen in a supported version (currently FileMaker 16+).

  • If you don’t already have the Base Elements plugin installed, it will prompt you to do so.

• Find the bundle you want. There are a lot, and they have samples so you can preview them! In this case I searched for “progress” and the Circular Progress Bar was at the top of the list.

• Select the bundle and click Deploy.

• Select the deployment type and follow the instructions – I chose to go with Standard Deployment and Production Script.

• While it may seem fun to choose the Standard Deployment, and choose Development Script (instead of Production Script), you should take note that I tried this and learned that it requires your FileMaker solution to have an external data reference to Carafe Kitchen. This selection is useful for a more advanced development process of making changes to the bundle in Carafe Kitchen while developing. If you choose to go this route, be sure to take advantage of the tutorials! 

• Click “Copy Standard Script”.

• Paste the script you just copied into your solution.

• Add a web viewer to the layout you want and name it “web”. Web is  the default, but you can customize the name, too, if you wish.

And that’s it for installation. To test and see if everything works, you can run the script from the layout where you added the web viewer. By default it will load test data, so you can preview it. They provide a great sample of how to pass a JSON object parameter to the script, and the next step would be to write a script that collects whatever data you need, calling the script and then passing that data in.

Enjoyable Results

While I liked this bundle, I wasn’t sure if I might have been missing something, as there didn’t appear to be any way to automatically update the progress bar, incrementally, once the bar was displayed. I decided to add a JavaScript function that I could call using “Perform JavaScript in web viewer” and then place it in my FileMaker script to update the progress bar at regular intervals. I was surprised by the outcome and the ability to keep the web viewer window animated while the script created records and ran in the background.

I thoroughly enjoyed playing with Carafe Kitchen and testing this progress bar bundle. If you are interested in seeing the results, check out our demo file below. I created a little test script in the file to update the progress bar as it runs. If you are a geek like me, it is a lot of fun.

Here are the key additions to the demo file that I added. Enjoy!

The function that I added to the Carafe script bundle, contained in the Insert Text script step – line 37

We’re Happy To Help!

If we can assist you with implementing JavaScript in your FileMaker solutions, please get in touch through  the contact form below! You can also schedule a complimentary intro meeting to discuss your questions and ideas.

Thanks for reading!

We’re hiring a FileMaker Developer! This fully remote position is a great opportunity to join a successful, growing team of FileMaker developers based in the Seattle area, but doing work for clients around the country. We’re working on some of the most cutting edge FileMaker technologies – the FileMaker data API, 3rd party REST API integration, and always the latest versions of FileMaker. Apply now!