TweetFollow Us on Twitter

AppleScript Scorecard

Volume Number: 14 (1998)
Issue Number: 2
Column Tag: Scripting

The AppleScript Scorecard Guidelines

by Cal Simone and Bill Cheeseman

Is your application truly scriptable? These guidelines may help you find the answer

For users writing scripts in AppleScript, the number one challenge is the lack of intuitiveness in scripting implementations and consistency when moving among scriptable applications of different types. To aid potential users of scriptable applications in determining the suitability of particular products for their scripting scenarios and, more importantly, to promote these characteristics among developers of scriptable applications, a set of guidelines has been developed, in the form of an AppleScript "Scorecard".

By the time you read this, the Catalog of Scriptable Products should be available on the Web, tentatively at http://www.mainevent.com/scorecard/. The Catalog is a comprehensive directory of scriptable applications, and includes reviews and ratings. The guidelines put forth in this article were developed to form the basis for the reviews and ratings found in the Catalog.

Although the guidelines were developed primarily as an aid for users, they are offered here so that, as the developer of a scriptable product, you can see, in broad terms, what makes up an application that delivers the power of user scripting into the hands of users. Note that, at the time of writing this, we were close to completion, but the final point distribution had not been frozen.

Even if you don't submit your application for a rating, following the criteria of this scoring system will guide you to making your application more easily scripted and more consistent with other well-designed object model-based applications.

The Guidelines

These Guideline are Copyright 1997-1998, Cal Simone and Bill Cheeseman. Printed courtesy of MacTech Magazine, April 1998. The Guidelines may be freely used and distributed, provided that they are copied or distributed in complete form, without alteration, and provided this notice is included.

To promote full AppleScript support in the widest range of products, an application is rated in the AppleScript Scorecard in part for the full and proper implementation of specific scripting features, such as the object model and recordability. To promote the highest quality, an application is also rated on a more qualitative assessment of the design, completeness, transparency, stability and documentation of its AppleScript implementation. In the first phase of rating an application, a range of points is awarded for the presence of specific features, taking into account the extent to which each feature is implemented and its conformity to Apple standards and conventions. In the second phase, additional points are awarded on a sliding scale for specific overall qualities of the scripting implementation.

The AppleScript Scorecard rates an application's support for AppleScript on a scale of 0 to 100. The final score is converted to a scale of one to five "scripts", with half-scripts (1-10 = 1/2 script, 11-20 = 1 script, etc.). The "scripts" score is the primary rating for public distribution, but the points score can be published in parentheses (after converting it to a scale of 0.0 to 10.0 with one decimal place). An example: "3-1/2 scripts (7.2)".

An application is not considered scriptable, and it is not rated, if it has no dictionary or terminology ('aete') resource, or if it has a dictionary that supports only the Required Suite (the run, open, print and quit Apple events) and the "do script" event. Its Finder "scriptable" property may be true because it does respond to the Required Suite, but this by itself does not reach the threshold necessary to be rated.

To be considered for rating, therefore, an application must implement a meaningful and reasonably useful set of verbs in addition to those in the Required Suite (run, open, print and quit), although not necessarily in the form of additional, named suites. Even a small number of supported commands suffices, as long as they enable a scripter to take advantage of some significant and useful functionality of the application. The "do script" event, without more, does not qualify (because this is a rating of the application's AppleScript features, not of a proprietary internal scripting system.)

Phase 1 -- Scripting Features Supported

Points are awarded in Phase 1 for the presence of the specific AppleScript features described below. A range of points may be awarded for the presence of each feature to take into account the extent of its implementation and its conformity to Apple standards and conventions, but Phase 1 does not otherwise rate qualitative aspects of the application's AppleScript support.

Implementation of any of these AppleScript features in conformity to its description here merits awarding the maximum number of points for that feature. Points should be deducted from the maximum for failure to implement specific aspects of a feature where indicated. Points should also be subtracted for limiting a scripting feature such as the object model to a narrow subset of an application's functionality; the penalty should be roughly proportional to the fraction of the application's functionality that is not covered by the scripting implementation. The maximum score for complete implementation of all possible scripting features is 40 points.

Object Model Support -- supports the Apple event object model -- 0 to 25 points

The application supports the object model. It includes at least the essential verbs in the Core, or Standard, Suite ("make", "get" and "set," at a minimum). It also implements a meaningful set of objects that can contain other objects and that have properties. The elements contained in objects have a variety of reference forms (e.g., by index, by name, by unique ID) suitable to their intended use. Its supported commands, including new verbs devised for the application, can operate on various objects and properties in object model fashion. For example, instead of providing commands that are verb-noun hybrids like "GetColor", a graphics application might support objects of several classes, including "picture," which can have any of several properties, including "color," and commands that can operate flexibly on any of those objects and properties to allow a scripter to create complex statements such as "make new picture with properties {color:red}", "get the color of the first picture" and "set the color of picture 3 to red." The objects supported by an application must correspond to all of the conceptual structures of the application (windows, pictures and so on; not its internal programmatic objects). 5 points should be withheld if the application does not support the filter reference form ("whose" clauses).

Recordable -- supports recording -- 0 to 5 points

The application automatically generates the text of valid AppleScript statements when actions are recorded by a script editor. To receive the full 5 points, the generated script must be executable without editing when run under the same conditions under which it was recorded, and its statements should be in general form (for example, they should not refer to objects by unique id).

Attachable -- supports a "Scripts" menu -- 0 to 5 points

The application has a "Scripts" menu which lists AppleScripts written by the user and allows them to be run from the menu bar. An application typically installs the scripts in the Scripts menu when the user places them in a folder within the application's folder. Withhold 1 point if the Scripts menu does not support hierarchical menus (scripts installed in subfolders of the Scripts folder), and withhold 1 point if the Scripts menu is not updated "on the fly" when a new script is placed in the Scripts folder. Withhold 2 points if the menu has a name other than "Scripts" or its synonym in non-English systems.

Embeddable -- supports embedding of scripts in the user interface generally -- 0 to 5 points

The application provides a means to integrate user-written AppleScripts into the user interface in any of a variety of ways in addition to or instead of installing them in a "Scripts" menu. For example, scripts can be executed by clicking on buttons on a tool palette, or scripts can be run as background agents in response to events occurring in the application such as the launching of the application, the opening or closing of a window or the receipt of e-mail. The specific user interface and the manner in which these scripts are stored is not specified and is not relevant to the score. To receive the full 5 points, the manner in which embedded scripts are made available to the user should be creative, consistent with the user interface generally and easy to use.

Phase 2 -- Quality of Scripting Implementation

In addition to the points awarded in Phase 1 for specific scripting features, additional points are awarded in Phase 2 on the basis of the following qualitative assessments of specific aspects of an application's AppleScript support. In general, these categories rate the degree to which an application's AppleScript support forms a consistent and useful user interface in its own right.

An award of 0 points in any one category means that the implementation is abysmal in that respect; 2 or 3 points, that it is barely useful; 6 points, that it is average and therefore acceptable; 9 or 10 points, that it is very good; and 12 points, that it is nearly perfect. In general, a conservative approach is taken so that room will be left at the extreme ends of the scale to distinguish the worst and the best implementations. An average score is not bad, and the scores of most applications should cluster around 6. A score of 4 or 5 points will not be uncommon for slightly below average implementations, and 7 or 8 points should be considered appropriate for good implementations. The maximum score for quality is 60 points. To be awarded the full score, an application's AppleScript support should achieve all of the desired qualities in each category described here.

Design -- fidelity to the application's structure and function -- 0 to 12 points

The Application's commands, objects and properties, and the containment hierarchy and relationship of objects to one another, flow naturally from its subject matter and function instead of rigidly and slavishly mimicking its menu commands and dialogs. The richness of the application is reflected in a relatively large number of objects, or nouns, and a relatively small number of events, or verbs, that act upon them. Commands and objects from established suites, such as the Text Suite, are implemented faithfully if the application is one for which the suite is appropriate. For an application in an area that has no established suites, its commands and objects reflect an equally appropriate fidelity to the structure and function of the application. Consistency with good scripting implementations in the run of scriptable applications in a particular field is closely observed or, if a new and different approach is taken, it is creative, imaginative and, above all, natural and intuitive -- and still in keeping with the "look and feel" of standard AppleScript. Verbs and nouns that go beyond the standard features of established and well-designed suites must extend the language in a consistent and useful manner.

Completeness -- depth, breadth and thoroughness of scriptability -- 0 to 12 points

The application implements a large number of commands, a wide array of objects having a deep containment structure, and a rich and extensive set of properties, exposing the application's full complexity and overall functionality through its scripting interface. The AppleScript implementation is thorough, detailed and complete, making all appropriate functions of the application available to the scripter.

Transparency -- resemblance to plain English words and syntax -- 0 to 12 points

AppleScripts written with the application's dictionary are made up of simple English sentences. Common words in everyday use are employed in a familiar way to describe commands, objects and properties. The application's terminology and syntax are natural and intuitive, not awkward and obscure. A traditional computer programmer would think that an AppleScript statement written using the application's dictionary was a conceptual description of a script, not its executable code. A nonprogrammer would have a good chance of getting an AppleScript statement right the first time without looking at the manual, and scripters experienced with the application would have little difficulty remembering how to script it.

Stability -- absence of bugs -- 0 to 12 points

The application's AppleScript implementation is bug-free, and it works according to specification.

Documentation -- documentation and examples are provided -- 0 to 12 points

Instructions for most or all of the application's scripting features are provided, whether in print or on disk. The documentation is clearly written, well organized and thorough. A large number of useful examples are provided. Apple Guide help (or another help facility available within the application) covers the topic of scripting. The scripting dictionary ('aete' resource) within the application has comments sufficient to remind a user familiar with the application how to use its commands and objects without the need to resort to the external documentation.

Getting Your Product Rated

Send your application (including documentation), in a StuffIt archive, to review@script.org. Submitting to this address will cause the terms in your vocabulary to be added to the databases (both inside and outside of Apple) that are used to analyze and maintain the AppleScript language. This also submits your product for review in the Catalog of Scriptable Products. A submission form is also available in the Catalog's web area, tentatively http://www.mainevent.com/scorecard/. If your application is large, has printed manuals, or is packaged in a box, instructions can be found on the submission form for shipping your product, manuals, or other materials for review.

More Resources for Implementing Scriptability

A roadmap for achieving a thoughtfully designed and well-executed scripting implementation can be found in "According To Script: Steps to Scriptablility" in develop issue 24.

Many of the style guidelines, conventions, tips, and tricks (including the reasons for implementing the object model) are offered in "Designing a Scripting Implementation" in develop issue 21, and the rest of the "According to Script" series, issues 22-26 and 29.

Details of the Apple Event Manager and OSA (Open Scripting Architecture) API are described in Inside Macintosh: Interapplication Communication.


Cal Simone, cal@script.org, champion of AppleScript, is the President of Main Event Software mainevent@his.com and the designer of the Scripter authoring and development environment for AppleScript. In the first half of 1997, Cal spearheaded a 5-month effort to rescue AppleScript from the chopping block during Apple's "technology evaluation" (also known as the "spring cleaning") and to convince Apple's top management to commit to AppleScript in Rhapsody.

Bill Cheeseman, cheeseb@mediaone.net is a lawyer in Massachusetts, and he maintains The AppleScript SourceBook site at http://oasis.bellevue.k12.wa.us/cheeseb/index.html. A true-life legal experience of his is the subject of the best-selling book "A Civil Action," and it is being made into a Hollywood movie, starring John Travolta, to be released in late 1998. Bill has been programming Apple computers as a hobby since 1977.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Black Hole Joyrider (Games)
Black Hole Joyrider 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Guide your spacecraft through the gravity well of a powerful black hole using only your retro-thrusters and dwindling fuel... | Read more »
My Koi (Games)
My Koi 1.0 Device: iOS iPhone Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: My Koi is a beautiful and relaxing fish pond app. Customise and name each fish. Feed them daily. Watch them grow. Collect new fish.... | Read more »
Never Gone (Games)
Never Gone 1.0.2 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.2 (iTunes) Description: ###IMPPORTANT### Never Gone's HD art resources require devices with more than 1GB RAM, so please note that iPhone 4/4s, iPad 2/... | Read more »
INKS. (Games)
INKS. 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: From the makers of BAFTA-winning Lumino City comes INKS. INKS updates pinball for a new generation. It combines the joy of pinball with... | Read more »
How to maximise your profits in Bakery B...
Running a bakery can be an expensive venture. You’ll need to continuously upgrade your oven, your kitchen supplies, and even your ingredients to keep customers happy. Most of these renovations in Bakery Blitz cost a pretty penny, but we have a few... | Read more »
How to manage your time in Bakery Blitz
It can be tricky, especially when you risk burning your kitchen to the ground if you forget a cake in the oven, so make sure to use these time management tricks to keep your bakery running smoothly. Don’t collect the money right away [Read more] | Read more »
Model 15 (Music)
Model 15 1.0 Device: iOS iPhone Category: Music Price: $29.99, Version: 1.0 (iTunes) Description: The Moog Model 15 App is the first Moog modular synthesizer and synthesis educational tool created exclusively for iPad, iPhone and... | Read more »
How to deal with wind in Angry Birds Act...
Angry Birds Action! is a physics-based puzzler in which you're tasked with dragging and launching birds around an obstacle-littered field to achieve a set objective. It's simple enough at first, but when wind gets introduced things can get pretty... | Read more »
How to get three stars in every level of...
Angry Birds Action! is, essentially, a pinball-style take on the pull-and-fling action of the original games. When you first boot it up, you'll likely be wondering exactly what it is you have to do to get a good score. Well, never fear as 148Apps... | Read more »
The beginner's guide to Warbits
Warbits is a turn-based strategy that's clearly inspired by Nintendo's Advance Wars series. Since turn-based strategy games can be kind of tricky to dive into, see below for a few tips to help you in the beginning. Positioning is crucial [Read... | Read more »

Price Scanner via MacPrices.net

12-inch 128GB iPad Pros on sale for up to $10...
B&H Photo has 12″ 128GB WiFi iPad Pros on sale for up to $100 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 12″ Space Gray 128GB WiFi iPad Pro: $899 $50 off MSRP... Read more
Global Tablet Sales Slump Continues, iPad’s F...
Another miserable showing for the global slate tablet category in calendar Q1/16, with global tablet shipments falling another 1ten percent to 46.5 million units during the according to Strategy... Read more
Revel Systems to Showcase iPad POS Platform w...
Revel Systems, specialists in iPad Point of Sale management solution for brick-and-mortar retail, food businesses and more, today announced that it will showcase its innovative iPad Point of Sale... Read more
13-inch 2.5GHz MacBook Pro on sale for $999,...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Apple refurbished 2015 iMacs available for up...
Apple now has a full line of Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are... Read more
Indian Smartphone Market Grows Annually by 12...
India’s smartphone market grew by 12 percent year-over-year, with 24.4 million units shipping in Q1 2016. The top five vendors stayed the same, with Samsung in the lead, followed by Micromax, Intex... Read more
Get Notifications When Your Friend’s Phone Ba...
Calgary, Canada based Stonelight Pictures has announced the release of Battery Share 1.0.1, its new utility for iOS 9 supported devices. The company notes that people are spending more time on their... Read more
11-inch 1.6GHz/128GB MacBook Air on sale for...
Amazon has the current-generation 11″ 1.6GHz/128GB MacBook Air (sku MJVM2LL/A) on sale for $749.99 for a limited time. Their price is $150 off MSRP, and it’s the lowest price available for this model... Read more
Price drops on clearance 2015 13-inch MacBook...
B&H Photo has dropped prices on clearance 2015 13″ MacBook Airs by up to $250. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/4GB/128GB MacBook Air (MJVE2LL/A): $799, $200... Read more
Mac minis on sale for up to $100 off MSRP
B&H Photo has Mac minis on sale for up to $100 off MSRP including free shipping plus NY sales tax only: - 1.4GHz Mac mini: $449 $50 off MSRP - 2.6GHz Mac mini: $649 $50 off MSRP - 2.8GHz Mac mini... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Automotive Sales Consultant - Apple Ford Linc...
…you. The best candidates are smart, technologically savvy and are customer focused. Apple Ford Lincoln Apple Valley is different, because: $30,000 annual salary Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Simply Mac *Apple* Specialist- Service Repa...
Simply Mac is the largest premier retailer of Apple products in the nation. In order to support our growing customer base, we are currently looking for a driven Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.