gwcoffey.com

Archived Post

This post is archived from the now-defunct FileMaker Advisor magazine. Some posts have been edited slightly to fix typographical errors, and remove unnecessarily-gendered language. You can view the full archive here.

Practical Script Triggers

Archive Post
FileMaker Advisor icon

FileMaker Pro 10 introduced an assortment of exciting new features but the king of the hill, so to speak, is Script Triggers. You could argue that this is the biggest new feature to hit FileMaker since version 7 back in the late Cretaceous period. Alas, it is also one of the most complex features you’ll encounter as a budding FileMaker developer. But that doesn’t mean less advanced developers should ignore these triggers all together. With a little guidance, you can put script triggers to use in almost any database, and start making FileMaker do things it never could before.

Script Triggers Explained

A script trigger is, simply put, a way to tell FileMaker to run your script under some predetermined circumstance. In some sense FileMaker has always had this power. After all, you probably already know you can turn a layout object into a button. You’re telling FileMaker to run a particular script whenever the button is clicked. If you pop in to the File → File Options dialog box, you can also configure a script to run when the file is first opened and another when it is closed. All of these have been around for ages, and they’re all small examples of script triggers.

But 10 takes this to a new level by allowing you to trigger scripts under a dozen new situations. You can kick off a script whenever someone switches to a particular layout, or when they tab in to a field. Your scripts can jump in to action when your users switch tabs in a tab control, commit a record, or switch to Find mode. All these trigger points spell flexibility for you, the developer.

Do you have a report layout that should find and sort a particular way? Why make your users run a script when they can just switch to the layout. With a simple script trigger, you can make sure they always get the right data. Do you need a tab order that’s more complex than FileMaker lets you define? Maybe you want to skip right past the “Have you ever been pregnant” drop-down list if the patient is very young. Or tab in to the Date and Time fields only when the “Schedule Delivery” checkbox is turned on. These kinds of things were difficult-to-impossible in FileMaker 9 because once your user started working with the database, your scripts had very little control. Now you can sprinkle your layouts with a little magic script trigger dust, and inject control exactly where you need it. Truly, the sky’s the limit with this feature.

Adding Script Triggers to your Database

Script triggers are applied at two levels. First, you can attach a trigger to an entire layout. Alternately, you can attach a trigger to a particular layout object (like a field, portal, or tab control).

FileMaker 10 has seven layout-centric script triggers in all. Each trigger has a nerdy-sounding name that tells you a little about when it will fire. The layout script triggers are:

For layout objects, you can pick from five script triggers:

To assign a trigger to a layout, just visit the Layout → Layout Setup dialog box and switch to the Script Triggers tab (Figure 1).

The Layout Setup dialog box with the new Script Triggers tab selected. The above list of triggers is shown, which a checkbox by each. There is a section at the bottom where you can configure the selected step.

Figure 1

The Layout Setup dialog box (Layout → Layout Setup) has a new Script Triggers tab. Just turn on the trigger you want, then choose the script you want to run. For most triggers, you also get to decide which modes it works in. For example, you could set your OnModeEnter trigger to run in Find mode only, and it wouldn’t fire when you switch to any other mode.

Assigning a layout object trigger is almost as easy. First, select the object with which you want to associated the trigger. Then choose Format → Set Script Triggers. Once again, you can turn on any trigger, then pick an associated script.

A Simple Example

Suppose you run a delivery service, and you use a FileMaker database to track your upcoming deliveries. When you view your “Delivery List” layout, you always sort it descending by time, so the oldest deliveries are at the top, and top priority. Of course you can just sort the list each time you visit it, but that gets old fast. In FileMaker 9, the best alternative was to write a script that goes to the layout and sorts the records. You could then put a button somewhere to run this script, show it in the Scripts menu, or use Custom Menus to add it to some other menu.

This method works fairly well, but it isn’t perfect. You either have to script access to every layout, which is time consuming, or you have to remember that this layout is special, and get to it in a different way.

In FileMaker 10, you can use script triggers to tell FileMaker you want to run a script every time you go to this layout. When you do this, your users have nothing new to learn. They just switch to the layout the same way they always did (and the same way they do with every other layout). And best of all, it is easy to implement:

  1. Create a script with just one line: Sort Records. Configure it to sort however you like.

    Your script is now available to select when configuring script triggers.

  2. Go to the list layout and switch to Layout mode. Then, from the Layout menu, choose Layout Setup.

    You see the Layout Setup dialog box.

  3. Switch to the Script Triggers tab.

    You see the list of available script triggers. Each has a checkbox by its name.

  4. Turn on the checkbox next to OnLayoutLoad.

    At the bottom of the window, you now see a Specify button and other configuration options.

  5. In the Specify Script window, select the script you created in step 1, then click OK.

    FileMaker now shows your script name associated with this script trigger.

  6. Click OK to close the Layout Setup window and switch back to Browse mode.

    Nothing looks different but now your script will run automatically every time you or your users visit this layout.

That’s it. Now whenever you switch to this layout, FileMaker will sort the records for you. Easy as pie.

Keystroke Triggers

Suppose your database has a Delivery Scheduled checkbox, and an associated When field. The idea here is that you can schedule deliver for a certain date. As you tab through the layout, doing data entry, if you don’t turn on the Delivery Scheduled checkbox, there’s no need to enter a date. For the sake of maximum data entry efficiency, you would like the Tab key to skip right past the When field if it doesn’t need to be filled in. You can see a database like this in Figure 2.

A FileMaker database window with several fields including the checkbox and "When" field described above.

Figure 2

In this database, there’s no need to tab to the When field if you haven’t turned on the Delivery Scheduled checkbox.

You could use this same technique in other database systems too, of course. For instance, you might have questions that are age specific in your patient database, or type specific in your product database.

To solve this problem you’ll call upon the OnObjectKeystroke trigger. This is, without a doubt, the most complex of FileMaker’s trigger types. Of course attaching an OnObjectKeystroke trigger to your checkbox field is a breeze. And you can probably guess what you want your script to do:

If the checkbox is turned on and the user pressed Tab, go to the When field. Otherwise, skip to the price field.

The first challenge is figuring out which key the user pressed. Your script will be called when they press any key at all. You certainly don’t want to be bouncing from field to field if they press the letter A or the space bar. The secret is the new Get(TriggerKeystroke) function. When a script runs because of a keystroke trigger, this function tells you which key the user pressed. For instance, if the user presses the letter A, then Get(TriggerKeystroke) returns "A".

But the Tab key is a little trickier still. After all, it is hard to type a Tab into a FileMaker calculation. To make these hard-to-reach characters easier to work with, FileMaker assigns a special number to each key. It just so happens that the Tab key is number 9. The Code function turns any value into its special number code. So a calculation like this will tell you if the tab key was pressed:

Code(Get(TriggerKeystroke)) = 9

You can find a complete list of codes for special keys in the FileMaker help. Just search for “Code.”

The script in Figure 3 uses this calculation to control where the user goes when they press the Tab key. Unfortunately, if you run this script from an OnObjectKeystroke trigger attached to the Delivery Scheduled checkbox, you’ll quickly discover it doesn’t work properly.

A Script 7 steps. It starts with "If Code(Get(TriggerKeystroke)) equals 9". If this is true, it does a second condition: "If the Orders::Schedule Deliver field equals 1". If this is true it goes to the When field, otherwise it goes to the Price field.

Figure 3

This script is designed to be used with a keystroke trigger. It checks the code of the key the user pressed. If it is 9 (the Tab key) then it takes action, navigating the user to the correct field.

You were warned: keystroke triggers are tricky. This script has two problems. You’ll spot the first right away: No matter how you set the checkbox, you end up on the wrong field. The problem is simple but subtle. When you press the Tab key, your script runs, putting the user in the right field. Then, after the script finishes, FileMaker processes the Tab key, taking the user to the next field in the tab order. Clearly when your script does its thing, you don’t want FileMaker to see the Tab as well. Luckily, this is easy to fix. Many script triggers allow you script to “cancel” the original trigger action, and OnObjectKeystroke is one of them. (See the sidebar “Cancel an Event” for more on this power.)

All you need to do is add an Exit Script script step to the end of your script. Be sure to click its Specify Result button and put 0 or False in the result calculation. This tells FileMaker to ignore the keystroke after you’re done with it.

Now your script is almost perfect. The last problem requires a little testing. When you press Tab, FileMaker goes to the next field in the tab order. But if you press Shift-Tab, it goes to the previous field instead. For the sake of simplicity, you can just tell your script to ignore Tab keystrokes when the Shift key is down. You detect this with the Get(TriggerModifierKeys) function. This function returns secret codes of its own:

Since you can hold more than one modifier key down at the same time, FileMaker adds up the numbers associated with each key and gives you back the total. For instance, if you have Caps Lock and Shift down, then the result of Get(TriggerModifierKeys) will be 3 (1 for Shift plus 2 for Caps Lock).

In your case, you only want your script to operate if there are no modifier keys down, or if only the Caps Lock key is down. To make the change, modify the If step’s condition formula to look like this:

Code( Get ( TriggerKeystroke ) ) = 9 and (Get (TriggerModifierKeys) = 0 or Get(TriggerModifierKeys) = 2)

This version will only do its magic if the Get(TriggerModifierKeys) function returns 0 (no modifiers) or 2 (Caps Lock).

With this change in place, your script trigger does its magic. As you tab through the fields on the layout, FileMaker dutifully skips the When field unless it matters.

The Sky’s the Limit

The true power of script triggers goes well beyond making it a little easier to do what you could do before, or making slight improvements to data entry. With script triggers you can do things that simply weren’t possible in FileMaker 9. This is a true developer’s feature — a new tool you can use creatively to help solve complex problems. It is impossible for one article to tell you all you can do with Script Triggers. Hopefully, though, with the mechanics under your belt, and a little experimentation, you can put this power feature to use for you.