A script trigger in a FileMaker solution is set to run a script when a specified event occurs. The first event for any file is when the file opens, or more specifically, when the first window opens. It is common that a script will run when a file is opened.
There are three main categories of script triggers – file, layout and object. You can check out all the triggers and links to detail of how they work in the online FileMaker Pro Help.
File triggers include those for opening and closing windows – the first, the last and any windows. The most useful of these are OnFirstWindowOpen and OnLastWindowClose. These can run various housekeeping tasks when a file opens or closes.
File triggers can be set through File > File Options…
Layout triggers deal with loading layouts and records. For example, exiting or entering a layout can trigger a script. Some developers have used these triggers to build a Back/Forward navigation system building (amongst other things) a list of layouts for navigation.
Layout triggers can be set in Layout mode through Layouts > Layout Setup…
Object triggers deal with actions on layout objects such as fields and panels. In a user interface context, object triggers can be used to enforce data entry rules or to validate data. The OnObjectValidate trigger activates before fields are validated and saved. This provides more options for providing feedback to the user than field option validation. However, it should be understood that triggers are not always activated – they are dependent on the context of the data entry.
Object triggers can be set in Layout mode by selecting the object and then Format > Set Script Triggers…
Other script triggers
Although not listed as script triggers in the FileMaker Help, other events can trigger a script to run. These include:
- clicking a button (the first ever trigger!)
- Perform Script and Perform Script on Server script steps
- Install OnTimer Script script step
Pre-event vs post-event triggers
Pre-event script triggers run the script before the event is processed by the database engine; post-event script triggers run the script after the event is processed.
Why is this important? It determines whether the trigger event can be cancelled. If the event has already been processed before the script runs, the event cannot be cancelled.
Pre-event triggers are powerful in that the script can be configured to cancel the event. This is done by exiting the script with a false result (0 or False).
An example of this is when you want to allow a maximum number of characters in a field.
A Tax File Number (TFN) in Australia is nine digits. So we might write a script to check the number of characters in the field in a script that runs OnObjectKeystroke (a pre-event trigger).
Consider the following script:
If [ Length ( data::TFN ) >= 9 ] Exit Script [ Result: False ] Else #do nothing End If
Note that the script will run before the event (typing a new character) occurs. This means that we need to check the length of the field before the addition of the new character. If there were 5 characters in the field, the script would allow another character – the If statement returns false and the script exits doing nothing. If there were 9 characters in the field, the If statement would return true and the script would exit with a result of False. This will cancel the triggering event so the new character would not appear.
This script appears to do a good job. It certainly stops the 10th character being entered. However, it has a couple of problems.
- One problem is that if the field contains 9 characters, all keystrokes in the field are cancelled. This includes Delete (if you need to make any corrections) and Tab (if you want to exit to the next field). A better script will account for all possible valid keystrokes and allow them.
- Another problem is that the user can still enter invalid data in other ways than by simple character keystrokes. For example, a ten digit number can be pasted into the field. Other triggers or methods may be needed to watch for this.
The takeaway here is that your script trigger behaviours should be well tested to ensure that they behave in reasonable ways.
When working with a file with script triggers enabled, it can be difficult to troubleshoot exactly what is happening and when. This is where the Script Debugger provided in FileMaker Pro Advanced is very useful. With the script debugger open, you can navigate around a solution and see which events trigger which scripts, and even cancel them if needed. This is particularly so when first opening a file – open the Script Debugger then open the file to catch the OnFirstWindowOpen script.
The Tools in FileMaker Pro Advanced allow the developer to temporarily disable script triggers. Do this by choosing Tools > Debugging Controls > Disable Script Triggers.
Script triggers are very powerful but with power comes great responsibility. Make sure you properly test all script triggers for expected behaviour. You have been warned!