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

<meta name=”AppleTitle” content=”MyAppName Help”>

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.


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 ( works on Apple Help and related instructional products.


Community Search:
MacTech Search:

Software Updates via MacUpdate

DEVONthink Pro 2.9.6 - Knowledge base, i...
DEVONthink Pro is your essential assistant for today's world, where almost everything is digital. From shopping receipts to important research papers, your life often fills your hard drive in the... Read more
Safari Technology Preview 10.1 - The new...
Safari Technology Preview contains the most recent additions and improvements to WebKit and the latest advances in Safari web technologies. And once installed, you will receive notifications of... Read more
VueScan 9.5.60 - 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
Civilization VI 1.0.0 - Next iteration o...
Sid Meier’s Civilization VI is the next entry in the popular Civilization franchise. Originally created by legendary game designer Sid Meier, Civilization is a strategy game in which you attempt to... Read more
Adobe Flash Player - Plug-in...
Adobe Flash Player is a cross-platform, browser-based application runtime that provides uncompromised viewing of expressive applications, content, and videos across browsers and operating systems.... Read more
RestoreMeNot 2.0.4 - Disable window rest...
RestoreMeNot provides a simple way to disable the window restoration for individual applications so that you can fine-tune this behavior to suit your needs. Please note that RestoreMeNot is designed... Read more
Persecond 1.0.7 - Timelapse video made e...
Persecond is the easy, fun way to create a beautiful timelapse video. Import an image sequence from any camera, trim the length of your video, adjust the speed and playback direction, and you’re done... Read more
iShowU Instant 1.1.0 - Full-featured scr...
iShowU Instant gives you real-time screen recording like you've never seen before! It is the fastest, most feature-filled real-time screen capture tool from shinywhitebox yet. All of the features you... Read more
Spotify - Stream music, creat...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
HoudahSpot 4.2.6 - Advanced file-search...
HoudahSpot is a powerful file search tool. Use HoudahSpot to locate hard-to-find files and keep frequently used files within reach. HoudahSpot will immediately feel familiar. It works just the way... Read more

Latest Forum Discussions

See All

5 Halloween mobile games for wimps
If you're anything like me, horror games are a great way to have nightly nightmares for the next decade or three. They're off limits, but perhaps you want to get in on the Halloween celebrations in some way. Fortunately not all Halloween themed... | Read more »
The 5 scariest mobile games
It's the most wonderful time of the year for people who enjoy scaring themselves silly with haunted houses, movies, video games, and what have you. Mobile might not be the first platform you'd turn to for quality scares, but rest assured there are... | Read more »
Lifeline: Flatline (Games)
Lifeline: Flatline 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: The Lifeline series takes a terrifying turn in this interactive horror experience. Every decision you make could help... | Read more »
Game of Dice is now available on Faceboo...
After celebrating its anniversary in style with a brand new update, there’s even more excitement in store for Game of Dice has after just being launched on Facebook Gameroom. A relatively new platform, Facebook Gameroom has been designed for PC... | Read more »
4 addictive clicker games like Best Fien...
Clickers are passive games that take advantage of basic human psychology to suck you in, and they're totally unashamed of that. As long as you're aware that this game has been created to take hold of your brain and leave you perfectly content to... | Read more »
Smile Inc. Guide: How not to die on the...
As if Mondays weren't bad enough, at Smile Inc. you have to deal with giant killer donuts, massive hungry staplers, and blasting zones. It's not exactly a happy, thriving work environment. In fact, you'll be lucky to survive the nine to five.... | Read more »
Oh...Sir! The Insult Simulator (Games)
Oh...Sir! The Insult Simulator 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: | Read more »
WitchSpring2 (Games)
WitchSpring2 1.27 Device: iOS Universal Category: Games Price: $3.99, Version: 1.27 (iTunes) Description: This is the story of Luna, the Moonlight Witch as she sets out into the world. This is a sequel to Witch Spring. Witch Spring 2... | Read more »
4 popular apps getting a Halloween makeo...
'Tis the season for all things spooky. So much, so, in fact, that even apps are getting into the spirt of things, dressing up in costume and spreading jack o' lanterns all about the place. These updates bring frightening new character skins, scary... | Read more »
Pokémon GO celebrates Halloween with can...
The folks behind Pokémon GO have some exciting things planned for their Halloween celebration, the first in-game event since it launched back in July. Starting October 26 and ending on November 1, trainers will be running into large numbers of... | Read more »

Price Scanner via

Worldwide Smartphone Shipments Up 1.0% Year o...
According to preliminary results from the International Data Corporation (IDC) Worldwide Quarterly Mobile Phone Tracker, vendors shipped a total of 362.9 million smartphones worldwide in the third... Read more
TuneBand Arm Band For iPhone 7 and 7 Plus Rel...
Grantwood Technology has added the TuneBand for iPhone 7 and 7 Plus to its smartphone armband series. The TuneBand provides a lightweight and comfortable way to wear the iPhone while running,... Read more
1.4GHz Mac mini on sale for $449, save $50
Adorama has the 1.4GHz Mac mini on sale for $50 off MSRP including free shipping plus NY & NJ sales tax only: - 1.4GHz Mac mini (Apple sku# MGEM2LL/A): $449 $50 off MSRP To purchase a mini at... Read more
21-inch 1.6GHz iMac on sale for $999, save $1...
B&H has the 21″ 1.6GHz Apple iMac on sale for $999 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Macs’ Superior Enterprise Deployment Cost Eco...
IBM’s debunking of conventional wisdom and popular mythology about the relative cost of using Apple Mac computers as opposed to PCs running Microsoft Windows at the sixth annual Jamf Nation User... Read more
12-inch WiFi Apple iPad Pros on sale for $50-...
B&H Photo has 12″ WiFi Apple iPad Pros on sale for $50-$70 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 12″ Space Gray 32GB WiFi iPad Pro: $749 $50 off MSRP -... Read more
Apple refurbished 12-inch 128GB iPad Pros ava...
Apple has Certified Refurbished 12″ Apple iPad Pros available for up to $160 off the cost of new iPads. An Apple one-year warranty is included with each model, and shipping is free: - 32GB 12″ iPad... Read more
Apple refurbished iPad minis and iPad Air 2s...
Apple recently dropped prices on several Certified Refurbished iPad mini 4s and 2s as well as iPad Air 2s. An Apple one-year warranty is included with each model, and shipping is free: - 16GB iPad... Read more
MacHTTP-js Preview Full-featured Web Server f...
MacHTTP.Org has released MacHTTP-js Preview for macOS, a full-featured Web server for 21st Century desktops and servers. MacHTTP-js is a modern take on the classic stand-alone, desktop computer Web... Read more
Samsung Galaxy Tab A 10.1 with S Pen Makes US...
Samsung Electronics America, Inc. has announced the release of the Galaxy Tab A 10.1 with S Pen in a highly mobile, lightweight tablet. “With an embedded S Pen, consumers can discover more ways to... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Software Engineering Intern: UI Applications...
Job Summary Apple is currently seeking enthusiastic interns who can work full-time for a minimum of 12-weeks between Fall 2015 and Summer 2016. Our software Read more
Security Data Analyst - *Apple* Information...
…data sources need to be collected to allow Information Security to better protect Apple employees and customers from a wide range of threats.Act as the subject Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 52812872 Houston, Texas, United States Posted: Oct. 18, 2016 Weekly Hours: 40.00 **Job Summary** As an Apple Solutions Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.