Creating Scripts

Creating and editing scripts in FileMaker is fairly straightforward. Simply choose S cripts, S criptMaker and the Define Scripts dialog opens. Keep in mind you'll need to have signed in with an account that allows script access.

Before getting into the exact mechanics of creating a script, you'll want to consider the process conceptually. A script steps through a series of instructions, one at a time, until the script either reaches its last instruction or until it reaches some exit condition. Exit conditions can vary, and many of their implementations are covered in this chapter.

To delve into common scripting techniques including exit conditions, see "Common Scripting Techniques," p. 249 , later in this chapter.

Here's a simple example of the logical outline of a script that you might use to take users to a Main Menu layout after they log in. This script would be set up to run when a file is opened. Assume that someone named Kim has just logged in.

After valid login:

1. In a table of users, set the LastLoginDate field in Kim's record to today's date.
   
   
2. Set the gUserNameDisplay field to "Kim."
   
   
3. Set the gUserMessage field to "Welcome back, Kim."
   
   
4. Go to layout: Main_Menu
   
   

This simple four-step process takes care of some background tasks first, then from a user 's standpoint navigates to the main menu on which, presumably, a welcome message sits.

Topology of ScriptMaker

The Define Scripts dialog (see Figure 9.1) allows you to manage all the scripts in your current file. To reorder scripts, simply drag individual scripts up or down along the list. Unfortunately, there's no means of sorting scripts, so you need to do your best to stay organized.

Figure 9.1. The Define Scripts dialog box allows you to create, edit, and organize your scripts, and to decide which ones to display in FileMaker's Script menu.

TIP

Use ( -up/down arrow) [Ctrl+up/down arrow] to move scripts via your keyboard.

You can perform various actions in the Define Scripts dialog box as outlined in the following list:

• You can create new scripts, edit existing scripts, or delete those you no longer need.

• By selecting a given script and clicking Per f orm you can execute scripts directly from this dialog. Using this button to initiate scripts saves you the extra step of having to close the dialog and launch them from within your database.

• You can use the P rint button to print a script. Printing a script is a good way to create documentation ” especially in combination with Adobe Acrobat's capability to create PDFs ”or spot problems more easily.

• You can import scripts. You are likely to find yourself writing scripts that may be similar to those you've written before, or needing to migrate from an older file into a newer . Luckily, you need not reassemble all your scripts by hand. It's possible to import a script from another file. In this latest version of FileMaker, imported scripts match field, relationship, layout, and other references by name (as opposed to prior versions' behaviors of matching by internal object IDs). Naturally, it's necessary to double-check whether a script imported rightly. It's a good idea to look at any script steps that refer to fields, layouts, subscripts, related records, or anything that is layout-driven and assumes the object in question is on a given layout.

  TIP

  If you use FileMaker Developer, one of the easiest ways to confirm that a script has imported well is to run it the first time with the Script Debugger turned on.

  
  

• The Edit button opens the Edit Script dialog for any given selected script. A much faster way to work is to simply double-click the script you want to edit.

• The D u plicate button can be used to duplicate a script so that you need not start from scratch when writing a new script. We recommend creating a script template and duplicating such to begin new scripts.

• The check box column along the left of the dialog controls whether or not a given script appears in FileMaker's Script menu. If you hide a script by unchecking its check box, you need to provide the user with another means of performing, or executing, the script. Typically, you include a button in the user interface that executes the script. In fact, quite often this is the preferred means of managing scripts. Attached to buttons , scripts become an integral part of your user experience.

Note also that just as in other areas of FileMaker Pro, a single hyphen becomes a menu divider. If you create a script named "-", you insert a divider in your list. This is useful in organizing your scripts visually. Plan to have a good many scripts; it is a good idea to keep them well organized.

TIP

Notice that by using ( -click) [Ctrl+click] you can select multiple, non-contiguous scripts and then delete, duplicate, or print as you need.

Script Naming Practices

Keeping your scripts well organized and following good script naming practices is even more important in FileMaker 7 than it was in previous versions of the product. Prior versions of FileMaker Pro generally involved more individual files than FileMaker 7, and hence scripts tended to be naturally distributed throughout a given system. In this version, all your scripts may very well live in a single file.

NOTE

FileMaker 7's capability to store many tables in one file has many implications, but in particular with scripts, you won't be constantly closing and reopening ScriptMaker in different files. Fewer scripts are also required in many cases: Many operations that would have required executing a series of external subscripts can now be accomplished by a single script in FileMaker Pro 7.

Script naming practices vary quite widely from developer to developer; even the authors of this book find it difficult to agree to a common standard. It's less important that you follow any particular naming convention than that you use a logical and consistent system. We do, nonetheless, recommend you consider some of the following ideas:

• Use hyphens, underscores, and so on to divide your scripts into logical groupings. As in other areas of FileMaker Pro, a single hyphen displays as a menu separator in the Scripts menu.

• Don't show all your scripts to your users. Surely most can be turned off! Choose deliberately which scripts you want to make available to users in the Scripts menu.

• Think of adding headers as shown previously in Figure 9.1. Organize your scripts into groups and then label them accordingly .

• When using subscripts (this topic is covered later in the chapter), you might consider indenting the names of subscripts with underscores or using a prefix naming style to indicate that a given script belongs to another "parent" script.

• Scripts are often intended to operate on a specific table occurrence (for example, if you're using a script to control the creation of a new record). It's a good idea to use short table prefixes or suffixes when a script applies to only a given table and "all" when it doesn't ”for example, New_Record_contact_to , Report_invoices_to , or Resize_Window_all .

• If you plan on using Custom Web Publishing, we encourage you to avoid spaces and special characters in your script names. They're a pain to parse if you plan on calling these scripts from the Web. (Clearly those scripts you allow to be displayed in the Scripts menu need to follow user-friendly naming conventions.)

Script Editing

After you create a new script in ScriptMaker, or edit an existing script, the Edit Script dialog opens (see Figure 9.2). Here you construct the actual script by inserting script commands from the list on the left into the window on the right. Nearly every script step has additional options you need to specify, such as the name of a layout to go to, or the name of a file from which to import. These options appear underneath your script when you highlight a given step in your script.

Figure 9.2. The Edit Scripts dialog presents you with additional dialogs as needed to configure settings for specific steps in your script.

TIP

You can ( -click) [Ctrl+click] multiple script steps at once and insert the batch into a script in one move.

To reorder script steps, simply drag them by the two-headed arrow icon located to the left of the step. It's often handy to assemble a series of Loop steps or If steps and then click D u plicate to duplicate the batch as needed.

If Indicate Web Compatibility is enabled, script steps that are incompatible with Web publishing display in gray.

As an example, Go to Layout is a common step you'll use quite often. Notice that when you insert it into a script, a menu appears in the Script Step Options area at the lower right, from which you can choose an existing layout, the layout on which the script began , or one determined by calculation.

Full Access Privileges

Notice the Run Script With Full Access Privileges check box at the bottom of the Edit Script dialog. Designating that a script run with full access privileges means simply that for the duration of that script, FileMaker will override all security restrictions. When this option is not enabled, scripts run subordinate to whatever privilege set the currently signed-in user has. For instance, if a script makes a call to delete a record and the user who is running that script cannot do so based on his current security privileges, the script usually presents an alert message to the user and ignores that step of the script. The rest of the script is still performed.

Error management in scripts is an important element in all scripting. For more detail, see "Set Error Capture," p. 250 , later in this chapter.

Commenting Scripts

Keeping track of what scripts do is a difficult task. What seemed perfectly intuitive at the time you wrote a given script may become hopelessly obscure a few weeks ”or sometimes even hours ”later. Although developers vary in how they use comments, nearly all recognize their value.

Also remember that you're not coding in a vacuum . We can virtually guarantee that although you may never intend that a given database be seen by someone else's eyes, if it stands the tests of time and proves useful, at some point you'll crack it open with the infamous words, "Let me show you how I did this ." Likewise, professional-grade systems are nearly all collaborative efforts. Comments exist to help your peers understand what your caffeine -sodden brain was thinking at the time you wrote a particular routine.

A simple example of a commented script is seen in Listing 9.1.

Listing 9.1. Script with Comments

 #   Purpose: initiate the running of a report while allowing users to choose what sort  order they want #   History: sl 2004 02 04; bb 2004 02 05 #   Dependencies: Invoices: Monthly Report layout # #          prompt user for sort order Show Custom Dialog [ Title: "Sort Order"; Message: "Do you want to sort by amount or  date?"; Buttons: "Date", "Amount", "Cancel" ] # #          check for cancel first If [ Get (LastMessageChoice) = 3 ] Go to Layout [ original layout ] Halt Script # #          sort by Amount Else If [ Get (LastMessageChoice) = 2 ] Go to Layout [ "Monthly Report" ] Perform Script [ "Sort by Amount" ] # #          sort by Date Else If [ Get (LastMessageChoice) = 1 ] Go to Layout [ "Monthly Report" ] Perform Script [ "Sort by Date" ] # End If 

Notice that in FileMaker Pro comments are prefixed by the "#" symbol.

Using a Script Template

It is often helpful to create a template script that you can duplicate when you need to create a new script. In our templates, we include several comment lines at the top where we record information about the purpose and revision history of the script. A template script looks something like this:

 # purpose: TYPEHERE # dependencies: TYPEHERE # history: XXX DATE # #  Allow User Abort  [ Off ]  Set Error Capture  [ On ] # #   establish context Go to Layout [ Original Layout ] # # 

Although it is simple, this template does save time and promotes good code. We recommend placing the Go to Layout step in your template, regardless of whether or not you'll need it in all scripts. In many cases you may simply delete it.

This final step ensures that the script begins on the correct layout and is associated with the proper base table attached to that layout. Including it in the template prompts developers to make a conscious decision and will remind you that context needs to be managed.

Using Subscripts

One of the most useful things in ScriptMaker is the Perform Script step itself. One FileMaker script can call another script, which is then known as a subscript. This then allows you to divide scripts into smaller logical blocks and also break out discrete scripts for anything that you are likely to want to use again. This allows a degree of abstraction in your system that we very much recommend. Abstraction makes scripts easier to read, easier to debug, and modular ”in that a subscript may be generic and used in a variety of scripts. Here's an example:

 Sales_Report # purpose: to run the Sales Report, weekly or monthly # history: scl 2-5-2004 # # Perform Script [ "CheckPermission_forSales" ] # Perform Script [ "Find_CurrentSales" ] # Show Custom Dialog [ Title: "Run Report"; Message: "Would you like this report broken out  by Weekly or Monthly subtotals?"; Buttons: "Monthly", "Weekly", "Cancel" ] # If [ Get (LastMessageChoice) = 1 ] Perform Script [ "Monthly_Report" ] # Else If [ Get (LastMessageChoice) = 2 ] Perform Script [ "Weekly_Report" ] # End If 

Notice that the script offers a branch where one or another subscript will be run, but not both. It also has the Find_CurrentSales and CheckPermission_forSales scripts broken out ”which means they can be called from a variety of scripts and are not necessarily specific to only this Sales_Report script.

As an example of script abstraction, imagine sorting a contacts database by last_name then first_name for a given report. If you've written a script to produce that report, sorting is a step in the process; however, odds are that you'll want to be able to sort by last_name, first_name again ”perhaps for a different report, perhaps as a function that lives on a list view or in the Script menu, or perhaps prior to running an export script. Whenever is reasonable, we recommend looking for ways to abstract your code and foster reuse. It saves time and complexity if suddenly your client (or boss) comes to you and says you need to now present everything by first name. If that logic lives in one place, it's a one-minute change. If you have to hunt for it, it could take days and require extensive debugging.

Even if you're not planning on reusing blocks of code, it's still a good idea to break scripts into subscripts. They're easier to read, easier to turn on and off during testing, and allow you to name them in logical (even numeric, if you wish) ways that are comprehensible even at the Define Scripts dialog level.

Some other good candidates for subscripts are sort and find routines; these are often reusable by a wide range of scripts or by users as stand-alone functions. Other uses of subscripts might be for the contents of a loop or If[] function. Sometimes it's easier to separate logic into separate "paths" by dividing logical groups into separate scripts. When you have a branching script (covered later in the chapter) it's helpful to encapsulate a single branch in a subscript. This allows you to see the flow of logic in the parent script and cover each branch in its own respective subscript.