March 95 - According to Script: Attaching and Embedding Scripts
Designing a Scripting Implementation
Cal Simone
Now that AppleScript is fast becoming an important core technology of the Macintosh
operating system, more and more developers are making their applications scriptable
or improving their scriptability. The way you design your scripting implementation
can make the difference between satisfaction and frustration for users who want to
script your application. The tips presented in this article will help you do it right.
A well-designed user interface enables users to discover your application's
capabilities and take full advantage of them. Likewise, the way you design your
scripting implementation determines the degree of success users will have in
controlling your application through scripting -- writing simple, understandable,
and, in most cases, grammatically correct sentences.
And just as the consistency of its user interface has been perhaps the most important
factor in the Macintosh computer's ongoing adoption and success, consistency is an
essential part of the world of scripting. It's highly important for users (by which I
mean anyone who writes scripts, including power users, solutions providers,
consultants, in-house developers, resellers, and programmers) to feel as if they're
using a single language, regardless of which application they're scripting. As a
developer, you have a responsibility to extend the AppleScript language in a consistent
manner.
My purpose in this article, which might be considered a first attempt at some "human
scriptability guidelines," is to offer conventions, suggestions, and general guidelines
that you can follow to maintain consistency with the AppleScript language. I also give
some suggestions for redoing a poorly done scripting implementation. (I'm assuming
you're already convinced that you should make your application scriptable; if you're
not, see "Why Implement Scriptability?") The result of doing all this work is that the
AppleScript language feels consistent across applications of different types produced
by different vendors.
______________________________
WHY IMPLEMENT SCRIPTABILITY?
If you're still wondering why you should implement scriptability in your
application, consider these reasons:
• Scripting gives users a way to control your application through a
different interface. This alternate interface allows users to incorporate your
application into multi-application scenarios, as well as to automate tedious,
repetitive tasks.
• Allowing your application to be controlled through Apple events enables
Apple Guide to give your users truly active assistance.
• Implementing scripting prepares your application for OpenDoc by
ensuring that your part handlers will be able to mesh smoothly with other
parts.
• Making your application scriptable ensures that as speech recognition
matures, you'll be able to give users the option of voice control.
It's important to implement AppleScript support in your core application,
rather than through an external API, as some databases such as 4th Dimension
and Omnis do. When your core application isn't Apple event-aware, two things
happen: (1) no dictionary resides in the application itself, and (2)
functionality is usually limited. Users have difficulty doing decent scripting of
these applications, by and large. If you simply must support Apple events
through an external API, at least support the dynamic terminology mechanism
for your extensions.
The bottom line is this: If your application isn't scriptable soon, you'll be left
out in the cold. If you do the work now, not only will you open up more uses for
your application in the "big picture," but you'll also be that much closer to
implementing what you need in order to support several other technologies. So
please, don't put it off!
FIRST, SOME BASIC CONCEPTS
A good scripting implementation consists of two parts:
• An Apple event object model hierarchy, which describes the objects in
your application and the attributes of those objects.
• A semantic vocabulary, also called a terminology,consisting of the terms
used in the construction of command statements. Your vocabulary is stored in
your application's 'aete' resource, known to users as the dictionary.
Your terms, and the organization of those terms in your dictionary, directly affect the
ability of users to explore and control your application through scripting. Creating a
vocabulary through which users can effectively and easily script your application
takes time and careful effort. Don't expect to spend six months implementing Apple
events and then simply to throw together a dictionary at the last second.
It's important to note that a well-designed Apple event structure greatly increases the
ease of scripting your application. In a minute I'll say more about that, but first let's
look at the basic anatomy of an AppleScript command.
ANATOMY OF A COMMAND
You should design your scripting implementation so that users will be guided into
using a clean, natural-language sentence structure. To help you begin to visualize the
kinds of sentences your users should be encouraged to write, let's look at AppleScript's
syntactic statement structure (say that three times fast!). All application-defined
commands are in the form of imperative sentences and are constructed as follows:
verb [noun] [keyword and value] [keyword and value] . . .
These elements of sentence construction can be thought of as parts of speech that make
up a human-oriented computer language. Here are a couple of examples of commands:
close the front window saving in file "Goofballs:Razor
set the font of the first word in the front window to "Helvetica
Let's dissect these:
close verb, corresponding to kAECloseElement
the front window noun, corresponding to keyDirectObject
typeObjectSpecifier)
saving in keyword, corresponding to keyAEFile
file "Goofballs:Razor" value, of typeFSS
set verb, corresponding to kAESetData
the font of the first word noun, corresponding to keyDirectObject
in the front window (typeObjectSpecifier)
to keyword, corresponding to keyAEData
"Helvetica" value, of typeWildCard
Note that for application-defined commands, a verb -- for example, closeor set --
is the human language representation for the action described by an Apple event
(which I often shorten to just event), so there's a general correspondence between
Apple events and verbs. In this article, I identify Apple events by the event's name, its
4-byte ID, or the constant name for the ID. For example, the Close Element event has
the ID 'clos' and the constant name kAECloseElement, and corresponds to the
AppleScript verb close; the Set Data event has the ID 'setd' and the constant name
kAESetData, and corresponds to the AppleScript verb set.
Your ability to guide users toward writing clean, natural-language statements depends
a great deal on your use of the object model, as I explain next.
WHY USE THE OBJECT MODEL?
Supporting the object model facilitates scripting by allowing the use of familiar terms
for objects and actions. In the last couple of years, some important applications that
don't implement the object model have shipped, and most of them range from difficult
to impossible to script. Let's explore a couple of examples of how using the object
model can make scripting a lot easier.
Apple events and the object model are covered extensively in "Apple
Event Objects and You" in develop Issue 10 and "Better Apple Event Coding
Through Objects" in Issue 12.*
The following script is the result of a lack of defined objects in the application we'll
call My Charter. The lack of defined objects leads to a vocabulary in which every
noun-verb combination must be covered by verbs alone -- a vocabulary that doesn't
relate to other applications and that forces users to learn a new set of commands.
tell application "My Charter
Plot Options myOptions
Set Axis Lengths for X 100 for Y 100
Output PICT
Plot chart "pie
end tell
By contrast, the script below describing the same operation in much more familiar
terms results when the application uses familiar objects and characteristics of objects
(properties):
tell application "My Charter
make new chart
tell chart 1
set the type to pie
set the x axis to 100
set the y axis to 100
end tell
end tell
As illustrated by this script, a principal indication of solid use of the object model is
that the most common verbs used in scripts are make, set, andget.
Users are more likely to remember the terms for objects than commands. Moreover,
from the user interface, they often use Command-key shortcuts for the actions instead
of looking at the menu items once they get comfortable using your application. If you
don't implement the standard commands, they'll probably need to go back to your
application's menus to find out that the menu command is, for instance, Plot Chart. You
can help them by making the scripting terms intuitive. For instance, they already