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:

Advertisement

 

Customizing the SharePoint Help System : Part 1

Help in SharePoint is available by clicking the blue Help Icon at the top right of every standard page:

SharePoint Help files open in a new window and are delivered from a system Document Library called HelpFold which can be seen under View All Site Content of the Central Admin site:

The HelpFold document library is organized into a series of folders as follows:

Within these folders Help content is organized by language code (for example 1033 for US-EN) and then scope (MOSS, WSS, Central Administration, Search etc).

So in principle, it should be possible to customize this content in order to add your own help topics and content, which may relate say to your corporate environment or to customizations which have been made to SharePoint. It is not advisable to edit the contents of this document library directly, however, nor would it, I suspect, be supported. The way to customize the Help within SharePoint is to do so at the level of the source CAB files which are used to populate the document library shown above.

Help source CAB files

SharePoint Help files are loaded into the HelpFold Document Library from compressed CAB files which are stored under the following path:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\HCCab\1033

A standard MOSS server installation will have the following Help cab files:

The list above includes a custom help cab MS.OSS.CUSTOM.cab which will be used to provide an example of how to add custom help content.

If you uncompress a cab file, by using Windows Explorer and right-clicking to Extract, the contents should be extracted to two folders named content and metadata, in line with the Path attribute. The manifest.xml, prefixed by the help collection name should be saved to the root folder above content and metadata. As you would expect, content in the form of actual help files in .htm format plus images, css and javascript files are stored in the content folder. All metadata is stored in the metadata folder and consists of xml files describing categories, sub-categories and topics, plus descriptions of image and htm files. The whole thing is described in the manifest.xml file which contains all the relationships between the metadata and the content.

Making sense of a large help file can be difficult as every element is related together by keys which are not particularly meaningful to the human eye. An essential tool when modifying a help file in SharePoint is available from http://www.blackcompass.com : their SharePoint Help Collection Builder.

This little program, which is free to download, provides a clear picture of the structure of the different elements in the help system and allows relatively easy editing, plus the option of creating and installing the final cab file on the SharePoint server.

Though there is nothing to prevent the editing and customization of the standard Microsoft help content for SharePoint, this is not advisable for two reasons. Should Microsoft update their help contents for SharePoint, following a service pack or security patch, then your customizations will be lost. And in terms of maintenance, it is much simpler if all customizations are kept in a separate cab file which can then be edited without fear of corrupting the official help content for SharePoint.

Fortunately, one help collection can refer to and include another, so long as all follow the same structural principles. The best practice for customizing the help system in MOSS, for example, would be to simply include a reference to your custom help files in MS.OSS.HC.MANIFEST.xml as follows:

<referencedCollections> <collection sortOrder=”9″>MS.OSS.CUSTOM.manifest</collection> </referencedCollections>

As there are 9 existing top-level categories in the default MOSS help system, and the sortOrder begins at “0” you should give your referenced collection a sortOrder of “9” and it will appear at the end of the category list. In my next post, Part 2 of this article, I will explain in more detail how to create and install a custom SharePoint help file and provide an example to download.