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
$98.81
Apple Inc.
-0.37
MSFT
$45.76
Microsoft Corpora
-0.14
GOOG
$564.44
Google Inc.
-3.83

MacTech Search:
Community Search:

Software Updates via MacUpdate

TextSoap 7.4.2 - Flexible text editing u...
TextSoap is for people who work with text. TextSoap effortlessly cleans up text from endlessly different formats. Wash away unwanted characters, spaces, tabs. Fix paragraphs with hard returns at the... Read more
Dropbox 2.10.30 - Cloud synchronization...
Dropbox is an application that creates a special Finder folder that automatically syncs online and between your computers. It allows you to both backup files and keep them up-to-date between systems... Read more
Twitter 3.1 - Official Twitter client fo...
Twitter (was Tweetie) is a Twitter client with a variety of features. Important Note: As of January 2011, AteBit's Tweetie application has been acquired and renamed by Twitter. Version 1.2.8 of the... Read more
Cocktail Family License (5 Macs) 7.6.1 -...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Cocktail 8.0 Beta 2 - General maintenanc...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
QuickBooks 2015 16.0.0.1352 R1 - Financi...
QuickBooks 2015 helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save.... Read more
Mac DVDRipper Pro 5.0.1 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
Apple OS X bash Update 1.0 - Fix for sec...
The OS X bash Update fixes a security flaw in the bash UNIX shell on OS X 10.9.5 (also on OS X 10.8 and 10.7 [see Related Links below]). OS X 10.9.5 or later Downloads for OS X 10.8 and OS X 10.7 in... Read more
SyncTwoFolders 2.0.5 - Syncs two user-sp...
SyncTwoFolders simply synchronizes two folders. It supports synchronization across mounted network drives and it is a possibility to run a simulation showing in a log what will be done. Please visit... Read more
FinderPop 2.5.7 - Classic Mac utility, n...
FinderPop is a Universal preference pane that extends OS X's contextual menus using a FinderPop Items folder much as the Apple Menu Items folder used to do for the Apple menu. It has other features... Read more

Latest Forum Discussions

See All

A.R. Witham on Black Jack – The ‘World’s...
iBooks and the Kindle app do a great job of ensuring that there’s always something new to read while you’re on the move. They work well in complementing the traditional physical book. There’s still room for more interactive and animated fare though... | Read more »
Kawaii Killer Plushy Edition (Games)
Kawaii Killer Plushy Edition 1.22 Device: iOS Universal Category: Games Price: $2.99, Version: 1.22 (iTunes) Description: Kawaii Killer is an intuitive & fun game taking place in the Kawaii Forest, which is plagued by evil... | Read more »
Ms.Pac-Man Goes Pink for National Breast...
Ms.Pac-Man Goes Pink for National Breast Cancer Foundation Campaign Posted by Ellis Spice on October 2nd, 2014 [ permalink ] | Read more »
The Maze Runner Review
The Maze Runner Review By Lee Hamlet on October 2nd, 2014 Our Rating: :: A NICE CHANGE OF PACEUniversal App - Designed for iPhone and iPad The Maze Runner is a surprisingly enjoyable movie tie-in that will succeed in keeping... | Read more »
RPG Soul of Deva (Games)
RPG Soul of Deva 1.0.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.0 (iTunes) Description: SPECIAL PRICE56% OFF(USD 8.99 -> USD 3.99)!!! Demons attack humans, and humans live in fear of them...Set off on a... | Read more »
Banner Saga (Games)
Banner Saga 1.0.17 Device: iOS Universal Category: Games Price: $9.99, Version: 1.0.17 (iTunes) Description: NOTE: The Banner Saga does NOT run on iPhone 4. iPhone 4S and more modern devices recommended. | Read more »
Beatbuddy HD (Games)
Beatbuddy HD 1.0.2 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.2 (iTunes) Description: **IMPORTANT** Beatbuddy runs only on iPhone 6, 6 Plus, 5, 5c, 5s, iPad 4, iPad Mini Retina and iPad Air. | Read more »
Spirits of Spring (Games)
Spirits of Spring 1.0.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: From the creators of the award-winning empathy game, Papo & Yo, comes a tale about finding strength. | Read more »
I am a brave knight (Games)
I am a brave knight 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Do you have ten minutes to live a life? | Read more »
iKeywi - Customizable 5-Row Keyboard (U...
iKeywi - Customizable 5-Row Keyboard 1.0 Device: iOS Universal Category: Utilities Price: $.99, Version: 1.0 (iTunes) Description: Want to add an extra row to your iPhone/iPad? One of the most popular keyboard extension in iOS... | Read more »

Price Scanner via MacPrices.net

Apple drops prices on refurbished 27-inch iMa...
The Apple Store has dropped prices on Apple Certified Refurbished 27″ iMacs, now available for up to $340 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27... Read more
Logitech Type+ iPad Air Keyboard Case: Laptop...
If you want to make your iPad Air look and feel more like a laptop for productivity use, as well as protect it from impacts, spills, and scratches while on the move, the new Logitech Type+, a... Read more
ASUS, Lenovo, and Amazon Slug It Out For Tabl...
According to market intelligence firm ABI Research, Apple and Samsung have led the touchscreen tablet market by a substantial margin since Apple energized the category back in 2010. However, ABI says... Read more
Branded Tablet Growth Expected to Disappoint...
ABI Research says the 200 million annual shipments milestone for branded tablets continues to elude OEM vendors, and overall growth for 2014 is set to come in at a disappointing 2.5 percent. Apple... Read more
Amazon offers 13-inch MacBook Air for $899, $...
Amazon.com has the 13″ 1.4GHz 128GB MacBook Air on sale for $100 off MSRP including free shipping: - 13″ 1.4GHz 128GB MacBook Air: $899.99 Read more
Apple resting On Its iPhone Laurels? – The ‘B...
Apple calls its new iPhone 6 and 6 Plus “The Biggest Advancements in iPhone History,” but does reality live up to the hype? “Seldom have so many waited so breathlessly for so little,” tweeted veteran... Read more
Roundup of Apple Mac and iPad Education disco...
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
Apple Boycotts German Magazine Computer Bild...
Apple has revoked its PR accreditation of Germany’s Computer Bild, Europe’s best-selling PC magazine, in reaction to Bild’s posting of a “#Bentgate” YouTube video. Axel Telzerow, editor in chief of... Read more
iPhone 6 & iPhone 6 Plus Available in Chi...
Apple has announced that iPhone 6 and iPhone 6 Plus will be available in China beginning Friday, October 17 from the Apple Online Store (http://www.apple.com), Apple’s retail stores, and an expansive... Read more
MacBook Airs on sale for $100 off MSRP, start...
Best Buy has the new 2014 MacBook Airs on sale for $100 off MSRP on their online store. Choose free home shipping or free local store pickup (if available). Prices valid for online orders only, in-... 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
*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
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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.