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
$104.94
Apple Inc.
+1.95
MSFT
$45.41
Microsoft Corpora
+1.03
GOOG
$546.88
Google Inc.
+14.17

MacTech Search:
Community Search:

Software Updates via MacUpdate

Art Text 2.4.8 - Create high quality hea...
Art Text is an OS X application for creating high quality textual graphics, headings, logos, icons, Web site elements, and buttons. Thanks to multi-layer support, creating complex graphics is no... Read more
Live Interior 3D Pro 2.9.6 - Powerful an...
Live Interior 3D Pro is a powerful yet very intuitive interior designing application. View Video Tutorials It has every feature of Live Interior 3D Standard, plus some exclusive ones: Create multi... Read more
The Hit List 1.1.7 - Advanced reminder a...
The Hit List manages the daily chaos of your modern life. It's easy to learn - it's as easy as making lists. And it's powerful enough to let you plan, then forget, then act when the time is right.... Read more
jAlbum Pro 12.2.4 - Organize your digita...
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.4 - Create custom photo gall...
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
ExpanDrive 4.1.7 - Access remote files o...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
OmniOutliner Pro 4.1.3 - Pro version of...
OmniOutliner Pro is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It'... Read more
Evernote 5.6.2 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
OmniOutliner 4.1.3 - Organize your ideas...
OmniOutliner is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It's... Read more
BBEdit 11.0 - Powerful text and HTML edi...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more

Latest Forum Discussions

See All

Puzzle to the Center of the Earth Review
Puzzle to the Center of the Earth Review By Campbell Bird on October 23rd, 2014 Our Rating: :: SPELUNKING PUZZLESUniversal App - Designed for iPhone and iPad Do some puzzles to make some platforms in this smart and fun free-to-play... | Read more »
Sleep Attack TD Review
Sleep Attack TD Review By Jennifer Allen on October 23rd, 2014 Our Rating: :: A TRUE TWISTUniversal App - Designed for iPhone and iPad Sleep Attack TD is a tower defense game with a difference – you can rotate the layout – and it’s... | Read more »
Earn Your Master Camper Badge in Camp Po...
Earn Your Master Camper Badge in Camp Pokemon Posted by Jessica Fisher on October 23rd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Garruk Gets His Revenge in a New Magic 2...
Garruk Gets His Revenge in a New Magic 2015 Expansion, Coming This November Posted by Jessica Fisher on October 23rd, 2014 [ permalink ] | Read more »
Sentinels of the Multiverse Review
Sentinels of the Multiverse Review By Rob Thomas on October 23rd, 2014 Our Rating: :: SENTINELS ASSEMBLEiPad Only App - Designed for the iPad Greater Than Games’ tabletop classic, Sentinels of the Multiverse swoops in to save the... | Read more »
Build Your Own Fantasy Football Dynasty...
Build Your Own Fantasy Football Dynasty with Draft Day Posted by Jessica Fisher on October 23rd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Cars: Fast as Lightning – Tips, Tricks,...
Hey there, Stickers: Want to know all about how impressed we were with Radiator Springs? Check out our Cars: Fast as Lightning review! Cars: Fast as Lightning is a cute and fun app that combines racing and town-building with the charisma and... | Read more »
Jam Messenger Review
Jam Messenger Review By Jennifer Allen on October 23rd, 2014 Our Rating: :: SIMPLE MESSAGINGiPhone App - Designed for the iPhone, compatible with the iPad Want a very quick way to send push-based messages? Jam Messenger is basic... | Read more »
Felllice (Games)
Felllice 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: EXCLUSIVE PRICE DROP! 50% OFF FOR A LIMITED TIME! EAT EAT EAT AND GROW ! | Read more »
The Arrow Game: by Grazie Media (Games)
The Arrow Game: by Grazie Media 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Guide a flying arrow through skyscrapers and city streets to hit a distant target. Experience an endless... | Read more »

Price Scanner via MacPrices.net

Save up to $125 on Retina MacBook Pros
B&H Photo has the new 2014 13″ and 15″ Retina MacBook Pros on sale for up to $125 off MSRP. Shipping is free, and B&H charges NY sales tax only. They’ll also include free copies of Parallels... Read more
Apple refurbished Time Capsules available sta...
The Apple Store has certified refurbished Time Capsules available for up to $60 off MSRP. Apple’s one-year warranty is included with each Time Capsule, and shipping is free: - 2TB Time Capsule: $255... Read more
Textilus New Word, Notes and PDF Processor fo...
Textilus is new word-crunching, notes, and PDF processor designed exclusively for the iPad. I haven’t had time to thoroughly check it out yet, but it looks great and early reviews are positive.... Read more
WD My Passport Pro Bus-Powered Thunderbolt RA...
WD’s My Passport Pro RAID solution is powered by an integrated Thunderbolt cable for true portability and speeds as high as 233 MB/s. HighlightsOverviewSpecifications Transfer, Back Up And Edit In... Read more
Save with Best Buy’s College Student Deals
Take an additional $50 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through November 1st. Anyone with a valid .EDU email address can take advantage... Read more
iPad Air 2 & iPad mini 3 Best Tablets Yet...
The new iPads turned out to be pretty much everything I’d been hoping for and more than I’d expected.”More” particularly in terms of a drinking-from-a-firehose choice of models and configurations,... Read more
Drafts 4 Reinvents iOS Productivity App
N Richland Hills, Texas based Agile Tortoise has announced the release of Drafts 4 for iPhone and iPad. Drafts is a quick capture note taking app with flexible output actions. Drafts 4 scales from... Read more
AT&T accepting preorders for new iPads fo...
AT&T Wireless is accepting preorders for the new iPad Air 2 and iPad mini 3, cellular models, for $100 off MSRP with a 2-year service agreement: - 16GB iPad Air 2 WiFi + Cellular: $529.99 - 64GB... Read more
Apple offering refurbished Mac Pros for up to...
The Apple Store is offering Apple Certified Refurbished 2013 Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more
Select MacBook Airs $100 off MSRP, free shipp...
B&H Photo has 2014 a couple of MacBook Airs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels Desktop and LoJack for... Read more

Jobs Board

Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
*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
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.