Customizing the SharePoint Help system : Part 2

To create your own self-contained SharePoint help file, use the Black Compass help collection builder for SharePoint mentioned in my previous post. At the minimum you will require one help topic and one category. In order to illustrate the functionality of referencing another help collection, in this example we will add a further sub-category level which will link to our example help topic and the standard MOSS help collection.

Begin by preparing a help topic file in .htm format. Our example simply contains the text:

Helllo world – your customized SharePoint help collection is working!

You should also add a main category and sub-category to your help file project, as follows:

For each of the elements in the project, the settings can be changed in the panel to the right:

For each element, the program will create the appropriate XML file in the metadata folder. In the case of the Help Topic, it will take whatever file is referenced in the path and rename it in line with the overall project name. What is important to get right is the relationships between the different elements. In this example, Category1 is the root category and Topic1 is the default help item.

Elements are related together by specifying for sub-elements, which are their parents. The parent of Topic1 is Subcat1 and so on.

When you are ready, the program can be used to generate the required CAB file, under the Actions menu. You can also install the resulting CAB file if you are working directly on a SharePoint server by using the requisite option under the Actions menu.

Results are returned based on a code, 4 = success, 32 = no change and 256 = fail.

There is one aspect to the Black Compass program which does not seem to function well, and that is the option to add Referenced Collections under the root. I could not get this work for me and the resulting code would then not install. So I took to adding the Referenced Collection by hand as described in my previous post.

If for any reason you do not want to use Black Compass’s utility, you can do everything by hand. But it gets a little mind-bending keeping track of all the relationships. Within a manual process, you will need to create the CAB file yourself using CABARC for example. You will also have to install the help collection by hand using HCINSTALL in the BIN directory on the SharePoint web front-end. Be sure to Uninstall first if the file already exists. When installing a single help collection file, you will need some extra parameters, for /loc and /mns as described in the help for hcinstal.

I have prepared an example customized CAB file to get you started which can be downloaded here.

It is called MS.OSS.NICK.HC (you can replace the NICK with whatever you like, but make sure to change it all the way through the project) and it has one main category, with two elements, a help topic and a link to the main MOSS server help collection.

For best results, it will be necessary to prepare your .htm file using Microsoft’s help.css. I do not have the time to go into that here, but may be in a subsequent post.

The final results look like this:



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: