One of Frontier's major strengths is its ability to work with other applications. It can interact with external applications in two basic ways:
- It can drive a single application, acting as that application's scripting language.
- It can act as an intermediary to allow several scriptable applications to talk to each other by giving them a common ground through which to interact.
In this chapter, we will focus on how to write Frontier scripts that take advantage of scriptable applications. We will begin by describing at a high level how your scripts can "drive" an application. Then we'll build a couple of examples of such scripts. These sample scripts enable you to control a scriptable application called BarChart that is included with the Macintosh version of Frontier in the UserLand Utilities Folder.
BarChart is just used as an example. You probably have many scriptable applications on your disk. This chapter will focus on the basics, giving you a foundation from which to learn the specifics of whichever applications are of particular interest to you.
How Scripts Control Programs
Frontier can control any program which is scriptable, that is, any program which has been written or enhanced to receive specific "Apple Event" messages. Each application implements a different set of verbs, though similar applications often have many verbs in common.
Applications that are scriptable will generally come with a Frontier install file -- usually named something like BarChart.Frontier (the application name appearing before the period following "Frontier"). When you install the application for the first time, you will simply double-click on this install file. It will then install a table of verbs into Frontier's Object Database. That table of verbs is called the applications "glue," "glue scripts," or "glue table." Some install files may be available from sources other than the publisher of the application, including the Internet, on-line services and Macintosh user groups.
Figure 5-1 shows what actually happens when your script instructs an external, scriptable application to do something which it "understands" (meaning that it has a corresponding verb or Apple Event and an entry in the Frontier table where its interface is defined).
Figure 5-1. Controlling an Application from Frontier
Control One Application
Now that we know how glue scripts controls an application, how do we use them in our own Frontier scripts? The short answer is that there is no fundamental difference between a Frontier script that drives an external application and one that manipulates the operating system or adds functionality to Frontier itself.
To use a verb connected to a scriptable application, you write a script that:
- ensures that the application is running
- calls one or more of that application's verbs using the same notation we've been using throughout this manual
To use a BarChart verb, then, you simply call it by providing the application's name, followed by a period, followed by the verb name, followed by a set of parentheses enclosing its parameters, if any.
Here's a sample script you can paste into your workspace table. (Make a new script in your workspace table called testBarChart, copy this script from this page, and paste it into your new script. It should paste fine.)
«Illustrates the use of UserLand's BarChart demo app
if not app.start ("BarChart") «try starting up the BarChart application
return (false)
app.bringToFront ()
BarChart.newWindow (4, "Temperatures in Redwood City", "° F");
BarChart.setBar (1, "Jan", 54) //set the label of bar 1 to Jan, value to 54
BarChart.setBar (2, "Apr", 67)
BarChart.setBar (3, "Jul", 82)
BarChart.setBar (4, "Oct", 73)
return (true)
Run the script by clicking on the Run button. BarChart comes to the front and displays this lovely chart:
Behind each of the BarChart calls in the script is a call to Frontier's built-in "appleEvent" verb. That's how your scripts communicate with other applications. Here's what BarChart.setBar does:
on setBar (n, blabel, bval) «set the label and value of one of the bars
return (appleEvent (BarChart.id, 'BARC', 'sbar', '----', short (n),
'lbar', string (blabel), 'vbar', long (bval)))
Luckily, you rarely have to look inside one of these "glue" scripts. They look so much prettier from the outside!
BarChart and Menu Sharing
Because BarChart supports a special Frontier protocol called "menu sharing," we can examine the scripts attached to some of its menus. In BarChart, hold down the Option key while you select "Watch Random Numbers" from the "Misc" menu in BarChart. Hold the Option key down until Frontier opens the menubar editor for the menu, then click on the "Script" button. The resulting script looks like this:
«this script uses BarChart to measure
«the randomness of Frontier's
«random number generator
app.start ("BarChart")
local (ctbars = 7)
local (windowtitle = "Random Number Test Window")
bundle «establish contact, open a window, label the bars
if app.selectWindow (windowtitle) «already has a window with this title
BarChart.setBarCount (ctbars)
else
BarChart.newWindow (ctbars, windowtitle, "")
BarChart.setBar (1, "Mon", 0)
BarChart.setBar (2, "Tue", 0)
BarChart.setBar (3, "Wed", 0)
BarChart.setBar (4, "Thu", 0)
BarChart.setBar (5, "Fri", 0)
BarChart.setBar (6, "Sat", 0)
BarChart.setBar (7, "Sun", 0)
loop «pick a bar, add one to it; press cmd-period to kill the script
local (x = random (1, 7))
BarChart.setBarValue (x, BarChart.getBarValue (x) + 1)
If you run the script, the window will probably look something like this:
We'll go more deeply into the concepts in this script in the next section.
BarChart's Glue Scripts table
As a script writer, you will generally not have to be concerned with the inner operations of glue scripts (also known as "install scripts") for external applications you wish to control. But in case you are curious, let's take a quick look at where they are stored and what they look like.
Figure 5-2 shows part of the system.verbs.apps table where glue scripts are stored.
Figure 5-2. The Install Scripts Table in Frontier
Let's open the table for BarChart (type Cmd-J then "BarChart," click OK). It looks like Figure 5-3.
Figure 5-3. BarChart Install Table
Just from their name, you can probably determine what most of these glue scripts will let you tell BarChart to do.
Just for fun, let's take a look at one of these install scripts. Double-click the item marker next to the script newWindow. The script looks like this:
This is a fairly normal-looking Frontier script, not unlike many others we've seen in this user's guide. It uses a "generic" newWindow verb (common to utilities created by UserLand) in the app table to create a new window, then makes sure it is able to set up a window to accommodate the desired number of bars and units. Notice that this script calls BarChart.setBarCount. Let's open that install script by Command-double-clicking on the verb's name in the newWindow script. It looks like this:
Now this script looks a good bit different from other scripts we've seen, at least in its operational line. The first line is familiar-looking. The second line is typical of glue scripts in Frontier. It uses a call to Frontier's appleEvent verb (which handles Apple events), passes it some information about what the verb wants to do and what application it wants to use, and returns the result of that call.
Creating and editing these scripts can be left to Frontier experts. We've given you a short peek behind the scenes to help you understand how scriptable applications are controlled from Frontier.
Scripting more than one application
As you can see, using external applications from within Frontier is for all practical purposes as easy as using Frontier itself. As final proof, let's build a script that uses the Macintosh Finder, Aladdin Systems's StuffIt compression program, and Dartmouth's Fetch FTP client.
The script loops over all the files selected in the Finder, adding each one to a StuffIt archive it creates. It then binhexes the archive and uploads it to an FTP server.
«create and upload a StuffIt archive of all the files selected in the Finder
local (sitfile = file.getSystemDisk () + "Desktop Folder:samplefile.sit")
local (hqxfile = sitfile + ".hqx")
local (serverpath = "/pub/" + "samplefile.sit.hqx")
stuff.createArchive (sitfile, finderMenu.getSelectionList (), true)
app.start ("Fetch")
Fetch.store (hqxfile, "ftp.mancuso.com", serverpath, "bullman", "no.way")
file.delete (hqxfile)
This is a very tight script that does a lot and really illustrates the power of interapplication communication. First, it calls stuff.createArchive, which launches StuffIt if necessary, and sends it instructions to add all of the files selected in the Finder (finderMenu.getSelectionList ()) to a new archive named samplefile.sit, located on your system desktop.
The last parameter to stuff.createArchive, true, says that we also want the file to be binhexed. This call will create a file named samplefile.sit.hqx.
Now that the file we want to upload has been created, we launch Fetch, tell it to upload the file (to a fictitious server, named ftp.mancuso.com) and when its done, we delete the file, using Frontier's built-in file.delete verb.
You can run the script if you want. You can copy-and-paste from this page into a script in your workspace table. Be sure to substitute your account information in the call to Fetch.store.
Click "Compile" if you want to just check the syntax. If you get an error, click "GoTo" and compare that line (or possibly the previous line) to the script shown above. Click "Run."
What About My Application?
Entire chapters or even books could be written for each scriptable application. With the information you learned in this chapter, you should be able to browse any application table and try out some of the verbs. Some applications include excellent scripting documentation, some depend on notes written by a few dedicated volunteers, others include nothing. Perhaps you will be one of the volunteers! Chapter 1 offers pointers to sources of information.