Sen's Blog

In part 1, we had a look of some basic concepts and structure of SharePoint help collections. In this post, we will have a look inside of a help collection cab file, the structure of it, and what will it take to create/modify one.

BlackCompass offers a free help collection builder, to help you create, modify and deploy help collection. Get your free copy now , there are also full tutorials available.

As mentioned in the first post, the help collection cab files are in this location: <12hive>\HCCab\1033 (or other locale folder).

Let us unzip one of these cab files into a folder using winrar.

The structure of this folder as follows:

A xml manifest file – this is a file describes the help collection, it contains some meta data for the help collection and some meta data for each help item

A folder named “metadata” - this is a folder containing multiple xml files, each xml file is a metadata file describing a single help item in detail

A folder named “content” – this folder contains all the raw .htm, .js .css and image files

Lets look into each one of these

The manifest file

First note the manifest file’s name, it is <help collection name>.Manifest.xml, be sure to follow this format, make sure only use alphanumeric characters and no space in the name, to ensure smooth installation.

Open up the manifest file:

The structure of this file is simple, first, there some tags describing this help collection, such as name and author. A couple of interesting tags:

<rootCategory> – this is the “welcome” help category for  a help collection. For example, http://senmossdev/_layouts/help.aspx?Lcid=1033&cid0=MS.WSS.manifest will bring up this page:

in the above url, I only specified the locale id and the help collection id, what you are seeing is actually help category MS.WSS.CL10074787 (as specified in MS.WSS.Manifest.xml), since this is the default category.

<defaultHelpItem> – this doesn’t seem to be used, usually I just set this id to be the root category id mentioned above

<brandingImage> – doesn’t seem to be used

There are multiple <helpItem> tags , each one describes a help item in the collection, the <parent> tag is used to express a help item belongs to a help category. For example, the screenshot above shows a help category, each link point to a help item. So, in this case, you would specify the parent of the help item be the help category. The order number determines the order of the links.

Help item meta data

The metadata folder contains multiple xml files, each xml file carries metadata for a help item, each help item will have exactly one meta data file.

Lets open up a meta data file and see what’s inside:

Depends on what type of help item it is (help script, help image, help topic…), these tags may vary slightly, but they are very similar to each other. Note the naming of these files follow the format <help item id>.xml

Content folder

This folder holds all the raw content files, htm files for help topic, css files for help css, js files for help script and so on.

 

Note the files are named using this format <help item id>.extension.

Create and modify help collection

From a high level point of view, creating/modifying help collections involves three steps:

-> Manually create/modify the manifest xml, metadata xml or the content files itself.

-> Build a cab file of this folder structure (using cabarc.exe)

-> Install/uninstall the cab file into SharePoint using HCINSTAL.EXE

HCINSTAL.EXE

HCINSTAL.EXE is the command line utility shipped by Microsoft, used to install/uninstall help collections. You can use reflector to open it up and see what’s inside. Basically, installing a help collection is a scheduled job. HCINSTALL.EXE goes through the manifest and metadata xml file and put everything in the right place (central administration)

Type in HCINSTAL.EXE /?? in the command windows will give you advanced documentation on this tool, including all the command line parameters.

A couple of examples:

HCINSTAL.EXE /act InstallOneHC /loc 1033 /mns BC.MOVIETIMES

The above command will install a help collection BC.MOVIETIMES.cab

HCINSTAL.EXE /act InstallallHCs /loc 1033

The above command will install all help collections under the <12 hive>\HCCab\1033 folder

HCINSTAL.EXE returns an integer to indicate result, they are:

4 – OK

32 - No actions (for example, try to uninstall a help collection that doesn’t exist)

256 - Error, unfortunately, it doesn’t return what error it is. However, when you see this, check the SharePoint ULS log under <12hive>\LOGS 

This marks the end of part 2. In the final part, part 3, we will have a look some advanced topics like as context sensitive help, help maps and related help topics.