The Importance of the Layout

In a script, the active layout is very important, since it's what determines the script's context. Context is critical when you do things like delete records. If you write a script that simply deletes a record, it deletes the current record from whatever layout the user happens to be onwhich may not be the right record at all. You could end up deleting a record from the Customer table instead of the single Invoice record you meant to delete!

Take the script you've created in this chapter, for example. Before it does anything else, your Find Unpaid Invoices script goes to the Invoice List layoutbut what would happen if you left that step out? Figure 13-7 shows the options ScriptMaker gives you for the Perform Find script step. See if you can spot what's missing.

Figure 13-7. The Perform Find scripts step gives you only one optionto specify a find request. When you click Edit in the Specify Find Request dialog box, you see the window in the front. To add requests, you can pick which fields to search in, and which tables those fields are in. Problem is…there's nowhere to tell FileMaker what kind of records to find: Invoices? Customers? Line Items? The answer to that question lies in the layout your script is running on.

Upon close examination of Figure 13-7, you can see that Perform Findlike every other script stepmakes absolutely no mention of which table it should act upon. Just because you're asking it to "Find records when Invoices::Invoice ID > 0" doesn't mean you're looking for invoice records. You could be looking for customers whose attached invoices have a balance due. Or you could be looking for any line items that are on an unpaid invoice. The only way FileMaker can tell what you're looking for is by the context of the layout you're on. That's why the first step in the script goes to the Invoice List layout. That layout is attached to the Invoices table occurrence. This tells FileMaker which records to look through (those in the Invoices table) and from what perspective to resolve relationships (the Invoices table occurrence on the relationship graph).

13.2.1. When to Switch

Now that you've dutifully absorbed the lesson in the previous paragraphs, don't get lured into the idea that you always have to switch to a layout for your script to work. The fact that a script can do something useful from more than one context can be a good thing. In general, you have three choices when you write a script, and here are some guidelines on when to use each:

• Switch to a layout associated with the table you want to work with. The Go to Layout script step makes sense when you're showing certain results (like the Find Unpaid Invoices script) or when your script always makes sense, but only from one particular context. If necessary, you can then switch back to the original layout at the end of the script (Go to Layout has an Original Layout option).
• Don't include a Go to Layout script step at all. Just let the script go about its business, whatever the context. If you use this approach, you have to make sure the script works and makes sense from any perspective. For instance, a script could switch to Preview mode, resize the window to show the whole page, and then ask the user if he'd like to print. This script can run on nearly any layout and still do something usefulprint. (See the box on Section 13.4.1 for one example of context independent scripting.)
• Prevent the script from running on the wrong layout. As you'll see on Section 13.4.1, you can make it so a script won't run at all if it's not designed to work properly on the current layout. This alternative is your best bet when switching layouts within the script isn't feasible. For example, suppose you have a Refund Invoice script that carries out the steps necessary to pay someone back. Using Go to Layout to switch to the Invoices layout would ensure the right layout, but not the right invoice. It's best if this script runs only when the user is already open to the Invoices layoutpresumably looking at the invoice she wants to refund.

---

Tip: Anytime a script can do damage to your database when run from the wrong layout, you may want to use that last option even if you're the only person who uses your database. If your mouse hand slips when you're insufficiently caffeinated, the script can show you an error message rather than running at the wrong time (Section 15.2.1).

---