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.

 
AAPL
$100.96
Apple Inc.
-0.83
MSFT
$47.52
Microsoft Corpora
+0.84
GOOG
$596.08
Google Inc.
+6.81

MacTech Search:
Community Search:

Software Updates via MacUpdate

Airfoil 4.8.9 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
WhatRoute 1.13.0 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the... Read more
Chromium 37.0.2062.122 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. FreeSMUG-Free OpenSource Mac User Group build is... Read more
Attachment Tamer 3.1.14b9 - Take control...
Attachment Tamer gives you control over attachment handling in Apple Mail. It fixes the most annoying Apple Mail flaws, ensures compatibility with other email software, and allows you to set up how... Read more
Duplicate Annihilator 5.0 - Find and del...
Duplicate Annihilator takes on the time-consuming task of comparing the images in your iPhoto library using effective algorithms to make sure that no duplicate escapes. Duplicate Annihilator detects... Read more
jAlbum Pro 12.2 - Organize your digital...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code!... Read more
jAlbum 12.2 - Create custom photo galler...
With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly, with pro results Simply drag and drop photos into groups, choose a design... Read more
Quicken 2015 2.0.4 - Complete personal f...
Quicken 2015 helps you manage all your personal finances in one place, so you can see where you're spending and where you can save. Quicken automatically categorizes your financial transactions,... Read more
iMazing 1.0 - Complete iOS device manage...
iMazing (formerly DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and... Read more
Xcode 6.0.1 - Integrated development env...
Apple Xcode is Apple Computer's integrated development environment (IDE) for OS X. The full Xcode package is free to ADC members and includes all the tools you need to create, debug, and optimize... Read more

Latest Forum Discussions

See All

View Source – HTML, JavaScript and CSS...
View Source – HTML, JavaScript and CSS 1.0 Device: iOS Universal Category: Utilities Price: $.99, Version: 1.0 (iTunes) Description: View Source is an app plus an iOS 8 Safari extension that makes it easy to do one key web developer... | Read more »
Avenged Sevenfold’s Hail To The King: De...
Avenged Sevenfold’s Hail To The King: Deathbat is Coming to iOS on October 16th Posted by Jessica Fisher on September 19th, 2014 [ permalink ] Just in time for Halloween, on October 16 Avenged Sevenfold will be launching | Read more »
Talisman Has Gone Universal – Can Now be...
Talisman Has Gone Universal – Can Now be Played on the iPhone Posted by Jessica Fisher on September 19th, 2014 [ permalink ] | Read more »
Tap Army Review
Tap Army Review By Jennifer Allen on September 19th, 2014 Our Rating: :: SHOOT EM ALLUniversal App - Designed for iPhone and iPad Mindless but fun, Tap Army is a lane-based shooter that should help you relieve some stress.   | Read more »
Monsters! Volcanoes! Loot! Epic Island f...
Monsters! Volcanoes! Loot! | Read more »
Plunder Pirates: Tips, Tricks, Strategie...
Ahoy There, Seadogs: Interested in knowing our thoughts on all this plundering and pirating? Check out our Plunder Pirates Review! Have you just downloaded the rather enjoyable pirate-em-up Plunder Pirates and are in need of some assistance? Never... | Read more »
Goat Simulator Review
Goat Simulator Review By Lee Hamlet on September 19th, 2014 Our Rating: :: THE GRUFFEST OF BILLY GOATSUniversal App - Designed for iPhone and iPad Unleash chaos as a grumpy goat in this humorous but short-lived casual game.   | Read more »
A New and Improved Wunderlist is Here fo...
A New and Improved Wunderlist is Here for iOS 8 Posted by Jessica Fisher on September 19th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Evernote Update for iOS 8 Adds Web Clipp...
Evernote Update for iOS 8 Adds Web Clipping, Quick Notes, and More Posted by Ellis Spice on September 19th, 2014 [ permalink ] | Read more »
Apple Names Ultimate Productivity Bundl...
Apple Names Ultimate Productivity Bundle by Readdle as the Essential Bundle on the App Store Posted by Jessica Fisher on September 19th, 2014 [ permalink | Read more »

Price Scanner via MacPrices.net

Updated Price Trackers
We’ve updated our Mac Price Trackers with the latest information on prices, bundles, and availability on systems from Apple’s authorized internet/catalog resellers: - 15″ MacBook Pros - 13″ MacBook... Read more
Mac Pros available for up to $260 off MSRP
Adorama has Mac Pros on sale for up to $260 off MSRP. Shipping is free, and Adorama charges sales tax in NY & NJ only: - 4-core Mac Pro: $2839.99, $160 off MSRP - 6-core Mac Pro: $3739.99, $260... Read more
13-inch 2.6GHz/256GB Retina MacBook Pros avai...
B&H Photo has the 13″ 2.6GHz/256GB Retina MacBook Pro on sale for $1379 including free shipping plus NY sales tax only. Their price is $120 off MSRP. Read more
Previous-generation 15-inch 2.0GHz Retina Mac...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros now available for $1599 including free shipping plus NY sales tax only. Their price is $400 off original MSRP. B&H... Read more
21″ 2.7GHz iMac available for $1179, save $12...
Adorama has 21″ 2.7GHz Hawell iMacs on sale for $1179.99 including free shipping. Their price is $120 off MSRP. NY and NJ sales tax only. Read more
iOS 8 Adoption Rate Slower than iOS 7, 6, Hit...
Apple began pushing out iOS 8 updates to eligible devices around 1pm ET on September 17, 2014. However, unlike with iOS 7, which boasted a wide variety of differences from its predecessor iOS 6, in... Read more
LIkely Final Definitive OS X 10.9.5 Mavericks...
Apple has released what will almost certainly be the last incremental version number update of OS X 10.9 Mavericks (save for futire security updates) before OS X 10.10 Yosemite is released next month... Read more
Fingerprints, Apple Pay and Identity Theft Wa...
On Sep 9th, CEO Tim Cook unveiled Apple Pay, along with the new iPhone 6 and iWatch. Apple Pay is a newly developed technology that utilizes a near field communication (NFC) to enable customer... Read more
Amazon Introduces Two All-New Kindles
Amazon on Thursday introduced the 7th generation of its Kindle dedicated e-reader device: Kindle Voyage, its top-of-the-line e-reader, and the new $79 Kindle, with a 20% faster processor, twice the... Read more
Save up to $300 on the price of a new Mac wit...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.