A parameter is text that is passed to a FileMaker script when it runs. The text is often used to make decisions during the script. Using a script parameter allows the developer to construct a script that can run differently according to the conditions.

Running a script

A script can be called to run in a number of ways:

• user clicks a button
• event occurs such as switching layouts
• user selects a script in the Scripts menu
• script runs the Perform Script or Perform Script on Server step
• FileMaker Server schedule runs a script
• user selects a custom menu item defined to run a script
• timer running in a window runs a script

Passing a parameter

In most cases, when a script is called a parameter can be passed to the script. In the simple case of defining a button, when the action is to Perform Script, the (optional) script parameter can be defined in the lower part of the Specify Script dialog:

The Edit… button provides access to the FileMaker calculation engine such that the script parameter can be a calculated result determined when the script runs.

Parameter is text

It is important to understand that a script parameter is passed as text. This can have important implications when the data is expected to be used as number or date. It also means that raw container field contents cannot be passed as parameters – they must first be converted to text (e.g. using Base64 encoding).

Accessing a parameter

A parameter passed to a script is available only within that script. It can be accessed at any time using the Get ( ScriptParameter ) function.

For convenience, a developer may choose to extract the parameter into a variable (or multiple variables) at the start of the script. This can provide a readable name for the parameter making code more self-documenting.

For example, if the script parameter being passed is the name of a customer and that data will be used to name a new card window, the following code might be used:

New Window [ Style: Card; Name: Get(ScriptParameter);                   Using layout: “Contact Details”]

Without knowing the contents of the script parameter, it is impossible to know how the window will be named. Compare that with the following:

Set Variable [ $customerName; Value: Get(ScriptParameter)]
New Window [ Style: Card; Name: $customerName; 
             Using layout: “Contact Details”]

It is now clear that the new card window will be given the customer name.

Conditional scripting using a parameter

A parameter may be used to control how a script runs.

One example is when the parameter is queried in an If script step. The parameter may contain contextual data such as where the script is being run. Depending on the layout, the script may run different script steps.

For example, the parameter could be set with the Get(LayoutTableName) function. This returns the table occurrence name of the current layout.

If the table occurrences underlying each layout are named using a naming convention where the first word is the name of the table, this can be used to run different script steps based on the layout where the script was called.

Set Variable [ $table; 
   Value:LeftWords(Get(ScriptParameter) ; 1 )]
If [ $table = "person" ]
   #do these steps
Else If [ $table = "invoice" ] 
   #do these steps
Else If [ $table = "product" ] 
   #do these steps
End If

Passing multiple parameters

In most cases, it is sufficient to pass one piece of data as a parameter. To pass more than one parameter, you need to think about how to bundle up multiple pieces of data and then unpack them in the script.

A common method is to use the List function to create a return separated list of values. Knowing the number and order of the values, you can effectively unpack the data into different variables in the script.

For example, if a person’s first name, last name and student number is passed using the List function:

List ( person::First; person::Last; person::StudentNo )

This could be unpacked in the script thus:

Set Variable [ $p; Value: Get ( ScriptParameter ) ]
Set Variable [ $first; Value: GetValue ( $p; 1 ) ]
Set Variable [ $last; Value: GetValue ( $p; 2 ) ]
Set Variable [ $studentno; Value: GetValue ( $p; 3 ) ]

It is also possible to adopt a more structured approach and pass data in a parameter as name/value pairs. This is easily done in FileMaker Pro 16 using JSON format and extracting the data from the parameter using the new JSON functions.