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

Pixelmator 3.8.1 - Powerful layer-based...
Pixelmator is a beautifully designed, easy-to-use, fast, and powerful image editor for OS X. It has everything you need to create, edit, and enhance your images. Pixelmator is a layer-based image... Read more
Malwarebytes 3.6.21.2055 - Adware remova...
Malwarebytes (was AdwareMedic) helps you get your Mac experience back. Malwarebytes scans for and removes code that degrades system performance or attacks your system. Making your Mac once again your... Read more
iStat Menus 6.31 - Monitor your system r...
iStat Menus lets you monitor your system right from the menubar. Included are 8 menu extras that let you monitor every aspect of your system. Features CPU -- Monitor cpu usage. 7 display modes,... Read more
Unite 2.0 - $9.99
Unite allows you to quickly and easily turn websites into full-featured, native apps on macOS. With Unite 2, we've completely rewritten the backend browser with WebKit 2, enabling support for the... Read more
VueScan 9.6.23 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Thunderbird 60.3.2 - Email client from M...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
Apple Security Update 2018-006 - For mac...
Apple Security Update is recommended for all users and improves the security of OS X. For detailed information about the security content of this update, please visit: http://support.apple.com/kb/... Read more
VueScan 9.6.23 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Apple Security Update 2018-006 - For mac...
Apple Security Update is recommended for all users and improves the security of OS X. For detailed information about the security content of this update, please visit: http://support.apple.com/kb/... Read more
Thunderbird 60.3.2 - Email client from M...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more

Latest Forum Discussions

See All

148Apps year end round-up: These are the...
It's Monday, and our round-up of the best games of 2018 has landed on March. There were some pretty amazing developments in the third month of the year, mainly thanks to the launch of PUBG and the start of the Fortnite beta (technically Fortnite... | Read more »
Twinfold guide
Twinfold may look like a cheap Threes! clone at first glance, but it's so much more than that. It's actually a rather deep roguelite with a really satisfying difficulty curve and almost endless replayability. Since the game's depth does take some... | Read more »
Which of these iPhone and iPad games sho...
On a normal week we like to give you the chance to vote for your game of the week on Thursday. But since this clearly isn't a normal week, we've decided to give you the chance to vote for our game of the week on Friday. You're welcome. [Read more... | Read more »
Munchkin.io ends 2018 in style with a ne...
While it can sometimes seem like we are drowning in a sea of battle royale games, few struggle to actually deliver the kind of fun and frantic experience you’d expect from a refined entry in the genre. Well step aside from those other games because... | Read more »
Choose a side in Rift of Raigard, the ne...
If you’re an RTS player that’s constantly underwhelmed by most genre entries on mobile, or sick of putting up with stingy F2P models and cheaters, Rift of Raigard is the base building game for you. Developed by a team of creators who are equally... | Read more »
148Apps year end round-up: These are the...
Our round up of the best games of the year has rolled along to February. Which makes sense, since we started off with January - click here and you'll be able to read the top 5 in its entirety - and February was definitely a doozy, we can tell you... | Read more »
The top 5 best gifts for mobile gamers t...
Since it's the most wonderful time of the year according to most adverts, and since the most wonderful time of the year is all about the giving and receiving of presents (and probably some other stuff, we guess), we thought it was high time we... | Read more »
Dragalia Lost - Resplendent Refrain Sabn...
Dragalia Lost's latest event, Resplendent Refrain, is an event that favors light Adventurers in an all new raid dungeon. This dungeon has four teams of four face off against the mighty Sabnock, which is probably the toughest raid fight in the game... | Read more »
Dragalia Lost Adventurers' Guide
Want to up your Dragalia Lost game? You've come to the right place. Here at 148Apps, we've been digging deep into Nintendo's latest gacha game to find the best tips, tricks, and strategies to share with all of our future co-op team mates (read: you... | Read more »
148Apps year end round-up: These are the...
We're heading towards the end of the year, which can only mean it's time to start thinking about what games we're going to remember from the last 12 months. And we're going to break it down into a series of top 5s, one for each month. We're... | Read more »

Price Scanner via MacPrices.net

21 Days Left To Avail Apple $29 Battery Repla...
FEATURE: 12.10.18- There are only 21 days left in 2018 before it will be that time once again for making New Year’s resolutions but for a handful of certain iPhone users these next three weeks will... Read more
Get a new 2018 Apple iMac for $100-$220 off M...
B&H Photo has 2018 Apple iMacs on sale for up to $220 off MSRP for Green Monday 2018. Current-generation 21″ models are on sale for $100-$170 off MSRP, and 27″ iMacs are on sale for $200-$220 off... Read more
Amazon offers 9″ 32GB WiFi iPads for $249, $8...
Amazon is offering 9.7″ 32GB & 128GB WiFi iPads with Apple Pencil Support, in Space Gray & Gold, for $80 off MSRP for Green Monday 2018. Silver iPads are on sale for $60 off. These are the... Read more
B&H and Amazon offer 13″ Apple MacBook Pr...
Apple resellers B&H Photo and Amazon are all offering sale prices on new 13″ MacBook Pros ranging up to $200 off MSRP as part of their Green Monday/Holiday 2018 sales. B&H Photo has 13″... Read more
Amazon offers Apple Watch Series 3 GPS + Cell...
Amazon is discounting Apple Watch Series 3 GPS + Cellular models by $50 as part of their Holiday 2018 sales, with 38mm Watches starting at $329. Shipping is free: – 38mm Apple Watch Series 3 GPS +... Read more
Holiday/Green Monday sale: Apple resellers of...
Get a new 2018 15″ Touch Bar MacBook Pro for $300 off MSRP, starting at $2099, at the following Apple resellers today. These are the same models sold by Apple in their retail and online stores: B... Read more
Holiday sale: Get a new 2018 Mac mini for $50...
Apple introduced a new Mac mini in October 2018 with a similar form factor as previous generations but featuring significantly upgraded internals. The new mini comes in a darker Space Gray color and... Read more
Holiday sale! Get a new 2018 13″ MacBook Air...
B&H Photo has new 2018 13″ MacBook Airs on sale for $100-$130 off MSRP, starting at only $1069, as part of their Holiday 2018 sale. Their prices are the lowest available for these new models from... Read more
Holiday 2018 sale: 9.7″ Apple iPads on sale t...
Amazon is offering 9.7″ WiFi iPads with Apple Pencil Support for $60-$80 off MSRP this weekend as part of their Holiday 2018 sale with prices starting at $269. These are the same iPads found in Apple... Read more
Organize Apple Power Adapter Clutter With A F...
FEATURE: 12.07.18- Looking for the perfect gadget to give as a stocking stuffer or gift for the MacBook user in your life that won’t break the bank and can actually help them organize the cable and... Read more

Jobs Board

Geek Squad *Apple* Master Consultation Agen...
**660766BR** **Job Title:** Geek Squad Apple Master Consultation Agent **Job Category:** Services/Installation/Repair **Location Number:** 001021-San Rafael-Store Read more
*Apple* Mobile Master - Best Buy (United Sta...
**659208BR** **Job Title:** Apple Mobile Master **Job Category:** Store Associates **Location Number:** 000806-Seekonk-Store **Job Description:** **What does a Best Read more
*Apple* Mobile Master - Best Buy (United Sta...
**660573BR** **Job Title:** Apple Mobile Master **Job Category:** Store Associates **Location Number:** 000488-Chattanooga-Store **Job Description:** **What does a Read more
*Apple* Mobile Master - Best Buy (United Sta...
**658576BR** **Job Title:** Apple Mobile Master **Job Category:** Store Associates **Location Number:** 001022-Leesburg-Store **Job Description:** **What does a Best Read more
*Apple* Mobile Master - Best Buy (United Sta...
**659661BR** **Job Title:** Apple Mobile Master **Job Category:** Store Associates **Location Number:** 000197-King of Prussia-Store **Job Description:** **What does Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.