FileMaker 14 Script Triggers

Script triggers are a straightforward concept, but there’s a lot of detail to learn for each one. This post will break this detail down in several different ways with the intent to organize the information so that it can be learned and absorbed more easily and effectively.

Update: Script Trigger Sequence illustration updated to show “View Change” as a post sequence.

A Historical View

FileMaker 7 and earlier

• Total number of triggers: 2 (OnFileOpen and OnFileClose)
• These were renamed to OnFirstWindowOpen and OnLastWindowClose in FileMaker 12

FileMaker 10

• Total number of triggers: 15
• Thirteen new triggers
• One of the new triggers is the “Install OnTimer Script” script step
• OnLayoutLoad is renamed to OnLayoutEnter in FileMaker 11
• FileMaker’s help page

FileMaker 11

• Total number of triggers: 18
• Three new triggers: OnObjectValidate, OnViewChange, OnLayoutExit
• OnLayoutLoad is renamed to OnLayoutEnter
• FileMaker’s help page

FileMaker 12

• Total number of triggers: 21
• Three new triggers: OnWindowOpen, OnTabSwitch, and OnWindowClose
• OnTabSwitch is renamed to OnPanelSwitch in FileMaker 13
• OnFileOpen is renamed to OnFirstWindowOpen, and OnFileClose is renamed to OnLastWindowClose
• FileMaker’s help page

FileMaker 13

• Total number of triggers: 23
• Two new triggers: OnLayoutSizeChange and OnGestureTap
• OnTabSwitch is renamed to OnPanelSwitch
• FileMaker’s help page

FileMaker 14

• Total number of triggers: 26
• Three new triggers: OnObjectAVPlayerChange, OnFileAVPlayerChange, OnExternalCommandReceived
• FileMaker’s help page

Trigger Categories

Script triggers are set up at one of four levels: file, window, layout, and object.

The 5 file-level triggers are:

• OnFirstWindowOpen, OnWindowOpen
• OnWindowClose, OnLastWindowClose
• OnFileAVPlayerChange

The sole window-level trigger is:

• OnTimer

The 12 layout-level triggers are:

• OnLayoutEnter, OnLayoutExit
• OnModeEnter, OnModeExit
• OnViewChange
• OnRecordLoad, OnRecordCommit, OnRecordRevert
• OnLayoutSizeChange
• OnLayoutKeystroke
• OnGestureTap
• OnExternalCommandReceived

The 8 object-level triggers are:

• OnObjectEnter, OnObjectExit
• OnObjectKeystroke
• OnObjectModify
• OnObjectSave
• OnObjectValidate
• OnPanelSwitch
• OnObjectAVPlayerChange

The OnTimer trigger is set up differently from the other script triggers; it is installed (and removed) as a script step. All other triggers are set up in settings dialog windows. The file-level triggers are configured in the File Options dialog. The layout and object triggers are set up while in Layout mode, as an attribute of the layout or object that they belong to.

Script Trigger Sequence

When multiple events are triggered by a single action, they are processed in the order shown in the diagram below:

There is a method to the order in which triggers fire:

1. First there is the entering into the interface elements, which happens in the following order: window → layout → mode → view → record → object.
2. Next is the interaction with the objects that have been laid out; e.g. a user types something, a script changes some data, etc. Each of these script triggers deals with objects.
   • There are some exceptions though: OnLayoutSizeChange, OnLayoutKeystroke, OnGestureTap, and OnExternalCommandReceived are layout-level triggers, and OnFileAVPlayerChange is a file-level trigger.
3. The action is completed with the leaving of the interface elements, which happens in reverse order: object → record → view → mode → layout → window.

There may be times when it appears that the order is different than shown above. For example, if we are in a text field that is configured with an OnObjectExit trigger, and then we click on a tab control object that is configured with an OnPanelSwitch trigger, the OnPanelSwitch will fire after the OnObjectExit, but this is because the previously active object (the text field) gets to complete its sequence of object-level triggers (which in this case includes OnObjectExit) before the newly active object (the tab control) gets to call its set of object-level triggers (which in this case includes OnPanelSwitch).

The sequence shown in the diagram is important, but not in all cases. For example, OnGestureTap is shown after OnLayoutKeystroke instead of, for example, OnLayoutSizeChange, but this particular order does not matter, because you’ll never be in a situation where both of these events can fire.

Canceling The Triggering Event (Pre or Post Events)

Some script triggers are processed before the triggering event is processed, and others are processed after it. For example, if you click into a field, FileMaker will enter the field, and then the OnObjectEnter trigger will activate. This is referred to as a post-event trigger. However, if you click out of a field, the OnObjectExit trigger will activate before FileMaker exits the field, since it is a pre-event trigger.

It’s important to know which triggers are pre-event, because FileMaker allows us to cancel the triggering event for these triggers by exiting the script with False. In the example above, if we exit the script that is called by the OnObjectExit trigger with Exit [False], the user will not be able to exit the field, which can be useful if for example an invalid value was entered.

There is (of course) one exception. The OnObjectSave trigger is a post-event trigger, and FileMaker does allow us to cancel its triggering event. However, if we do this, the object’s value will still get saved (even though the event will be canceled). An example may help to explain this better: Suppose we modify a value in a field that’s configured with the OnObjectSave trigger. We then click out of the field. The trigger fires and exits false, which prevents the leaving of the field. The modification we made to the field value will still be saved though.

New in FileMaker 14

FileMaker 14 introduces three new script triggers:

• OnObjectAVPlayerChange
• OnFileAVPlayerChange
• OnExternalCommandReceived

These triggers are iOS-only, and their function is to provide developers with the ability to control what happens when audio, video, and image media is played, paused or stopped using the iOS A/V Player.

OnObjectAVPlayerChange

The OnObjectAVPlayerChange trigger is assigned to a container field. It fires when an image, audio, or video stored in a container field is played, and when the playback is paused or stopped. It will fire regardless of whether the presentation is full screen or embedded in the container field, and regardless of the media change event (play, pause, stop) was initiated by the user or by a script.

The media playback can be scripted using these three new script steps:

• AVPlayer Play – plays audio, video, or images from a URL or a container field (whether present on the layout or not)
• AVPlayer Set Playback State – pauses, resumes, or stops playing a media file that is playing or is paused
• AVPlayer Set Options – changes the setting (for example, full screen vs embedded) for a media file that is playing or is paused

Developers can determine the playback state using this new function:

• GetAVPlayerAttribute ( attributeName ) – behaves similarly to the GetContainerAttribute ( sourceField ; attributeName ) function introduced in FileMaker 13

Media playback happens either embedded in the container object or full screen. When audio or video media is playing, users can pinch apart to show the player in full screen and pinch together to exit full screen. If the playback is embedded, users can pinch together to stop the player, and they can double tap to toggle between play and pause.

OnFileAVPlayerChange

The OnFileAVPlayerChange trigger is assigned to a file. Using the new script steps listed above, users can script the playback of media stored in a container field or streamed from a URL without having that field or a web viewer shown on the current layout. This trigger will fire when the script step plays, pauses, or stops the media, or when the media stops on its own because the end of the audio or video was reached.

Note: The new script steps and the new function mentioned above (in the OnObjectAVPlayerChange section) are equally relevant to the OnFileAVPlayerChange script trigger.

OnExternalCommandReceived

The OnExternalCommandReceived trigger is assigned to a layout. It fires when a user presses external AV-related controls to activate one of the following commands:

• Play, pause, stop
• Toggle play/pause
• Play next/previous
• Seek (begin/end seeking forward/backward)

Developers can use the new Get ( TriggerExternalEvent ) function to find what external command was pressed.

Examples of external controls include:

• EarPod buttons
• External bluetooth keyboard media control keys
• Controls on the iOS lock screen
• Controls on the iOS control panel (accessed by swiping up from the bottom of the screen)

Note that this trigger will fire even when the AV player isn’t active. For example, if you tap on the play button in the control panel, this trigger will activate, even if you weren’t playing any audio or video at the moment.

OnGestureTap

In addition to adding three new script triggers, FileMaker 14 also changed how OnGestureTap behaves. This script trigger was iOS-only in FileMaker 13 but is now also supported on Windows 8 touch devices. The gestures that are supported are:

• Single-tap with one, two, or three fingers (iOS)
• Double-tap with one finger (iOS)
• Single-tap with two fingers (Windows 8)

FileMaker 14 also supports pinch zooming and other gestures on other devices. For example on a MacBook, you can zoom in or out by pinching the trackpad. However, these gestures do not activate the OnGestureTap trigger.

Reference PDF and Playground Demo File

That’s it for this overview. For a more complete reference, take a look at the PDF document we’ve put together, and also please check out the demo file which you can use to see for yourself how script triggers work. The demo file has a layout that has every type of field and object on it. And the file, layout, and each object have every possible script trigger enabled. Make sure to access the file using all three clients (Pro, WebDirect, and Go) to learn how script triggers work on each one.

Demo File

A note on testing the OnFileAVPlayerChange in the demo file:
Whenever a trigger fires in the demo file, a dialog window is shown. If a video is being played in full screen, the dialog window will stop the playback. So to test out the OnFileAVPlayerChange trigger, first tap on the “Toggle” button to disable showing of trigger messages, and then tap on the “Play From Field” button. Try pausing, resuming, and stopping the video. Then tap on the “History” button to see how and when the OnFileAVPlayerChange trigger fired.

Cheat Sheet

FileMaker 15 and Beyond

FileMaker 15 and 16 did not introduce any new script triggers. However, FileMaker 16 does bring one change worth mentioning: the new “Configure Region Monitor Script” step can be used to trigger a script to run when an iOS device enters or exits a region. In this way, it is reminiscent of the “Install OnTimer Script” step, which also causes a script to run based on some event.

— Mislav Kos and Wim Decorte