FileMaker scripts can be called in various ways – user clicks a button, event triggers a script, script calls another script, etc. Most times* when a script is called, the developer can provide a script parameter to pass to the script. This parameter may be retrieved at any time during the course of the script using Get(ScriptParameter).
* Developer Quiz Question:
When is it NOT possible to use a script parameter when calling a script? (see answer below)
Naming a parameter
Many times, a script parameter is used to control which part of a script will run. For example, a single script may handle all parts of a process such as open, save and cancel. So the script is called with one of these strings as the parameter.
The general structure of the script is:
If [ Get (ScriptParameter) = "open" ] #do something here Else If [ Get (ScriptParameter) = "save" ] #do something here Else If [ Get (ScriptParameter) = "cancel" ] #do something here Else Show Custom Dialog [ "Error" ; "Invalid or missing parameter" ] End If
This creates a minor readability issue – each If statement is not immediately intuitive as the reader needs to ask “what is the script parameter?”.
A simple solution is to ‘unpack’ your script parameter into a variable that is named to make sense of the usage. So we can add a script step at the start of the script. See how the rest of the script is now more readable?
Set Variable [ $action; value: Get (ScriptParameter) ] If [ $action = "open" ] #do something here Else If [ $action = "save" ] #do something here Else If [ $action = "cancel" ] #do something here Else Show Custom Dialog [ "Error" ; "Invalid or missing parameter" ] End If
What about more than one parameter?
One of the limitations of a script parameter is that there is only one text string. Once you start using script parameters, you quickly see the need for multiple parameters. Over the years, FileMaker developers have used many different methods to be able to pass multiple pieces of data in a single parameter.
For example, three pieces of data may be passed with standard separators such as:
David | Head | david@ulearnit.com.au
When the data is being passed from fields, it is useful to send it as a List:
List ( first_name ; last_name ; email )
This single parameter can then be parsed into three separate strings. When doing this, it is most useful to parse the values directly into variables for later use. This is easily done with the List example:
Set Variable [ $first ; GetValue ( Get (ScriptParameter); 1 ) ] Set Variable [ $last ; GetValue ( Get (ScriptParameter); 2 ) ] Set Variable [ $email ; GetValue ( Get (ScriptParameter); 3 ) ]
One of the advantages (and disadvantages) of the List function is that, if a value is empty, there will be no value returned – not even an empty value.
In the above example, if the last_name field happened to be empty, the script parameter would consist of just two values. This would mean that the variable $last would contain the email address and the variable $email would be empty (and therefore not exist).
A common method of passing multiple parameters is to create JSON code. This is much easier now that there are native JSON functions in FileMaker. The script parameter is set with:
JSONSetElement ( "" ;
["first"; person::first_name; JSONstring ];
["last"; person::last_name; JSONstring ];
["email"; person::email; JSONstring ]
)
This creates a string that looks like:
{"email":"david@ulearnit.com.au","first":"David","last":"Head"}
And this can be parsed into variables like this:
Set Variable [ $json ; Get (ScriptParameter) ] Set Variable [ $first ; JSONGetElement ( $json; "first" ) ] Set Variable [ $last ; JSONGetElement ( $json; "last" ) ] Set Variable [ $email ; JSONGetElement ( $json; "email" ) ]
Again, you end up with named variables containing each piece of data. If it happens that some data does not exist, the variables will still be set correctly.
See Also: Get ( ScriptResult)
These techniques are also applicable when returning data to a calling script via the Exit Script step. This data is accessible via the Get ( ScriptResult ) function.
Conclusions
Once you start using script parameters, you will want to adopt a standard method for passing and handling data from Get ( ScriptParameter ). Variables are your friend for readability and re-use.
Quiz Answer:
When is it NOT possible to use a script parameter when calling a script?
- When choosing a script from the Scripts menu (or run from the Script Workspace)
- When using any File script trigger (such as OnFirstWindowOpen)
One Response
Now to extend it further, you can create custom functions to pass your JSON formatted script parameter into that turns them all into variables with the one function call. A good introduction into the concept of Custom Functions.