JSON ( JavaScript Object Notation ) is a useful function that was introduced in FileMaker Pro 16. JSON is a simple human readable data format that allows you to store and pass information across layouts and scripts. If you’re not using JSON yet, this article will give you some tips for adding it to your toolbox. In order to make that even easier, a FileMaker Add-On is included for download at the bottom of this article, which includes a suite of custom functions for working with and manipulating arrays. The custom functions have no dependencies and are built from FileMaker native functions to sort, slice, filter, search, or perform a calculation for each array element. This Add-On brings the JavaScript Array methods to native FileMaker.
To start with, there are two types of data storage in JSON: an array, where data are organized by order, and an object, where data are organized by field names, called keys. You can think of an array as a prioritized task list. The task list will stay in the same prioritized order, and each task is retrieved one at a time by its numbered order. It doesn’t matter what the element in the array is, it matters what order it’s in. An object is like a dictionary. Each item is made up of a word and a definition. Instead of requesting the 500th word as you would with an array, you request the word as the key in order to retrieve its definition.
Array Notation:
[
“Apple”,
“Kiwi”,
“Banana”,
“Strawberry”
]Object Notation:
{
"key":"value",
“Apple”:”green”,
”Kiwi”:”brown”,
”Banana”:”yellow”,
”Strawberry”:”red”
}Default Functions
FileMaker comes with six default JSON functions:
JSONDeleteElement ( json ; keyOrIndexOrPath )
JSONFormatElements ( json )
JSONGetElement ( json ; keyOrIndexOrPath )
JSONListKeys ( json ; keyOrIndexOrPath )
JSONListValues ( json ; keyOrIndexOrPath )
JSONSetElement ( json ; keyOrIndexOrPath ; value ; type )These functions give you the basic controls needed to work with JSON. A powerful tip is to utilize setting multiple, nested elements at once with JSONSetElement. To set nested elements, send the nested elements in a period delimited format; “parent.child.object.” This format is also used with JSONGetElement in order to reach into elements that are nested in objects or arrays. In an array, the keyOrIndexPath is the bracketed number of the array, with “[0]” being the first element of the array. JSONSetElement can also set multiple values at the same time in a bracket delimited format.
JSONSetElement ( "{}" ;
[ "produce.fruit.banana" ; "yellow" ; JSONString ];
[ "produce.fruit.apple" ; "green" ; JSONString ];
)
= {"produce": {
"fruit": {
"banana": "yellow",
"apple": "green"
}
}If we set the results of our produce object to the variable $produce, then we can use JSONGetElement to retrieve the values that have been set, as in the example below. It is important to note that JSON keys are case sensitive. For more about working with JSON in FileMaker, view this resource from Claris.
JSONGetElement ( $produce ; "produce.fruit.banana" )
= "yellow"Script Parameters
When calling a script, it is a best practice to include as much information as the script needs to run, instead of setting variables inside the script which are dependent on the current context. Creating a JSON object as a parameter from the layout button creates the context dependency on the layout instead of in the script. In the past, developers were limited to sending a parameter list in a specific order and then setting the variables from that specific order, or coming up with their own format to parse. With JSON, that format is standard and built into FileMaker native tools with functions for retrieving each value. For example, if a script sets a task category, that information the script needs can be sent as a JSON object and then parsed in the script before taking action.
{
“primary key”:”123-abc”,
”category”:”testing”
}Temporary Storage
JSON can be used as an object that stores key-value pairs, much like fields, and as array rows, much like records. Therefore, it is a powerful tool for storing FileMaker record data in temporary storage. This data can then be manipulated in variables within a script. Here is a tip for storing the found set of records into JSON with a single calculation. Replace the keys, fieldNames and data types to suit your needs.
While ( [ i=0; n=Get ( FoundCount ); result="{}" ] ; i<n ; [ i=i+1;
result = JSONSetElement ( result ;
[ "record[" & i-1 & "].label" ; GetNthRecord ( @Template::label ; i ) ; JSONString ];
[ "record[" & i-1 & "].title" ; GetNthRecord ( @Template::title ; i ) ; JSONString ];
[ "record[" & i-1 & "].description" ; GetNthRecord ( @Template::description ; i ) ; JSONString ];
[ "record[" & i-1 & "].type" ; GetNthRecord ( @Template::type ; i ) ; JSONString ];
[ "record[" & i-1 & "].category" ; GetNthRecord ( @Template::category ; i ) ; JSONString ]
)
];
result )Session Global Variables
Session global variables are another way that JSON can improve the organization and performance of your applications. Some developers will set a number of global fields or variables in order to track the current state of the user session, for interface or scripting purposes. Instead of multiple global variables, a single $$Session global can be set as a JSON object whose values can easily be added, removed or updated over the course of the user session. This keeps the session variables organized in one place, instead of across fields or variables.
Working with Arrays
Building on the FileMaker default functions, iCore has released a set of 30 custom functions as a FileMaker Add-On that add new capabilities to developers working with JSON Arrays. These custom functions extend the default set of functions from FileMaker described above. The complete set can be downloaded here for free. The set includes common javaScript array functions, such as concat, findIndex, filter, forEach, pop, push, slice, splice, and many more.
