by Bob Cusick, ClickWare
Using AppleScript With FileMaker 3.0
(First in a series of articles)
The purpose of this series of articles is to explore different techniques, tips, and tricks for using AppleScript with FileMaker. AppleScript is a great tool for extending the functionality of FileMaker and can help you get (or set) data from a database and have it act on data in other programs. There are tons of cool things you can with it. You can duplicate, move, rename or create files, automate time-consuming (or boring, repetitive tasks), set time-intensive tasks to run overnight, or extend the functionality of different applications. In this first article we'll talk about the differences in FileMaker's two new scripting steps “Send Apple Event” and “Perform AppleScript”.
Before we “dive in” and examine the commands and examples, I'll talk a little bit about what AppleScript is and how it basically works. If you're already using AppleScript, please feel free to jump to the next section! If you're new to AppleScript, or have heard of it, but don't quite know what it does - read on.
Brief Overview
There are many different “scripting” programs out there; HyperCard, SuperCard, Microphone, Excel, PageMaker, Quark Express and others that all allow you to control every aspect of their interface. AppleScript is different because it can CONTROL MULTIPLE applications. For example, you can get data from your FileMaker database, tell AppleScript to process it, then tell PageMaker to format and save it, then send the file via Claris Emailer all automatically.
Note: Teaching you how to program is beyond the scope of these articles, but there are a couple of excellent books on AppleScript noted at the end of this article.
AppleScript can do all of this because it is a system resource. There are some extensions (AppleEvent Manager, and AppleScript, AppleScriptLib) that load when your computer starts up, and an application called “Script Editor” where you actually write and save your scripts. There is also a folder called “Scripting Additions” (inside your “Extensions” folder) that tells AppleScript how to perform system-level functions that aren't supported directly by the AppleScript language.
For example, there's a scripting addition called “beep” that works with the System's Sound Manager to make the Mac perform the “beep” sound. There's another addition called “Choose File” that contains the resources and special code required so that you can have your Applet choose a file, just like the “Open” command in many applications. We'll talk more about scripting additions in future articles, so don't worry too much about them right now, just be aware that they exist.
To use AppleScript you MUST have system 7.1 or later (if you use system 7.0 or 7.01 you also need QuickTime 1.5 [or higher]). The current version of AppleScript is version 1.1, and all examples will assume you have this version. If you're not sure, open your “Extensions” folder, click once on the “AppleScript” extension, and choose “Get Info” from the “File” menu. If you have system 7.5, then AppleScript 1.1 came with your system and is already installed (unless you've removed it). Well, if everything is “ready to go”, let's DIVE IN!
The “Send Apple Event” Command
This command has been around since FileMaker Pro 2.0, and is the one you'll probably wind up using the most. With it, you can open an AppleScript application (called an “Applet”), pass it some data, pass it your own custom Apple Event, have it act upon your database, pass information to other applications, and tons more!
Typically, you'll create an Applet, send the “Open Application” event from your database, the Applet will open, perform its operation(s), then quit itself. You can also have the Applet stay open and “wait” to receive more commands. In this series of articles we'll explore examples of both kinds, including how to send your own custom AppleEvent(s) to your Applet.
The “Perform AppleScript” Command
In FileMaker Pro 3.0, the engineers made the program “attachable”, which simply means that you don't HAVE to have a separate Applet to perform an AppleScript, you can write the AppleScript directly in FileMaker.
HOWEVER, there are a couple of serious limitations to doing this. The most important one is that the “Perform AppleScript” command CANNOT command FileMaker itself. So, let's say that you wanted to write an AppleScript that got the contents of a field called “First Name”, put up a dialog box that allowed the user to enter a new value, then set the “First Name” field to that new value. You CANNOT do this via the “Perform AppleScript” command! Hopefully this will be addressed in a future version, but for now, if you have to interact with your data, you must use an AppleScript Applet and the “Send Apple Event” command.
A simple illustration of using the “Perform AppleScript” command would be to alert the user (with the “display dialog” command), tell another application to do something (again NOT using your data), or to perform file maintenance (move a file(s), check if a file(s) exist, etc.).
Creating An AppleScript in FileMaker
Here's a simple example of using the “Perform AppleScript” command WITHIN FileMaker (no outside “Applet” required!):
1. Open a FileMaker 3.0 database
2. Choose “ScriptMaker” from the “Script” menu
3. Create a new script, then click the “Clear All” button.
4. From the “Available Steps” on the left, scroll all the way to the bottom, and double click “Perform AppleScript”.
5. Click the “Specify” button in the lower right, and enter this text:
display dialog "This AppleScript was defined in THIS FILE!" buttons {"OK"} default button {"OK"} with icon note
IMPORTANT NOTE: The brackets around the “OK” button name are CURLY BRACKETS (shift [ and shift ] respectively) and NOT parenthesis!
6. Click the “OK” button to save the AppleScript.
Technical Note: FileMaker is actually compiling the AppleScript and saving it with your file. This may take a couple of seconds.
7. Click the “Done” button, and choose your script from the “Script” menu. You should see a dialog box on screen with a single button “OK”. Click “OK”.
Congratulations! You've written your first AppleScript in FileMaker!
Creating An Applet
For this section, we'll be using the program “Script Editor”. So before we get started, go ahead and locate the program and double-click it. It's ok, I'll wait...
... OK, now that “Script Editor” is open, you should have a window called “Untitled 1” with the buttons “Record”, “Stop”, “Run” and “Check Syntax” with a blank area below it. It's the area BELOW the buttons in which we'll type our script (the “Description” area ABOVE the buttons is for your own comments about this particular AppleScript).
NOTE: Teaching you all the “ins and outs” of Script Editor is way outside the scope of these articles. For more information on the Script Editor Program see the documentation that came with AppleScript.
1. In the area BELOWÂ the buttons type the following text:
tell me to activate
display dialog "We're running an Applet!" buttons {"OK"} default button {"OK"} with icon note
2. Choose “Save” from the “File” menu.
3. From the “Kind” pop-up menu (that now says “Compiled Script”), choose “Application”.
4. EXTREMELY IMPORTANT: UNCHECK the “Stay Open” and CHECK the “Never Show Startup Screen” options.
5. Click the “Desktop” button, name your Applet “My First Applet” and click “Save”.
6. Close the window (or choose “Close” from the “File” menu).
7. Open any existing FileMaker Database (or make a new file if you want), choose “ScriptMaker” from the “Script” menu, create a new script, and click “Clear All”.
8. From the “Available Steps” on the left, scroll all the way to the bottom and double click “Send Apple Event”.
9. Double click the “Send Apple Event [ ]” step on the right and choose “open application” from the pop-up menu “Send event” (it now reads “do script”).
10. When you're prompted to choose a file, click the “Desktop” button and double click the Applet “My First Applet”.
11. EXTREMELY IMPORTANT: UNCHECK the “Wait for event completion before continuing” checkbox!!!
12. Click OK, click OK, click Done.
13. Choose your script from the “Script” menu and after a brief delay, you'll see your dialog box with the OK button. Click the “OK” button and your Applet will automatically quit.
Congratulations! You've created your first Applet that gets “called” by FileMaker!
You may wonder what the "Stay Open" checkbox and the "Wait for event completion before continuing" checkbox do and how to set them in your own scripts.
What the "Stay Open" checkbox means:
When you save an Applet with the setting "Stay Open," the Applet will NOT automatically quit when it has finished performing the script. With the "Stay Open" option CHECKED, the Applet will not quit (ever) until either 1) your FileMaker Script tells it to quit, or 2) the user selects the Applet from the applications menu and presses command-Q (or chooses "Quit" from the"File" menu). If you are creating an Applet that only performs a single function, then UNCHECK the "Stay Open" option. If you are creating an Applet that will receive two or more custom events, then you can CHECK the "Stay Open" so there won't be the "lag time" of the Applet loading into memory every time you call it.
What the "Wait for event completion before continuing" ScriptMaker checkbox means:
The "Wait for event completion before continuing" checkbox is SUPPOSED to wait for the AppleEvent to post an "I'm done!" message to the operating system, and then FileMaker will continue with whatever the next script step is. In the real world, this option doesn't work very well at all! I've heard of people waiting 20 minutes for FileMaker to "get" the "I'm done!" message. A better work-around is to ALWAYS, ALWAYS UNCHECK this option!
If you uncheck the option, then you'll run into another problem - FileMaker will IMMEDIATELY perform the next script step. In other words, it will pass on the Apple Event, and go right on to performing the next step(s). This causes a problem if you want to get a piece of information from your Applet (like setting a field to a particular value) before continuing. Here's a couple of workarounds:
1) Use the "Pause/Resume" script step directly AFTER your "Send Apple Event" script step. In 3.0 you can set the "Pause/Resume" step to pause for a predetermined amount of time before automatically continuing. The best place to use this is if you have long scripts that have several AppleEvent calls that you don't want to break up into smaller scripts (see #2);
2) Have your script END with the "Send Apple Event" script step, and then have your APPLET tell FileMaker to perform another script with the rest of the processing. Your command in the Applet will be:
doScript FileMaker script "My script name" (where "My script name" is the script to perform).
Conclusion & References
The examples we covered in this first article are not “life changing” but hopefully you've found them to be helpful in getting started using AppleScript with FileMaker. In the coming articles we'll look at creating your own custom events, manipulating data in fields, performing FileMaker scripts via AppleScript, and some basics on interacting with other applications.
If you're just getting started with AppleScript, check out the GREAT book by Derrick Schneider called The Tao of AppleScript. This is an EXCELLENT guide to the person who is just starting out with AppleScript. If you have most of the basics down (or you're experienced in HyperTalk, SuperTalk or other programming language) check out Danny Goodman's The Complete AppleScript Handbook (both available at bookstores everywhere). I use BOTH of these books CONSTANTLY!
If you have suggestions for future AppleScript articles, please feel free to email them to clickware@aol.com.
## END ##
Bob Cusick a FileMaker Pro developer who creates custom databases, database tools, freeware, shareware, commercial products, and is the president of ClickWare. Check out ClickWare's Web Site at <http://members.aol.com/clickware> for more FileMaker Pro Tips and free downloadable files. Please feel free to send any comments or suggestions to clickware@aol.com.