Cocoa Dev Central

by Brock Brandeberg

It's very easy to implement a basic HTML help system in a Cocoa application. The Cocoa frameworks automatically provide your application with a help menu, complete with a menu item that will launch the Apple Help Viewer and bring up your HTML based help.

Figure 1. The Cocoa Help Menu

All that you need to do is:

1. Produce your HTML help content and add it to your Project Builder project
2. Place a single meta tag into the header of the desired HTML title page
3. Add a few key-value pairs to the Info.plist file in Project Builder

Once you've done this, your application's help system will magically work.

// Getting Started

Start by creating your HTML help content using an external HTML editor and save all of your files into a single root folder. It's good practice to keep your naming conventions consistent throughout your project and all of its resources, so you should name the root folder something like "MyApp Help." If you need help designing your help content, look at Designing a Help Book under "Apple Help Tasks" inside "Providing User Assistance With Apple Help" for more information.

Figure 2. A sample help system root folder

Now, open your title page in the HTML editor and add the following meta tag to the header. The meta tag should contain two name-value pairs as shown below. The first is "name" with a value of "AppleTitle". The second is "content" with a value that is a string of your choice. Note that this content value string will appear in the Help Center listing as the entry for your application.

<meta name="AppleTitle" content="MyApp Help"></meta>

Again, it's good practice to keep your naming conventions consistent, but the name of your folder and the name of the content value string don't have to be the same if you don't want them to be.

Once you have designed your book, named your root folder and added the meta tag, you should create a search index for it. Simply drop your root folder onto the Apple Help Indexing Tool and it will scan the folder and create an index file inside the folder. The index file must remain in the folder for the index to work correctly. If you need additional help with indexing, look at Using the Apple Help Indexing Tool under "Apple Help Tasks" inside "Providing User Assistance With Apple Help" for more information.

Figure 3. Sample root folder with index file

Now, add your help folder to your Project Builder project as a subfolder of Resources. To do this, simply select the "Resources" folder in the "Files" tab, then choose "Add Files..." from the "Project" menu. Select your help folder and choose the radio button "Create Folder References for any added folders" in the sheet so that the entire folder (including all subfolders) is added to the project.

Figure 4. Help folder added to Project Builder resources

Finally, add a CFBundleHelpBookFolder key-value pair, a CFBundleHelpBookName key-value pair and a CFBundleIdentifier key-value pair to the Info.plist file. Like associating an icon with an application, these Info.plist keys allow Apple Help services to register your help book with your application.

To add these key-value pairs, you will need to use the "Expert" option in the "Application Settings" tab of the target settings because the "Simple" option lacks text entry fields for these keys. If a key doesn't already exist, simply add it using the "New Sibling" button. Type in the new key name then double-click on its value to enter the new string value. The value of the CFBundleHelpBookFolder key should be the folder name of your help folder. The value of the CFBundleHelpBookName key should be the "content" value that you entered in the meta tag of your title page. (Note: You may see an old legacy NextStep tag called NSHelpFile if you browse through the Info.plist files of other application bundles, but don't be tempted to use this deprecated tag).

The value of the CFBundleIdentifier key is used by the operating system to identify applications uniquely, so you will need to assign one to your application if you have not already done so. To ensure that there are no naming conflicts, Apple strongly recommends that bundle identifiers be the same form as Java package names. This is your company’s unique domain name followed by the application or library name, such as "com.mycompany.myapp." For more detailed information, look at The Preferences System under "Software Configuration" in "Inside Mac OS X: System Overview".

Figure 5. Info.plist keys in Project Builder

At this point, you're pretty much done. Run your application, choose "MyApp Help" from the "Help" menu and Help Viewer should launch and display your HTML title page. If you press the "?" button at the bottom of Help Viewer, the viewer will switch to the Help Center listing and you should see the entry for your application listed there.

// Conclusion

You can add more bells and whistles if you like, such as a custom icon for your entry in the Help Center listing. Look at Designing a Help Book under "Apple Help Tasks" in "Providing User Assistance With Apple Help" for more information on this. In addition, there are other help system options available such as multiple help menu items, registering multiple help books or linking to help docs at remote URLs, but these options are typically beyond the needs of most applications. If you need these types of features, look at Providing User Assistance With Apple Help and the Cocoa Online Help programming topic.