TweetFollow Us on Twitter

Apr 02 Cover Story

Volume Number: 18 (2002)
Issue Number: 04
Column Tag: User Experience

Apple Help and AppleScript Studio

by Gordon R. Meyer

Providing Help Systems for AppleScript Studio-based Applications

Apple Help and Aqua

AppleScript Studio is an exciting prospect for Scripters - we are no longer limited to creating the usual droplets or faceless utilities commonly associated with scripting language development.

But power and opportunity come at a price. AppleScript Studio development also "raises the bar" on expectations for how your application looks and behaves. Like any other application on Mac OS X, following the Aqua Human Interface Guidelines will ensure your new application provides an excellent user experience. This article focuses on one aspect of Aqua - providing onscreen user assistance with Apple Help.

Virtually every application needs a help system, and using Apple Help is an easy and fundamental step in adopting Aqua. To get started all you need is a set of HTML help files and this article. Aside from the time spent writing the help content, you can implement a working help system in minutes.

What is Apple Help?

Apple provides the Help Viewer application for displaying your help content. The Help Viewer is optimized for providing onscreen help. It displays HTML 3.2, any QuickTime media you care to use, and it can run AppleScript automations to assist users in accomplishing complex or common tasks. (Because AppleScript Studio-based applications are already scriptable by default, there is a lot of opportunity to enhance your help with useful automations. Something to consider after you've gotten your first-cut at Help implemented.)

The Help Viewer also provides a built-in search engine that quickly gives relevancy ranked search results for your help, and all the help installed on the user's computer. Shortly, you'll learn how to ensure your help content is searchable.

When your application adopts Apple Help, it will be automatically listed in the Help Center. The Help Center allows users to view and search an application's help without having to open the application. It's a great way to find out which applications can handle a special task that you have in mind.

There are more Apple Help features such as automatically building "table of contents" files or the ability to mix locally-stored and Internet-based content. For information about them, see Providing User Assistance with Apple Help. If you prefer to watch and listen instead of reading, the WWDC 2001 streaming video of the Apple Help session also introduces all the features and capabilities.

What type of information should you include in your help? Making good onscreen help is a whole article by itself, but the "Help" chapter in Aqua Human Interface Guidelines has some discussion, as does the WWDC 2001 session. If you would like some guidance consider using these resources.

For the purposes of this article, don't worry about all the bells and whistles, just get your content into HTML 3.2 format. You can repurpose existing files from your Web site, or use whatever HTML authoring tool you normally use and create the help from scratch.

Preparing Your Help Files

After you've written your help, you need to make one minor addition to identify the "start page" (or "home page) for your help book and provide the title of your help system for the Help Center.

You do both by adding one META tag to the start page for your book. This is typically the table of contents page, or the splash page, or whatever page you want users to see when the Help Viewer opens. If you're re-using content from your Web site, it might be the index.html file, for example.

Listing 1: AppleTitle example

<html>
<head>
<meta name=”AppleTitle” content=”MyAppName Help”>
   […]
</head>
<body>
   […]
</body>
</html>

The content of the AppleTitle tag is the name of your help book. This is the name that gets listed in the Help Center, and it's how Apple Help identifies which book to open from your application's help menu. The Aqua HI Guidelines recommend that you use the form "MyAppName Help".

Making your help searchable

The search engine in Help Viewer is fast. It can search hundreds of pages of help in just seconds, returning a list of the most relevant topics in your help book. To accomplish this it uses a pre-generated index file. To make your help searchable, which is strongly recommended for the best user experience, you use the Apple Help Indexing Tool. Please don't forget this important step, users get frustrated if they can't locate information by searching. (Indexing is also required if you're using some of the advanced features, such as Anchor Lookup, as described in the Apple Help documentation.)

The Apple Help Indexing Tool is installed in /Developer/Applications/. To use it, simply drop your folder of help files onto the tool. The Indexing Tools quickly scans all the pages and creates the search index file in the correct location.


drag-and-drop to enable searching

That's all there is to it. You can get fancier if you'd like, by adding keywords or changing the way some topics are indexed, but for most uses all you have to do is use the default Indexing Tools settings and drag-and-drop your help folder.

Add Your Help to Your Project

By adding the META tag and creating a search index you have finished everything you need to do to your help content. Next, you add the help files to your application's package and tell Cocoa you have a help system.

Importing into Project Builder

In Mac OS X help files are stored in an application's bundle. This keeps everything tidy - help always travels with the application when it's installed or moved on disk - and with Mac OS X's multi-lingual support it permits you to have localized help along with the application itself.

Select the Resources folder in Project Builder, and then choose Add Files from the Project menu. Select the main folder of your help content and turn on the option to create folder references, and then click the Add button.


Select this option when importing your help folder.

Your help folder is now listed in the Resources list.


Help files added to a project.

Add Help to the Property List

Choose Edit Active Target from the Project menu. Then click the Application Settings tab to display the settings for your build.

In the Basic Information section, specify a bundle identifier. See Inside Mac OS X: System Overview for more detail, but in brief you specify a unique identifier for your application using Java-style naming.


Enter a bundle identifier

Click the Expert button in the top right corner of the settings pane. This allows you to edit the Property List directly.

Click the New Sibling button, then edit the new entry so the key is CFBundleHelpBookName and the value is a string that matches the contents of the AppleTitle tag that you put in your HTML.

Add another new sibling called CFBundleHelpBookFolder with the value being the name of your help folder that you previously imported. In our example both key values are the same because the folder where we store our help files is named the same as our book. That's not a requirement, but it is conventional.


Specifying the help book and folder names

Edit The Help Menu

You're in the home stretch now. The last task is to rename the default Help menu that is automatically created for your application. You don't have to do anything to make the menu work; Cocoa provides the functionality automatically because of the changes you made to your property list.

In Project Builder, double-click your interface definition file (MainMenu.nib, unless you've changed it) to open it in Interface Builder.

In the menu layout, change the Help item to match the name of your help book. The Aqua guidelines recommend the form "MyAppName Help". Note that you automatically get the correct keyboard shortcut, courtesy of Cocoa.


Edit the Help menu item.

That's it, you're done! Build your app and try it out. When you select your new Help menu the Help Viewer will launch and open to your book. If it doesn't work make sure that the property list values match up with the appropriate AppleTitle and help folder names. Also check that you remembered to enter a bundle identifier for your application.

Your AppleScript Studio-based application is now one step closer to providing a great Aqua user experience and useful help for your customers. And, along the way, you've learned how to implement a help system for any Cocoa application.

Bibliography

Aqua Human Interface Guidelines
Help Chapter

Providing User Assistance with Apple Help

Apple Help Reference

Apple Help WWDC session 125, Mac OS Track
Streaming video from Apple Developer Connection (Membership required. Log in, then choose View ADC TV)

Inside Mac OS X: System Overview


Gordon Meyer (gordon@apple.com) works on Apple Help and related instructional products.

 
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.