using script triggers in filemaker pro -...

Using Script Triggers in

FileMaker Pro

Using Script Triggers in FileMaker Pro of 42

Table of Contents

About This Technical Brief ............................................................................4 What is a Script Trigger? ..............................................................................4 What Script Triggers Are Supported by FileMaker Pro?.................................4 Overview of Script Triggers ..........................................................................5

Only Direct Operations Trigger Scripts.............................................................5 Categories of Script Triggers..........................................................................6 Pre-event and Post-event Script Triggers.........................................................6 Script Trigger Support on the Web..................................................................7 Functionality Details .....................................................................................7

Defining a Script Trigger...............................................................................8 Attaching a Layout Object Script Trigger..........................................................8 Defining a Layout Script Trigger ................................................................... 10 Defining a Timer Specific Script Trigger ......................................................... 11 Defining a File Specific Script Trigger ............................................................ 12 Additional Information About Attaching Script Triggers .................................... 13

Layout Object Specific Script Triggers in Detail ..........................................15 OnObjectEnter Script Trigger ....................................................................... 15 OnObjectKeystroke Script Trigger................................................................. 16 OnObjectModify Script Trigger...................................................................... 17 OnObjectSave Script Trigger........................................................................ 18 OnObjectExit Script Trigger ......................................................................... 19

Layout Specific Script Triggers in Detail .....................................................20 OnRecordLoad Script Trigger ....................................................................... 20 OnRecordCommit Script Trigger ................................................................... 20 OnRecordRevert Script Trigger ..................................................................... 21 OnLayoutKeystroke Script Trigger ................................................................ 21 OnLayoutLoad Script Trigger........................................................................ 22 OnModeEnter Script Trigger ......................................................................... 22 OnModeExit Script Trigger ........................................................................... 23

Timer Specific Script Triggers in Detail .......................................................23 “Install OnTimer Script” Script Trigger........................................................... 23

File Specific Script Triggers in Detail ..........................................................24 OnFirstWindowOpen Script Trigger ............................................................... 25 OnLastWindowClose Script Trigger................................................................ 25

New Calculation Functions to Support Script Triggers ................................25 Get (TriggerModifierKeys)............................................................................ 27 Get (TriggerKeystroke) ............................................................................... 27 Code () ..................................................................................................... 28 Char () ..................................................................................................... 29

Real World Example of Script Trigger Usage ...............................................30 Simplifying Navigation ................................................................................ 30 Automating Navigation................................................................................ 30 Filtering Keystrokes .................................................................................... 30


Committing Records from Idle Users ............................................................. 31 Preparing a Found Set of Records After A Layout Switch .................................. 31 Execute A Find Request After Data Entry ....................................................... 31 Sort a Layout Automatically ......................................................................... 31 Taking Action Based On User Interaction or Choice ......................................... 31 Switch Layouts Based On A Field Value ......................................................... 32 Dynamically Alter the Look and Feel of a Solution ........................................... 32

Troubleshooting Script Triggers..................................................................32 Operations That Will Not Trigger Scripts ........................................................ 32 Interaction with popup menus, list, calendar, and auto-complete ...................... 34 Using Script Triggers with Summary and Calculation Fields .............................. 34 Timing of multiple script triggers .................................................................. 35 Target Window Handling ............................................................................. 35 Debugging Triggered Scripts ........................................................................ 36

Script Triggers are not suitable for all things..............................................37 Changes to the Database Design Report in FileMaker Pro Advanced ...........38 Backward Compatibility with Previous Versions of FileMaker Pro ...............39 In Closing – A Word of Caution ...................................................................40 About The Author .......................................................................................42


About This Technical Brief This technical brief is designed to help the experienced FileMaker Pro developer obtain a better understanding of the new script trigger feature introduced in FileMaker Pro 10 and FileMaker Pro 10 Advanced. After reading this document, you will have a better understanding of the following key aspects of script triggers:

• What is a script trigger • What are the supported types of script triggers • How to define a script trigger • The usage details of the supported script triggers • Examples of how script triggers can be used in your solutions • Usages of script triggers • Troubleshooting the usage and behaviors of script triggers

For additional technical information on the use of script triggers, please refer to the electronic and online help that ship with FileMaker Pro and FileMaker Pro Advanced. What is a Script Trigger? Manage Scripts (formally known as ScriptMaker) has always been one of the most powerful features of FileMaker Pro. Over the years, the functionality of scripts has grown and evolved while retaining their ease of creation and use. As powerful as scripts have been in previous versions of FileMaker Pro, they had a limitation in that they needed to be launched or “triggered” by way of a manual process. This manual process usually took the form of clicking a button on a layout or a choosing an option from a menu. In either case, it required someone to do something in order to tell FileMaker Pro to run a particular script. All of this has changed with the introduction of FileMaker Pro 10 and the support for script triggers. Simply put, a script trigger is a mechanism that causes a user-defined script to execute when a supported event occurs. For example, a script trigger could be used in Table View to aid a user of your solution in navigating from the end of one row (record) to the beginning of the next row (record) when tabbing through records. For experienced users, you know there are some actions that involve creative workarounds and extra development time to accomplish. In most cases, the use of script triggers will make many of these workarounds unnecessary or the need to use workarounds has dramatically decreased. What Script Triggers Are Supported by FileMaker Pro? FileMaker Pro supports twelve different script triggers and one “on timer” script step for a total of thirteen different triggers. If you take into consideration that FileMaker Pro has supported running scripts that execute when the first window of a file is opened or the last window of a file is closed, the savvy FileMaker Pro user developer now has fifteen script triggers to use when creating their solutions. Here is a complete list of the script triggers that are supported in FileMaker Pro 10.


1. OnObjectEnter 9. OnLayoutKeystroke 2. OnObjectKeystroke 10. OnLayoutLoad 3. OnObjectModify 11. OnModeEnter 4. OnObjectSave 12. OnModeExit 5. OnObjectExit 13. OnFirstWindowOpen 6. OnRecordLoad 14. OnLastWindowClose 7. OnRecordCommit 15. Install OnTimer Script 8. OnRecordRevert

To add additional functionality and flexibility to the use of script triggers, FileMaker Pro includes four new, supplementary calculation functions. These include two new Get functions and two new Text functions. The two new Get () functions are:

Get (TriggerKeystroke) Get (TriggerModifierKeys)

The two new Text functions are:

Char (Number) Code (Text)

The rest of this technical brief is dedicated to the discussion and the description of the script triggers listed above and calculation functions that support them. Overview of Script Triggers

Before you begin to use script triggers in your own solutions, it is important to understand the types of script triggers that are available to you and how they fundamentally work. While each of the supported fifteen script triggers in FileMaker Pro perform different actions, many of them share similar characteristics. The following section goes over many of these shared characteristics and behaviors as well as pointing out some of the differences as well. At the end of this section, you will have a high-level understanding of the behaviors of script triggers in FileMaker Pro. Only Direct Operations Trigger Scripts If you take only one thing away from this overview section, know that ALL script triggers except the file related “OnFirstWindowOpen” and “OnLastWindowClose” script triggers and the “Install OnTimer” script trigger execute based on changes or actions performed on layouts and layout objects directly. Scripts will execute as a result of user interaction or if a script performs the same action. However, triggered scripts WILL NOT execute based on changes made to the underlying data.

The creation and usage of script triggers are supported in both FileMaker Pro and FileMaker Pro Advanced.


More about when a triggered script will and will not execute can be found in the “Troubleshooting Script Triggers” section of this technical brief. Categories of Script Triggers A script trigger can be configured to execute a script when a user interacts with a specific layout, when a user enters, modifies, or exits an object on a layout, when a file is opened or closed, or after a specific period of time has elapsed. There are four different categories of script triggers supported in FileMaker Pro.

• Object specific script triggers • Layout specific script triggers • File specific script triggers • Timer specific script triggers

Pre-event and Post-event Script Triggers All the script triggers supported in FileMaker Pro fall into one of two event categories – those that execute scripts after an event occurs and those that execute scripts before an event occurs Script triggers that are defined as “post” event triggers will execute the defined script after the operation that caused the event has completed successfully. For example, if there is a OnObjectEnter script trigger set to run a script when a field is entered and the user issues a NEW RECORD command that causes that field to be entered, the script will not run until after the new record operation is finished. Script triggers defined as “pre” event triggers will execute the defined script before the event is fully processed. For example, if an OnObjectExit script trigger is set to run a script when a field is exited, the script trigger will execute the script before the field is actually exited. Pre-event triggered scripts in FileMaker Pro can cancel the original event based on whether the script that was triggered returns “true” or “false.” The result of the

Script triggers have options that allow you to affect their resulting behavior. For example, most script triggers allow you to configure whether a script is executed in Browse, Find, and/or Preview modes. The default settings for most script triggers is to run in Browse mode only. The following script triggers do not have user selectable options for the modes they run in.

• OnFirstWindowOpen • OnLastWindowClose • Install OnTimer Script


triggered script determines whether the event should continue to be processed normally or whether it should be cancelled and ignored.

TRUE: The event that triggered the script proceeds FALSE: The event that triggered the script has been cancelled.

The OnObjectSave script trigger is fired after the object data is saved BUT before the object is exited; so returning “false” would cancel the original event and leave the object active.

Generally, only pre-exit script triggers can cancel an event. The following is a list of script triggers that can cancel the original event based on a result of either “true” or “false” from the triggered script.

• OnObjectKeystroke • OnObjectSave • OnObjectExit • OnRecordCommit • OnRecordRevert • OnLayoutKeystroke • OnModeExit • OnLastWindowClose

See the section “Description of Script Triggers” for a more in depth description of what the results of each script trigger means. Script Trigger Support on the Web When designing your FileMaker Pro solutions for the web, it is important to keep in mind the limitations associated with script triggers. Script triggers do not work in Instant Web Publishing (IWP) and Custom Web Publishing (CWP) when events are triggered by user interaction. However, if a script (non-user interaction) is executed and it would cause a script trigger to execute a script, then the triggered script will execute as expected. For example, if an IWP user tabs into a field that has an OnObjectEnter script trigger attached to it, the trigger will not execute the associated script. However, if a script step causes focus to move into that field then the OnObjectEnter script trigger attached to the field will execute the script as expected. Files that have “on open” and “on close” scripts configured to execute in FILE OPTIONS will function in a web solution as they always have. Functionality Details The following table summarizes the functionality of all the script triggers that are available in FileMaker Pro.


TRIGGER PRE VERUS POST WEB COMPATIBLE

OnObjectEnter Post Only if triggered from a script OnObjectExit Pre Only if triggered from a script OnObjectModify Post Only if triggered from a script OnObjectKeystroke Pre Only if triggered from a script OnObjectSave Pre Only if triggered from a script OnLayoutLoad Post Only if triggered from a script OnLayoutKeystroke Pre Only if triggered from a script OnModeEnter Post Only if triggered from a script OnModeExit Pre Only if triggered from a script OnRecordLoad Post Only if triggered from a script OnRecordCommit Pre Only if triggered from a script OnRecordRevert Pre Only if triggered from a script OnFirstWindowOpen Post Yes OnLastWindowClose Pre Yes Install OnTimer Script

N/A No

Defining a Script Trigger There are several ways you can attach a script trigger in FileMaker Pro. The method you use depends on the type of script trigger you are attempting to attach. The following section outlines how to attach the different types of script triggers that are supported in FileMaker Pro. Attaching a Layout Object Script Trigger A script can be set to execute when a specific action is performed on an object on a layout. There are five layout object script triggers supported in FileMaker Pro. Those script triggers are:

• OnObjectEnter • OnObjectKeystroke • OnObjectModify • OnObjectSave • OnObjectExit

Accessing the dialog box where you setup a script trigger for a layout object is done in one of three ways when the desired layout object is selected in Layout mode:

1. By clicking FORMAT > SET SCRIPT TRIGGERS 2. By “right-clicking” the object and choosing SET SCRIPT TRIGGERS from the

contextual menu. 3. By double-clicking the object while holding down the Command key (Mac) or

the Control key (Windows) The following dialog box is displayed using any of the methods described above:


The object script trigger dialog box displays the available script triggers for the selected layout object as well as a button to select the script you want to execute and some checkboxes to enable or disable whether the script trigger will execute the script in Browse and/or Find modes. Defining a script trigger on a layout object is as simple as choosing the event you want to trigger and assigning a script to perform when that event occurs. A layout object can have more than one script trigger attached to it. For example, a script trigger could be defined to execute a script when someone enters a field as well as when they exit the same field. Visually Identifying A Layout Object Script Trigger FileMaker Pro can display a tiny badge on layout objects that have script triggers assigned to them. In the example below, notice that “FieldB” has a red asterisk in the lower right hand corner of the field indicating that it has at least one script trigger attached to it.

This visual feature can be toggled on and off by clicking VIEW > SHOW > SCRIPT TRIGGERS and are displayed when viewing the layout / layout objects in Layout mode.


Defining a Layout Script Trigger A script can be set to execute when an action is performed on a layout. There are seven layout script triggers supported in FileMaker Pro. Those script triggers are:

• OnLayoutLoad • OnRecordCommit • OnRecordRevert • OnLayoutKeystroke • OnLayoutLoad • OnModeEnter • OnModeExit

Accessing the dialog where you define a script trigger for a layout can be reached in one of three ways when in Layout mode…

1. By clicking the Layout Setup button in the layout bar 2. By clicking LAYOUTS > LAYOUT SETUP 3. By right-clicking a layout and choosing LAYOUT SETUP from the contextual

menu. All three methods described above will open the LAYOUT SETUP dialog box. From here, clicking the SCRIPT TRIGGERS tab will display the following dialog box…

The layout script trigger dialog box displays the available script triggers for the layout as well as a button to select the script you want to execute and some checkboxes to enable or disable whether the trigger will execute the script in Browse, Find and/or Preview modes.


Defining a script trigger on a layout is as simple as choosing the trigger you want and assigning a script to perform when that event occurs.

Script triggers set for one layout apply to that layout only. To include a script trigger on other layouts you will need to define the script trigger(s) on each desired layout individually.

A layout can have any number of script triggers enabled. For example, a script trigger could be defined to perform a script when someone visits a layout, enters a mode, or exits a mode. Defining a Timer Specific Script Trigger A new script step has been introduced in FileMaker Pro 10 called “Install OnTimer Script.” Simply put, it allows the user or developer to run a specific script after a given interval of time (measured in seconds) on a specific window. A script using the OnTimer script step attaches to the active window for the life of the window or until a subsequent Install OnTimer script is executed on that window. ) The “Install OnTimer Script” step is located in the “Control” section of the list of available script steps in the Manage Scripts dialog box. This script supports the options for specifying the script you would like to execute as well as the number of seconds to wait before executing the script each time. This script step is selected like any other script step in the Manage Scripts dialog box.

Unlike object script triggers, the following Layout script triggers support being run from Preview mode:

• OnLayoutKeystroke • OnLayoutLoad • OnModeEnter • OnModeExit

“What happens if I duplicate a layout that has script triggers associated with it?” A duplicated layout inherits any script triggers that were defined on the original layout. Keep this behavior in mind when you are designing your solutions.


Defining a File Specific Script Trigger File specific script triggers should be familiar to most FileMaker Pro users and developers. These types of script triggers have been in the FileMaker Pro application for several years. There are two types of file specific script triggers available in FileMaker Pro.

1. OnFirstWindowOpen 2. OnLastWindowClose

Both of these script triggers are configured on a file-by-file basis using the FILE OPTIONS dialog box. The FILE OPTIONS dialog box is available by clicking FILE > FILE OPTIONS and clicking the OPEN/CLOSE tab. The FILE OPTIONS dialog box is shown below:


Here you can specify a script to run when a file is opened or, more specifically, when the first window of a file is displayed on the screen. You can also specify a script to run when a file is closed or, more specifically, when the last window of a file is closed. Additional Information About Attaching Script Triggers Keep in mind the following information when using script triggers in FileMaker Pro.

• If you make a change to an object on one layout, that change will not activate a script trigger on the same object that is on a different layout or layouts.

• Script triggers will behave the same whether they are triggered in form view, list view, or table view.

• A script needs to exist before you can attach it to a trigger. The Set Script Triggers dialog box does not allow you to define a script on the

It is possible to alter the behavior of script triggers that are run in form view, list view, or table view so that the script has unique behaviors for each view. Scripts can be written to use the Get(WindowMode) and Get(LayoutViewState) functions to determine the current mode and view and make decisions on how a script should behave based on that information.


fly. You will first need to define the script in the Manage Scripts window before you can use it as part of a script trigger.

• Scripts that are invoked via Apple Events or calculation function plug-ins while another script is running are queued to run after all running scripts are finished. Because of this behavior, there should not be any conflicts between FileMaker Pro script triggers and Apple Event scripts.

• It is possible to assign script triggers to more than one layout object at a time. Simply highlight all the desired layout objects first and define the script trigger(s) as you normally would. If you select multiple layout objects that already have script triggers attached to them and the script triggers are different, the Set Script Triggers dialog box will display a minus sign (“-“) to indicate the trigger has not been set on some of the objects.

The example above shows two layout objects (fields) that have been highlighted. One has an OnObjectEnter script trigger associated with it and the other has an OnObjectKeystroke script trigger associated with it. Note

Want to disable a script trigger without removing or deleting it completely from your solution? Simply clear the mode checkboxes. This method is available for layout script triggers and layout object script triggers. To disable an “Install OnTimer Script” step, simply highlight the script step and press the DISABLE button when editing the script using FileMaker Pro Advanced.


that they both have minus(-) signs next to them indicating that the trigger is assigned to only some of the selected objects.

Layout Object Specific Script Triggers in Detail The next section of this technical brief will go into more detail about the five (5) supported Layout Object script triggers that are available in FileMaker Pro. OnObjectEnter Script Trigger The OnObjectEnter script trigger runs a script when the layout object becomes the active object. Examples of this include:

• A user tabs to the object or clicks into the object • A command like “New Record” of “Enter Find Mode” is issued that, when

performed, makes a field active • A script step causes an object to be entered. • Moving between the repetitions of a repeating field. • Moving between the portal rows of a portal.

The OnObjectEnter triggered script is a “post”-processing trigger. This means that this trigger will execute a script after the event has been processed. In this case, this trigger will execute the script after the layout object has been “entered.” This trigger can be applied to any object that is allowed to have keyboard focus. This includes objects such as fields, tab controls, buttons, portals, and web viewers. When it comes to fields on a layout, it does not matter how a field is formatted (popup list, radio buttons, checkbox, etc.) as an OnObjectEnter trigger will execute a script regardless. However, if a field is configured not to allow entry in either Browse and/or Find modes, then an OnObjectEnter script trigger would only execute a script if the field is entered via a script step. When it comes to the behavior of Tab Panels and buttons when used with OnObjectEnter script triggers, only tabbing to the Tab Control or button will cause a script to execute. Clicking a tab in a tab panel or clicking a field contained in a tab panel will not cause an OnObjectEnter trigger attached to that tab to execute a script. Similarly, clicking a button does not “enter” the button and therefore an OnObjectEnter trigger attached to that button does not execute a script. When it comes to portals in FileMaker Pro and the usage of an OnObjectEnter script trigger, some additional care needs to be used:

• If an OnObjectEnter trigger is configured for a portal object, then the trigger will execute the script whenever a different row in the portal is made active. It does not matter if the portal row itself is selected or an object within the portal row is made active – the OnObjectEnter trigger will execute the script.

• Clicking on a field in the same row of an active portal will not execute an OnObjectEnter script that is attached to that portal.

• If a field in a portal is configured with an OnObjectEnter trigger and you click in that field, the trigger associated with the portal will execute the script first followed by the triggered script associated with the field within the portal row.


This is because you “entered” the portal first before you “entered” the field in the portal.

• Scrolling a portal is not considered making the portal active and therefore an OnObjectEnter trigger will not execute the script.

Lastly, the default behavior of FileMaker Pro when switching into Find mode is to place the cursor in the first field that is defined in the tab order of the layout. If an OnObjectEnter trigger is configured for this field and it is set to run in Find mode then it will execute the script in this scenario. OnObjectKeystroke Script Trigger The OnObjectKeystroke script trigger will execute a script when the object is the active object and receives one or more characters from the keyboard directly or through an Input Method Editor (IME)

In the case of IME input, multiple characters may be typed and committed into a field all at once. Therefore, the OnObjectKeystroke script trigger will execute when the string of characters is committed to the field and the script trigger will be processed based on the committed string. In all cases not involving an IME, the OnObjectKeystroke script trigger will trigger the script to run when the first keystroke is captured from the keyboard. The OnObjectKeystroke trigger is a “pre”-processing trigger. This means this trigger executes a script before the event has been processed. For example, say you enter an “o” into a field that is configured to use OnObjectKeystroke script trigger. In this case, the OnObjectKeystroke script trigger will execute the script first and process the captured keystroke before anything else occurs. The OnObjectKeystroke trigger can be applied to any object that is allowed to have keyboard focus. This includes objects such as fields (no matter how they are formatted), tab controls, buttons, portals, and web viewers. However, even though FileMaker Pro allows you to attach an OnObjectKeystroke script trigger to a portal and web viewer, they will not execute and will be ignored. This is because a portal does not respond to keys so there is no compelling reason to use a script trigger on a portal. In addition, for technical reasons an OnObjectKeystroke trigger will not work when the active object is a web viewer. It is important to keep in mind the order that keystrokes are processed by your system, the OS, and FileMaker Pro itself. Below is a rundown of the order that keystrokes are processed:

1. The operating system processes certain keys 2. FileMaker Pro processes keyboard shortcut keys

An Input Method Editor is an operating system component or program that allows users to enter characters and symbols not found on their input device. For instance, this allows the user of keyboards to input Chinese, Japanese, Korean and Indic characters.


3. A script triggered by OnObjectKeystroke is processed if there is an active object

4. A script triggered by OnLayoutKeystroke is processed 5. Navigation keys are used for navigation while non-navigational keys are

processed by the active object if there is one. 6. If there is not an active object, then an alert displays for non-navigational

keys. The first of these actions to use the key stops the process. Furthermore, a script executed by the OnObjectKeystroke script trigger can stop further processing of the keystroke by returning a value of “False” There are certain items and actions within FileMaker Pro that will not cause an OnObjectKeystroke script to execute. Below is a list of those actions:

1. Command shortcuts will not trigger an OnObjectKeystroke script to execute. For example, using CMD+- (on the Mac) or CTRL+- (on Windows) to insert the date into a field will not cause the OnObjectKeystroke script to execute. This applies to any custom menu shortcut created using FileMaker Pro Advanced to alter the behavior of command shortcuts.

2. Changing the value of a field by way of the mouse. This includes clicking on a radio button or choosing from a pop up menu or list.

3. Changing the value of a field by way of a script. When using the Field Behavior dialog box it is possible to define the keystroke used to “Go To Next Object” to be either the TAB, RETURN and/or ENTER keys on the keyboard. These keys will also be evaluated by the OnObjectKeystroke script and only if the script returns a value of “true” will they be used for navigation. Additional processing will need to take place in the script if you want to ensure the defined navigation keys actually perform the desired navigation and are processed the way you want them to be. This will involve using the Char () and Code () functions that are discussed later in this paper. Changing a layout object by tabbing to it and then using the arrow keys and the space key will run the OnObjectKeystroke script for that object based on the arrow and space keys but not the tab key that moved focus to the object. The new Get (TriggerKeystroke) function can be used to retrieve the keystrokes that caused an OnObjectKeystroke script trigger to execute the script. The Get (TriggerKeystroke) function can be used to capture, for example, when a carriage return is entered and could pop up a custom dialog to the end-user explaining what is going to happen next. OnObjectModify Script Trigger The OnObjectModify script trigger will execute a script when the value associated with the object changes due to the following actions:

• A user typing • A user clicking, if clicking actually changes the value • Edit operations such as Cut, Paste, and Clear • A script step that changes a field and requires that field to be on the layout,

like in the case of the “Insert Text” script step.


The following actions will not trigger an OnObjectModify script to execute

• A Refresh Window script step is run against data from an external data source • Whenever an auto-enter field is updated • Whenever a summary field or a calculation field is updated (see “Using Script

Triggers with Summary and Calculation Fields” section for more information.) • Contents of a Web Viewer is updated • Dragging and dropping data into a non-active field

The OnObjectModify trigger is a “post”-processing trigger. This means this trigger will execute a script after the event has been processed. It can be applied to any layout object that is allowed to have keyboard focus.

Summary fields and calculation fields that have OnObjectModify triggers attached to them will not execute a script for these types of fields. OnObjectSave Script Trigger The OnObjectSave script trigger will execute a script after the layout object data has been saved to the file. The OnObjectSave trigger is a “pre”-processing trigger. This means this trigger will execute a script before the event has been processed. This trigger can be applied to any object that is allowed to have keyboard focus. This includes objects such as fields, tab controls, buttons, portals, and web viewers. However, OnObjectSave triggers only apply to layout objects that can save their contents. This means that OnObjectSave script triggers will only execute a script when attached to fields. The OnObjectSave trigger only executes a script when data has changed and thus needs to be saved. This is in contrast to the OnObjectExit script trigger that executes a script when a layout object is being exited whether data has changed or not. If the OnObjectSave triggered script cancels the operation (by returning false), then the exit that would have happened next as well as any “bigger” operation that may have caused the save will all be cancelled.

For example, if there is an active field that has been changed and the user of the database chooses SORT from the menu, then the sort operation initially attempts to save and exit from the active field. If the OnObjectSave triggers runs a script that returns “false”, then not only will the exit be cancelled but the sort operation will be cancelled as well.

What if there are two instances of a normal, editable field on a layout but each of these fields has a different OnObjectModify trigger script assigned to it? If a change is made to one of the instances, will it trigger both OnObjectModify scripts to run? The answer is no. Modifying the contents of one instance of a field would indeed affect all instances of that field but only the script on the directly manipulated object is triggered.


If a field has been changed and then it is exited. FileMaker Pro does the following:

1. Performs validation on the field 2. Saves the field locally 3. Refreshes data dependent calculations – including auto-enter calculations

acting on the same field 4. Refreshes related data sets 5. Runs the script associated with the OnObjectSave script trigger

If the OnObjectSave triggered script returns “true” then FileMaker Pro will run the script associated with the OnObjectExit script trigger if it is applicable. If a field is modified by either the script associated with the OnObjectSave script trigger or OnObjectExit script trigger then the whole process starts all over again with the field validation. In this case, the OnObjectSave and OnObjectExit triggered scripts will be called again. If the field is not modified by the scripts and the scripts return a value of “true” (or nothing) then the field is exited and whatever “bigger” operation was invoked will proceed. OnObjectExit Script Trigger The OnObjectExit script trigger triggers a script to execute when the layout object changes from being the active object because of the following:

• A user tabs to another object • A user clicks to / into another object • A script step is executed that makes a different object the active object. • Switching records using the user interface. • Prompted certain dialog boxes to appear such as all the “manage” dialog

boxes, print, import, export, sort, and others. • Moving from one repetition to another in a repeating field.

The OnObjectExit trigger is a “pre”-processing trigger. This means this trigger executes a script before the event has been processed. This trigger can be applied to any object that is allowed to have keyboard focus. This includes objects such as fields, tab controls, buttons, portals, and web viewers. In the case of field objects, it does not matter how a field is formatted (popup list, radio buttons, checkbox, etc.) as an OnObjectExit trigger will execute the script. However, if the field behavior of the field is set to not allow entry in either Browser and/or Find modes, then the OnObjectExit script would only be triggered if the field is exited via a script step. OnObjectExit triggers will execute a script regardless of whether the data in the field has been modified.


Layout Specific Script Triggers in Detail The next section of this technical brief will go into more detail about the seven Layout script triggers that are available in FileMaker Pro. OnRecordLoad Script Trigger The OnRecordLoad script trigger will execute a script when a record is made current or is entered into. The OnRecordLoad script trigger will execute a script when:

• Switching to a layout • Switching records via the book • Creating a new record • Deleting a record • Performing a find operation

The OnRecordLoad trigger is a “post”-processing trigger. This means this trigger will execute a script after the event has been processed. This trigger can be applied to any layout and is available in either Browse and/or Find modes.

OnRecordCommit Script Trigger The OnRecordCommit script trigger will execute a script when a set of uncommitted record changes are committed. Actions that would cause the OnRecordCommit script trigger to execute a script include:

• Changing data in a record and the moving to another record • Changing a record and then bringing up the Manage Database dialog box. • Script steps that move focus to a different record will trigger a commit if the

previous record was modified Moving from related record to related record inside a portal does not cause a record to commit and therefore would not trigger an OnRecordCommit script to execute. Changes made on related records inside a portal are committed when the main record they are related to becomes the non-current record. The OnRecordCommit trigger is a “pre”-processing trigger. This means this trigger will execute a script before the event has been processed. This trigger can be applied to any layout and is available in Browse and Find modes. Exiting a record that had keyboard focus activates this script trigger only when the record being exited was changed.

FileMaker Pro has no reliable way to communicate to the triggered script which record was previously the current record. Because of this, the scriptwriter may want to cache some information that will uniquely identify the previous record in the script that is associated with the script trigger being used.


If the script connected to the OnRecordCommit script trigger returns “true” then the triggered script will proceed normally. If the script returns “false” then the script will not continue. OnRecordRevert Script Trigger The OnRecordRevert script trigger will execute a script when a set of records is reverted. Record(s) can be reverted in one of two ways:

1. By way of RECORDS > REVERT RECORD 2. By way of the “Revert Record / Request” script step

The OnRecordRevert trigger is a “pre”-processing trigger. This means this trigger will execute a script before the event has been processed. This trigger can be applied to any layout and is available in Browse and Find modes. Clicking the REVERT FIELD button in a field validation dialog box will not execute a script attached to an OnRecordRevert script trigger. If the script connected to the OnRecordRevert script trigger returns “true” then the script will proceed normally. If the script returns “false” then the script will not continue. OnLayoutKeystroke Script Trigger The OnLayoutKeystroke script trigger will execute a script when the layout is active and a user of the database enters one or more characters from the keyboard directly or through an Input Method Editor (IME). In the case of IME input, multiple characters may be typed and committed into a field all at once. Therefore, the OnLayoutKeystroke script trigger will execute a script when the string of characters is committed to the field. The OnLayoutKeystroke trigger is a “pre”-processing trigger. This means this trigger will execute a script before the event has been processed. This trigger can be applied to any layout and is available in Browse, Find, and/or Preview modes. There are two (2) types of characters that may cause the OnLayoutKeystroke script trigger to execute a script:

1. Keystrokes that would normally be applied to an active layout object 2. Keystrokes normally used for navigation

The following actions and events process incoming keystrokes

1. The operating system is given the first opportunity to intercept certain keystrokes

2. FileMaker Pro intercepts any command-oriented keystrokes 3. A layout object with an OnObjectKeystroke script trigger attached to it can

intercept keystrokes if it wants to by the script result returning “false” 4. Navigation keystrokes that are used for navigation and non-navigation

keystrokes get processed by the active object


5. If there is not an active object then an alert message will be displayed for non-navigational keys

The first “action” to actually use the key stops the process. A script called by the OnObjectKeystroke or OnLayoutKeystroke script triggers indicates it has “used” the character by returning “false” Items / Actions that WILL NOT cause a OnLayoutKeystroke script to execute are:

1. Command shortcuts will not trigger an OnLayoutKeystroke script to execute. For example, using CMD+- (on the Mac) or CTRL+- (on Windows) to insert the date into a field will not cause the OnLayoutKeystroke script to execute. This applies to any custom menu shortcuts created using FileMaker Pro Advanced to alter the behavior of command shortcuts.

2. Changing the value of a field by way of the mouse. This includes clicking on a radio button or choosing from a pop up menu or list.

3. Changing the value of a field by way of a script. If an error in the OnLayoutKeystroke script causes it not to finish, then the key event will not be processed. OnLayoutLoad Script Trigger The OnLayoutLoad script trigger will execute a script when a layout is loaded or switched to. The script associated with the OnLayoutLoad script trigger will execute when:

• A window is first opened • A new layout is switched to by user interaction • A new layout is switched to by way of a script.

The OnLayoutLoad trigger is a “post”-processing trigger. This means this trigger will execute a script after the event has been processed. This trigger can be applied to any layout and is available in Browse, Find, and/or Preview modes. The OnLayoutLoad trigger will treat switching between table view, list view, and form view as staying on the same layout. Therefore, the OnLayoutLoad trigger will not execute a script when switching between these views. Additional scripting will be required if this is a desired action. FileMaker Pro will not execute an OnLayoutLoad script if notified that the layout has been changed remotely. OnModeEnter Script Trigger The OnModeEnter script trigger executes a script when a new user mode is entered. The OnModeEnter trigger is a “post”-processing trigger. This means this trigger will execute a script after the event has been processed. This trigger can be applied to any layout and is available in Browse, Find, and/or Preview modes. An OnModeEnter script is also triggered when a window is created.


OnModeExit Script Trigger The OnModeExit script trigger will execute a script when an attempt is made to exit the current user mode. The OnModeExit trigger is a “pre”-processing trigger. This means this trigger will execute a script before the event has been processed. This trigger can be applied to any layout and is available in Browse, Find, and Preview modes. An OnModeExit script is also triggered when a window is closed. If the OnModeExit triggered script returns a value of “true” the event that triggered the script will proceed normally. If a value of “false” is returned by the script, the triggered event will not continue and the current mode will not be exited. Timer Specific Script Triggers in Detail “Install OnTimer Script” Script Trigger A new script step entitled “Install OnTimer Script” can be used to run a specific script at a specific interval (measured in seconds). The “Install OnTimer Script” step is located in the “Control” section of the available script steps within the Manage Scripts dialog box.

The options for this new script step allow you to specify a script to run as well as a calculation that will be evaluated when the script step is executed to determine the timer interval in seconds. After the specified time has passed, the OnTimer Script will execute the script if the following are true:

• There is not another script running or in a paused state • There is not a modal dialog box open • No operations are in progress (in other words the system is idle) • That the target window is not in layout mode.


By default, a newly defined “Install OnTimer Script” step will have a duration of zero seconds. This means that the “Install OnTimer Script” step by default will not install a timer until you specify both a duration and a script to execute. This script step will continue to execute at the defined interval until one of the following events occurs:

1. The window itself is closed 2. Another “Install OnTimer Script” is issued with different values on the window

that had the original “Install On Timer Script” step set.

The “Install OnTimer Script” script step can be used to install / enable a single timer per window. If another “Install OnTimer Script” is issued on a window that already has an “Install OnTimer Script” running, the new “Install OnTimer Script” will override the old one. However, because you can attach an “Install OnTimer Script” to each open window in your solution, it is possible to have multiple “Install OnTimer Script” instances running at the same time.

A couple of other things to keep in mind when it comes to the “Install OnTimer Script” step.

1. It is not a web compatible script step. 2. The “Install OnTimer Script” step cannot be used in conjunction with a

FileMaker Server scheduled script. File Specific Script Triggers in Detail File specific script triggers have been supported in FileMaker Pro and FileMaker Pro Advanced for quite some time. Their behavior has not changed since FileMaker Pro 7. While this functionality has never been officially labeled as a “script trigger,” the

The interval of the “OnTimer Script” is reset when the “OnTimer Script” executes the script and NOT when it completes. This is important to note if you have a script that takes a long time to complete and you are expecting the “clock to reset” when the script completes. If you want a script to run every 60 minutes (3600 seconds) and the script itself takes 5 minutes to complete, the next time the script runs will be 55 minutes after the completion of the script and not 60 minutes after since the interval was reset when the script ran initially.

Want to be sure that you cancelled an “Install OnTimer Script?” Simply issue another “Install OnTimer Script” step for the window with EITHER no script specified OR with a duration set to zero (0) seconds.


reality is that a script can be “triggered” to run when the first window in a database is opened or the last window in a database is closed. OnFirstWindowOpen Script Trigger The OnFirstWindowOpen script trigger does what it says – it runs a script in a file when the first window in that file is open. In most cases, this simply means when an end-user opens a file for the first time. However, there is more to it than that and therefore a few expected behaviors should be considered when using OnFirstWindowOpen script triggers:

• “Open scripts” are not run when a file is opened as part of a relationship or if a script from another file causes the file with the “open script” to open.

• “Open scripts” will run if you open a window for a hidden file previously opened via a script or a relationship.

OnLastWindowClose Script Trigger As is the case with an “open script,” the “OnLastWindowClose” script trigger delivers on what it advertises – it will execute when a file closes. For most end users this is the most common scenario where they will use a “close script.” However, some additional behaviors of “close scripts” should be noted:

• “Close scripts” are triggered when the last window of a file is closed EVEN IF the file itself is not going to close because some other file with open windows references it. Therefore it is possible to manually close a file, have the “closing” script run, but still have the file open as a “system” file (a file displayed under the “Show Window” menu with parentheses).

• Files that are opened as “system” files will not have their “close script” run when you quit out of the application or solution --- whereas files that are closed or files that have been “hidden” will have their “close scripts” executed as expected.

New Calculation Functions to Support Script Triggers To aid in the use of implementing script triggers in your FileMaker Pro solutions, FileMaker Pro has introduced the following new calculation functions:

• Get (TriggerModifierKeys) • Get (TriggerKeystroke) • Code () • Char ()

The two new Get () functions are listed with the other Get functions while Code and Char are listed along with the Text Functions.


Get (TriggerModifierKeys) The Get (TriggerModifierKeys) function returns the state of any keyboard modifiers (if any are pressed) when a script trigger executes a script. This function only returns a value when called by a script activated by a script trigger or from a subscript that is called from a triggered script. In all other scenarios the Get (TriggerModifierKeys) function will return an empty string.

Timing can be an issue when using the Get (TriggerModifierKeys) function. Time can elapse between the keys that caused the script trigger to execute the script and when the script “asks” for information on what modifier keys are being pressed (if any). To combat this, you can use the Get (TriggerKeystroke) function and the Get (TriggerModifierKeys) together. The Get (TriggerKeystroke) can be used to capture the keys that caused the script trigger to execute the script while the Get (ActiveModifierKeys) function can be used to capture any modifier keys that might be pressed. Get (TriggerKeystroke) The Get (TriggerKeystroke) function returns a string containing the characters that activated a script to execute using either of the following script triggers:

• OnObjectKeystroke • OnLayoutKeystroke

In most cases, only one character is returned when using the Get (TriggerKeystroke) function. The exception is when input comes from an input method editor (IME). See Page 16 of this document for more information about IMEs.

The following keys are defined as modifier keys in FileMaker Pro and FileMaker Pro Advanced.

• Shift • Caps Lock • CTRL (Windows) and Control (Mac OS) • Alt (Windows) and Option (Mac OS) • (Mac OS)

Refer to the FileMaker Pro or FileMaker Pro Advanced online help for more information on how to utilize these modifier keys


Code () The Code () function is used to return the Unicode code points of the characters in the text that are supplied to it.

The Code () function is commonly used in conjunction with script triggers to capture what navigation character was used to trigger a script. For example, the Code () function could be used to determine what arrow key was pressed on the keyboard and take appropriate action (like moving to a certain field). The following table shows how navigation characters are reported to a script activated by a trigger:

KEY PRESSED

REPORTED AS

NOTES

Backspace 8 Corresponds to Unicode / ASCII code for BS (backspace)

Tab 9 Corresponds to Unicode / ASCII code for HT (horizontal tab)

Shift + Tab 9 The shift can be detected using the value turned from the Get(TriggerModifierKeys)

function Enter 10 Corresponds to Unicode / ASCII code for

LF (linefeed) Return 13 Corresponds to Unicode / ASCII code for

CR (carriage return) Escape 27 Corresponds to Unicode / ASCII code for

ESC (escape) Left Arrow 28 Corresponds to the Unicode / ASCII code

for FS (file separator) Up Arrow 29 Corresponds to Unicode / ASCII code for

GS (group separator) Right Arrow 30 Corresponds to Unicode / ASCII code for

RS (record separator) Down Arrow 31 Corresponds to Unicode / ASCII code for

US (unit separator)

You may be wondering exactly what a Unicode Code Point is. A Unicode Code Point is any value in a range of numerical values for encoding characters. You may also hear Code Point referred to as Code Position. And while we are talking about definitions, the range of numerical values that are available for encoding characters is referred to as the “codespace” or “code space” Therefore, each value in the “code space” is known as a “code point.”


Space 32 Corresponds to Unicode / ASCII code for Space

Forward Delete

127 Corresponds to Unicode / ASCII code for Delete

If one character is in the text, the Code () function will return the code point for that character. If the text contains multiple characters then the Unicode code point for each character is returned as a group of five (5) digits where the code point for the first character is represented by the low five digits, the code point for the second character in the next higher (to the left) five digits, and so forth. For example:

VALUE PASSED TO CODE () CODE () RETURNS a 97 b 98 ab 9800097 ba 9700098 empty string (“”) 0

Char () The Char () function takes Unicode code points and returns the equivalent characters. It is the complement function to the Code () function mentioned above. When the Char () function is used, the argument for the function is a number. Each group of five digits in the number argument is treated as a Unicode code point (see above) and returns the text equivalent. If the number passed to the Char () function is between 1 and 99,999 then the function will return a single character. If the number passed to the Char () function contains more than five (5) digits, then the Char () function returns a string of characters that represents those code points. For example:

VALUE PASSED TO CHAR () CHAR () RETURNS 97 a 98 b 9800097 ab 9700098 ba 0 empty string (“”) 77600097 ä


Real World Example of Script Trigger Usage It is not the intent of this section to discuss the ONLY uses of script triggers in FileMaker Pro, but simply to provide some ideas and some common real world uses of script triggers. These ideas are provided to give you an idea of the power and flexibility of script triggers and can be used to get you going in your quest to incorporate script triggers into your new and existing solutions. As with many things FileMaker Pro, creative and more robust usages of script triggers will come over time as more developers use the feature and become familiar with it. Here are several examples of how script triggers can be used in your FileMaker Pro solutions today. Simplifying Navigation At the beginning of this technical brief, the example of moving from one row to another in table view was discussed briefly. This is one of many example in which you could use script triggers for database navigation. Solution developers can unlock the power of the arrow keys on the keyboard by checking to see if those keys are pressed during usage of their solutions. However, navigation by use of conventional arrow keys is the tip of the FileMaker Pro iceberg. It is now possible to program behaviors like auto-advancing to the next field when the correct number of characters have been filled in a field or mimicking the behavior of the status bar “Go To Record” number entry into your solutions. The navigation possibilities may be endless. Automating Navigation Along the same lines as simplifying navigation comes the notion of using script triggers to aid in automating navigation. Take for example the case of entering in an US-formatted phone number into a database. Some designers split a phone number into three parts / fields: Area Code (3 digits), Prefix (3 digits) and the Line Number (4 digits). Using script triggers you could check to see if three valid characters have been entered into the “Area Code” field and automatically advance to the “Prefix” field without the end user having to navigate to that field on their own. Automating navigation might also come in handy when it comes to tab controls and displaying the proper tab in a tab control during data entry. For example, in a solution that accepts different forms of payment, an end user could select “credit card” from a value list and a script trigger could automatically display a tab in a tab control with “credit card number” and “expiration” fields – all without the end user needing to think about it. Filtering Keystrokes Have you ever had a phone number field or a social security number field where entering in non-numeric characters would be a bad thing? Sure you could validate the data AFTER the user tries to commit the record to the database and inform them, via a custom dialog box, that their data in incorrect. However, this post-processing method can be awkward and inelegant. Would it not be nice to prevent the end-user of your solution from entering in undesirable data at the time of data entry instead of relying on field data validation?


With script triggers you can use the “OnObjectKeystroke” with a Filter () function to only allow numeric characters to be entered into this type of field. Non-numeric characters would be ignored and would not be entered into the field. Utilizing script triggers could also limit the number of characters that could be entered into a field. So, for example, if you were designing an inventory database and the parts in your inventory all had part numbers of seven characters or less, you could prevent those that are doing data entry from entering an eighth character into the part number field. Committing Records from Idle Users In this scenario, you could have an “Install OnTimer Script” step periodically save or commit records to a hosted database to insure that data is saved properly. This might be useful in the case of a multi-user solution where users of the solution work in it constantly throughout the day and might leave it open for long periods. Utilizing an “Install OnTimer Script” along with a “Commit Records” script step in the background would ensure that changes to the database were saved, like in the case of an end-user going to lunch before they committed any changes they were working on. While FileMaker Pro saves data all the time by design, in this scenario you could further control when FileMaker Pro saved data. Preparing a Found Set of Records After A Layout Switch With the use of an OnLayoutLoad script trigger you could always assure that a layout contained a pre-processed found set of records every time you display records using that layout. Sure, you could do this using scripts prior to FileMaker Pro, however, with the use of script triggers you cut down the complexity of your scripts and assure your users that their data will be processed the same way no matter when a layout is switched. Execute A Find Request After Data Entry Conducting a find request in FileMaker Pro is generally a two-step process: typing in the data you want to search for and then triggering somehow a find request to occur. With script triggers you could type some data in a field, press TAB, and have FileMaker Pro automatically trigger the find request to occur. This could be done using the “OnObjectExit” script trigger. When a user exits a field that they typed in some search criteria, FileMaker Pro can take over and automatically perform the find for them. Sort a Layout Automatically Having data on a layout sort automatically will become very useful and commonplace with the introduction of live summary data / reporting in Browse mode in FileMaker Pro. An “OnLayoutLoad” script trigger could be used to automatically sort data when a sub-summary layout is displayed. This would make certain that the live sub-summary data is displayed correctly and would not require any additional user-interaction or additional scripting to display the data correctly. Taking Action Based On User Interaction or Choice


Similar to the example above, script triggers can be utilized to perform actions based on something an end-user does. For example, you could have a pull down list or menu of common actions such as print, save as, export, etc., and when a user selects one of these actions a script trigger will take over and do what is necessary to make that action occur in the database. Switch Layouts Based On A Field Value Have you ever wanted to select a value from a drop down list or menu and have FileMaker Pro automatically switch to an appropriate layout? Using an “OnObjectModify” script trigger will allow you to do this very easily. For example, you could create a pull down menu or list of label layouts that an end-user could select from, and automatically navigate to the appropriate layout print the label automatically. Advanced navigation scenarios like the one above will be much easier to implement using script triggers. Dynamically Alter the Look and Feel of a Solution Envision a value list that allows you to choose either a “beginner” or “advanced” option and based on your selection; menu items and user interface objects change right before your eyes. Maybe you want to give the users of your solution the ability to change the color scheme or other behaviors in an easy manner. While much of this could have been done prior to script triggers, the introduction of script triggers makes these possibilities a lot easier for the end user to use because it does not require them to “select something” and then “click something” to make the selection active / execute. As you can probably imagine, these examples scratch the surface when it comes to the possible uses of script triggers. Troubleshooting Script Triggers This section discusses the expected behaviors of script triggers in FileMaker Pro. While they might be expected behaviors, they might be unexpected behaviors to developers or users of script triggers. Consult this section when you are troubleshooting the behavior of script triggers in your solutions. Operations That Will Not Trigger Scripts Script triggers are primarily for enhancing the user experience by providing more ways to automate a solution. They are not designed as a data integrity feature. Because of this, there are ways for the data in your solution to be changed that will not trigger a script to execute even when you think it should.


• Bulk Operations will not trigger scripts to execute – Object based script triggers will not be triggered by operations that may change many records in one operation. The reason for this is that many records could be updated in a single operation, as in the case of a Replace Field Contents operation, and it would be inappropriate to try to queue up many scripts to run after the bulk operation has completed. Additionally, many of these bulk operations take place while a modal dialog is being displayed on the screen, like in the case of the Spell Checker, and scripts cannot be executed when displaying a modal dialog.

o The Find / Replace operation will trigger scripts as expected when performing one (1) find or replace at a time. It will not, however, when performing a Replace All or when a modal dialog box is open. This is true for a user-initiated Find / Replace and for a scripted Find / Replace.

o Performing a spell check on all fields in a record or all records in a found set, either user-initiated or scripted, will not trigger scripts unless there is an active field when the operation is started OR a field is active when the operation is over. In this example then the OnObjectExit and OnObjectEnter would trigger respectively.

• Changes to other layouts or other layout objects – Changes made to a

field via one layout object instance will not trigger scripts on other layout objects on the same layout or a different layout.

• Changes to underlying tables - FileMaker Pro actions, such as Import, Relookup, and Replace Field Contents, that are applied directly to underlying tables will not trigger scripts to execute.

• Show Custom Dialog –When using fields on a Custom Dialog box, the Custom Dialog box should be thought of as a different layout. Therefore, changes made to a field from this dialog will not trigger OnObjectModify scripts.

• Script steps that interact directly with a field – Some script steps work directly with a field and do not interact with the layout. Therefore, they will not trigger OnObjectModify scripts to execute. The scripts steps that can change a field directly are Set Field, Set Field by Name, and Set Web Viewer. These scripts should not be confused with those, such as Insert Text, that do work on a layout object even though their target is specified as a field. In cases like these, these steps will trigger the OnObjectModify script to execute.

• AppleEvents that apply directly to a database - As with script steps, AppleScripts that apply to or work through layout objects will trigger scripts to execute, while those that bypass the layout will not trigger scripts. AppleScripts in general will not cause script triggers to execute scripts, but there may be some circumstances where they might.

• Other clients – Changes made to a record via another client (remotely or otherwise) will not trigger any scripts.

• Schema changes – Schema changes may results in data changing in fields. However, this action will not trigger scripts to execute.

Interaction with other scripts that are running A triggered script will run during the next “idle” time if both of the following are true:

• There is not already a script running.


• A running script is in a paused state. After the triggered script finishes, the script state will be as it was prior to the triggered script being executed. In other words, if a script was paused prior to a script being triggered, the same script will be paused after the triggered script has executed.

If there is a running script, then a new script can be initiated via a script trigger only if a step in the running script causes one of the script triggers to execute. In this case, the triggered script will run immediately and will interrupt the previously running script. Once the triggered script finishes, the script that was running previously will resume execution. If there is a script installed using the “Install OnTimer Script” step, then that script will run only at idle time when there is no script running and FileMaker Pro is not in a modal state. Interaction with popup menus, list, calendar, and auto-complete A popup menu blocks other events from occurring. Therefore, an OnObjectEnter script trigger will not run a script until after the menu is dismissed. The layout object will not register that a change has occurred until an item is picked and the menu is closed. Therefore, OnObjectModify, Save, and Exit scripts run afterwards and will not interact with the popup menu. When a field is formatted as a pop up list or drop down calendar, or is configured to “auto complete using a value list”, the list or calendar will not display immediately on field entry when the field is formatted to use an OnObjectEnter or OnObjectModify script trigger. In the case of the field formatted with an OnObjectEnter script trigger, the pop up list, drop down calendar or auto-complete functionality will display after the script returns a “true” result. Using Script Triggers with Summary and Calculation Fields Summary fields and Calculation fields can have script triggers assigned to them just like other field types in FileMaker Pro. When using script triggers with summary and calculation fields the following behaviors should be noted:

• OnObjectModify triggers will never execute a script for Summary fields and Calculation fields. OnObjectModify triggers will not work because changes to these fields occur at the database level and OnObjectModify is only triggered by direct user interaction with a layout object.

• OnObjectEnter, OnObjectExit, and OnObjectKeystroke triggers can be used with calculation and summary fields because you can click into them and give them focus.

Idle time in FileMaker Pro is anytime another action is not taking place AND a modal dialog box is not being displayed on the screen.


Timing of multiple script triggers Keep in mind that it is possible for a single user event to cause multiple scripts to be triggered. For example, say a user moves from one record to another and this causes a field in the original record to be exited. If there are script triggers set for OnObjectEnter, OnObjectExit, OnRecordCommit, and OnRecordLoad how do you know which order the script triggers will execute in? In this case, before the original field is exited, FileMaker Pro will run the OnObjectExit script. Once that script completes and it returns a value of “true,” FileMaker Pro will next retry the original user action of moving from one record to another and will reattempt the exit of the field. If the attempt to exit the field is successful FileMaker Pro will then run the OnRecordCommit script (if the record was modified) before the record is actually committed. Just like the OnObjectExit script, the OnRecordCommit script can return a value of “true” or “false” when it completes. If it returns “true” then FileMaker Pro will reattempt the original user action again. This way, FileMaker Pro keeps trying to perform the original action each time and gets further along in the process. Eventually, FileMaker Pro will get to the OnRecordLoad script and finally the OnObjectEnter script. The OnRecordLoad and OnObjectEnter scripts will run after the operation completes successfully.

Each time a script is triggered, the environment in which the script is run may be different from when the initial event occurred and because of that, FileMaker Pro may not always be able to perform the original action. For example, if a layout is changed or a window is closed, FileMaker Pro will not end up performing the original action of moving from one record to another.

Target Window Handling Previous versions of FileMaker Pro supported the behavior that a script would act upon the front most window of a given file. In order to retain backward compatibility, FileMaker Pro now tracks the target window. This change in behavior means that ALL scripts will be initially attached to a specific window and execute on that specific window until “told” to act on a different windows even if that window is in the background. This change in behavior is especially important when using “Install OnTimer Script” triggered scripts as well as exit-triggered scripts. To maintain backward compatibility with existing solutions, FileMaker Pro continues to support the behavior of executing scripts on the front most window of a given file but now also supports the ability to execute a script on a specific window. This is accomplished by resetting the target window associated with the running script and all of its calling scripts after executing certain script steps. These script steps are:

• New Window • Select Window • Close Window


This means that a script can still be made to act on a newly created or selected window. In other words, all scripts, including all triggered scripts, can still be directed to act on the front most window of a given file. The difference in behavior is that now scripts can begin execution on some other window of a file and will remain on that window until some scripted action switches the script to act on another window. In addition, if the assigned window becomes unavailable, the script will switch to run on the front most window of the given file. Lastly, FileMaker Pro will continue the behavior of pulling the associated window to the front if a script is paused.

Debugging Triggered Scripts If your script trigger still is not working as you expected after consulting the previous section, you can use the following tips to try to figure out what is going on. For starters, it is recommended that you use the Script Debugger that is part of FileMaker Pro Advanced to “walk” through your script. The Script Debugger has been enhanced to display the type of script trigger being used along with the name of the script in the event a script trigger is being run (otherwise scripts will display as they always have in the Script Debugger dialog box.) The examples below show a script being executed by a script trigger and the same script being run independent of the script trigger. Notice that the first screen shot shows the “OnObjectEnter” information while the second screenshot does not.

One additional detail has to do with scripts that are considered to be “calling scripts” and how they should be updated when a script switches the target window. When this happens, FileMaker Pro starts with the running script, assigns it the new target window, and assigns the same window to every script below it in the call stack that belongs to the same file up to and including the topmost-triggered script. This means that FileMaker Pro will not affect previously triggered scripts or their subscripts. FileMaker Pro behaves like this because a triggered script or one of its calling scripts should not affect which window a script is running against.


Scripts that are not directly executed because of a script trigger will continue to be displayed as they always have as depicted in the example below.

Besides the above change, FileMaker Pro introduces a new behavior when the script debugger is used to step through triggered scripts to prevent script triggers from behaving unexpectedly. This new behavior prevents the user from interacting with document windows, moving between fields or records, inserting data or making keystrokes, closing the window, quitting, or performing any operations on the data. This blocking of interaction will only occur when a script has been triggered via some action. When a user uses Script Debugger on a script that has not been triggered, user interaction with the document window will work as before. Script Triggers are not suitable for all things While script triggers open up new avenues for your solutions, their functionality is not suitable for all circumstances – even those that, on the surface, look like they


would be perfect applications for script triggers. Care should be taken when using script triggers to accomplish or enhance the following actions:

• Logging Changes / Auditing – In many FileMaker solutions it is necessary to keep accurate activity or change logs of data. It seems tempting to use script triggers to assist in creating these logs. However, script triggers may not catch all the different ways a record or a particular field could be modified and therefore the logs could be inaccurate.

• Overriding or enhancing commands – It might look attractive to use script triggers to override or alter the behavior of certain FileMaker Pro commands. However, this functionality is already provided when using “Custom Menus” in FileMaker Pro Advanced.

• Maintaining file integrity – Because script triggers are user interface focused and therefore more associated with the user interface than the underlying table, it makes using script triggers to aid in file integrity unreliable. There are several different ways to alter contents of a field that will not cause a script trigger to execute. Because of this behavior, script triggers are not recommended as tools for enforcing what can and cannot go into a field.

• Alternate or enhanced security – Developers might want to create script triggers that display messaging like “Steve can’t edit this field on Tuesday” or “you can only edit this field once.” Unfortunately, script triggers do not meet these security needs well because of timing issues. For example, a fast typing user might be able to enter a field and type something before an “OnObjectEnter” script trigger has a chance to execute.

Changes to the Database Design Report in FileMaker Pro Advanced To aid in support for script triggers, the Database Design Report (DDR) built into FileMaker Pro Advanced has been modified slightly. Script triggers will be treated like properties that are on layouts or on various types of objects on a layout – in much the same way that Tooltips are today – when viewed in the DDR. The information pertaining to a script trigger that a DDR will report on is:

• The name of the script trigger event (i.e. OnObjectEnter, OnRecordCommit, etc.)

• The script that is used in script trigger • Information about what file the script is from if the script is from another file • If applicable, the calculation expression used to generate the parameter to

the script when it is called. • The modes in which the trigger will execute (browse, find, and/or preview)

In the table detailing layouts in the DDR, a new column will be added for script triggers. The new column is titled “Script Triggers.”


In the tables reporting on individual layout objects, the first column is a general-purpose “properties” column and the script trigger information will appear in that column.

Backward Compatibility with Previous Versions of FileMaker Pro FileMaker Pro 10 shares the same file format as FileMaker Pro 7, FileMaker Pro 8, FileMaker Pro 8.5, and FileMaker Pro 9. Therefore, it is possible to open up a file designed in FileMaker Pro 10 in an older version of FileMaker Pro. If a file that contains script triggers is opened in a previous version of FileMaker Pro, the new script triggers will not be recognized and, therefore, will not execute. The exceptions to this rule are the scripts that run when you open and close a FileMaker Pro file. Since these script triggers are supported in previous versions of FileMaker Pro, they will continue to work as they always have. If a layout object that has script triggers is duplicated in a prior version of FileMaker Pro, the new duplicated layout object will retain the same script triggers associated with them when opened in FileMaker Pro 10. However, if a layout object that has script triggers is copied and later pasted in a prior version of FileMaker Pro, the new


object will not retain the script trigger from the original layout object. Similarly, a layout that is duplicated in a prior version of FileMaker Pro will retain the script triggers of the original layout when it is opened in FileMaker Pro. In Closing – A Word of Caution There is a line from a recent, popular American movie that states: “…with great power comes great responsibility…” This line holds true when using script triggers in FileMaker Pro. Script Triggers provide a powerful way for you as a developer to customize FileMaker Pro in ways that were not possible in previous versions. While there has always been an inherent risk of accidently running ill-advised scripts, in most cases, these scripts needed to be manually executed so there has always been an extra layer of safety built it. The dangers with script triggers is that poorly designed scripts could be executed unexpectedly and cause data loss or lock you out of your solution due to being stuck in an endless loop. A few simple practices can be used to make sure unexpected things do not happen to you when developing your solutions.

• Test, test, and test some more – This sounds simple, but adequate testing is often overlooked. Testing is especially important in the world of script triggers as so many things can happen now by pressing a key, entering some data, or switching to a different layout. Take full advantage of the Script Debugger that is part of FileMaker Pro Advanced and step through all possible scenarios before deploying your script triggered enabled files to others.

• Have a backup or clone available – As careful as you might thing you are, accidents can happen. You could find yourself locked out of your file or otherwise in a state from which you cannot recover. It is always good practice to backup your solution but with script triggers, especially when adding new script triggers, the need for clean backups is critical. If the worst happens it is very easy to restore your database from a backup or clone.

• Do not make changes on a production copy of your solution (or your only copy) – For the reasons outlined above regarding backups and clones, it is never a good idea to make big changes to your solutions if they are in a live environment or if it is the only copy you have. Always work on a copy of your solution and when you are satisfied with the results, then move the changes into production or import your data into the copy.

With all that said, there is a “safety net” built into FileMaker Pro 10 should you attach an opening script to your FileMaker Pro file or utilize script triggers that produce undesirable results and/or lock you out of your file. There is new functionality built into the Recovery utility in FileMaker Pro 10 that allows you to bypass the startup script and layout of a file. This action will bypass all set script triggers that would affect getting into a file and allow you to address the issue that is causing you not to be able to access your file like you would like to. The “Bypass startup script and layout” is available from the Advanced Options of the Recovery command.


1. From within FileMaker Pro, click FILE > RECOVER

2. Specify the file that you would like to recover

3. On the “Name new recovered file” dialog box, click “Use Advanced Options

4. On the “Advanced Recover Options” click “Bypass startup script and layout”

This process will create a copy of your file that no longer has “OnFirstWindowOpen” and “OnLastWindowClose” scripts defined. Furthermore, it will create a blank layout called “Recover.log” that displays when the file is opened, therefore bypassing any OnLayoutLoad and other script triggers you might have defined on that layout. From here, you can modify your file as needed to fix any issues.

In order to be able to use the “Bypass startup script and layout” option during the Recovery process, you will need to provide the [Full Access] account name and password for the file. This is a security measure to prevent a normal user of the database from bypassing these actions. Even if you have not set an account name and password on your solution, you will still be prompted to provide the default [Full Access] account name and password for the file.


About The Author Steve Romig is the Technical Liaison for the Developer Relations department at FileMaker, Inc. He is responsible for overseeing the goings on in the FileMaker Technical Network and FileMaker Business Alliance and is the primary contact on Tech Talk and Biz Talk for FileMaker, Inc. Steve was also the Project Manager of File Conversion at FileMaker, Inc. in March 2004 when FileMaker Pro 7 shipped, and worked in Technical Support and in the Training department as the FileMaker Pro Technical Lead at Claris Corporation from 1994 - 1998. In all, Steve has over 13+ years of FileMaker Pro experience dating back to FileMaker Pro 2.1. © 2004,2009 FileMaker, Inc. All rights reserved. FileMaker is a trademark of FileMaker, Inc., registered in the U.S. and other countries. The file folder logo is a trademark of FileMaker, Inc. All other trademarks are the property of their respective owners. Product specifications and availability are subject to change without notice. The example companies, organization, products, domain names, e-mail addresses, logos, people, places and events depicted are purely fictitious, and any resemblance to existing persons and companies is purely coincidental. Product specifications and availability subject to change without notice. THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, AND FILEMAKER DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR THE WARRANTY OF NON-INFRINGEMENT. IN NO EVENT SHALL FILEMAKER OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS, PUNITIVE OR SPECIAL DAMAGES, EVEN IF FILEMAKER OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY. FILEMAKER MAY MAKE CHANGES TO THIS DOCUMENT AT ANY TIME WITHOUT NOTICE. THIS DOCUMENT MAY BE OUT OF DATE AND FILEMAKER MAKES NO COMMITMENT TO UPDATE THIS INFORMATION.

using script triggers in filemaker pro -...

Documents