Sen's Blog

Today I will start a series of posts to explain SharePoint help collections. As well as how to create, modify and extend SharePoint help collections. 

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

In this post, part 1, we will look at

-> What is SharePoint help collection

-> Where are help collections stored

-> The components of a help collection

-> The structure of a help collection cab

-> How are help page accessed

What is SharePoint help collection?

SharePoint (MOSS 2007 or WSS 3.0) has an integrated help system. On most SharePoint pages, on the top right hand corner, you will see an  symbol, click on it, it should bring up a help page, like this:

Also there are places in SharePoint where there is a link to help, like this one:

Click on the link, it will take you a help page specific to that topic, like this:

 These pages are part of a help collection, a help collection is a bunch of html pages, supporting these html pages, there are javascript files, image files, and css files. Out of the box MOSS 2007 ships 7 help collections.

Where are help collections stored

These help pages are stored in a document library in central administration. Go to your central administration site, click on “View all site content” and you will see a document library named “HelpFold”. This folder contains all SharePoint help system.

Here is an explaination of the meaning of these folders:

Content - holds htm files, these are help pages you see

Images - holds images files supporting the htm files

Lock – this folder is used by the help collection installation process, if you see entries in this folder, this means help collection installation is scheduled, this folder does not hold any help collection content

Manifests – holds manifest files of help collection (more on manifest files later)

MetaData - holds meta data files describing every help item (more on help item later)

Support - holds files supporting the help pages, such as javascript files, css files

When you install SharePoint, there is an installation process for the help system. The help system are installed from cab files.  The tool for installing help collection is “HCINSTAL.EXE” under the <12hive>\bin directory. More on this tool later.

Under the 12 hive, there is a folder called HCCab, under this folder, there are locale folders, and help collections are cab files in these folders. For example, I have an en-us installation of MOSS (locale id 1033), my folder is: <12hive>\HCCab\1033, like this:

Each one of these cab files holds one help collection, when you run HCINSTAL.EXE, you can install/uninstall help collections from cab file into SharePoint (to the “HelpFold” document library in central administration). More on this later.

You may ask, “Why not just have one giant help collection”? This is a good questions, I don’t know for sure, but as you can guess from the screenshot above, some of these help collection are intended for WSS. So Microsoft may have split up the collection for different version of the product or modular deployment of different parts of MOSS (such as central administration).

The components of a help collection

 As mentioned above, help collections are html pages with supporting images, javascript files, and images. Each of these is called a help item. A help item can be one of the following.

Help topic - htm file, which is the help page itself

Help script - a javascript file (.js)

Help image - an image file (png, jpg…)

Help css - a style sheet file (.css)

In addition to this, help items are grouped into help context and help category.

 Help category is a collection of help pages, it looks like this:

A help context is like a help category but is not used to visibly group help pages, the main use is to associate key words with a help context, and associate help context with a help item. More on this later.

The structure of a help collection cab

You can just open up these cab file using winrar.

The structure of a help collection cab file as follows:

-> a xml file named <name of the help collection>.Manifest.xml

-> a folder named meta data, in this folder, there are many xml files, each xml file contains meta data for one help item

-> a folder name “content”, this folder holds the real content (htm files, css files, js files)

All help collections are structured this way.

How are help page accessed?

Once help collections have been installed into central administration, they can be accessed from SharePoint sites. Lets pick a help page in SharePoint, take the example from above:

This is the help page talking about content approvals in document libraries (go to any document library -> settings -> versioning settings). The url of this page is: http://senmossdev/_layouts/help.aspx?Lcid=1033&Key=ContentApproval

This brings us to another interesting point, the help pages are not displayed alone, they are displayed inside of help.aspx, so help htm files are not complete html documents (does not have tags like <html> <head>…etc).

Help.aspx pages takes these query string parameters:

Lcid - the locale id of the help collection

Cid[X] - the id of the help collection, note the [X] variable is an integer, starting from 0, for example:  http://senmossdev/_layouts/help.aspx?lcid=1033&cid0=MS%2EOSS%2EADMIN%2EManifest&tid=MS%2EWSS%2EHA10021413 note this is a ZERO not the letter O. So you can cid0=[something]&cid1=[something else]

Key - the key word associated with a help context, more on help contex later

tid – id of the help item to be displayed

pg – page number, doesn’t seem to be used, if you know a place this parameter is used, please email me

Note not all of these parameters are mandetory, for example, you can just supply the tid parameter to display a help item.

How to reference help image, help css and help script from help pages

From inside of help pages, you can refer to help image, help css, and help javascript by accessing the _layouts/helpcontent.aspx page. Following is an example:

The “helpContent.aspx” takes these query string parameters:

Lcid – the locale id of the help collection

id – the id of the help image, help script or help css

ext – the file extension of the help image, help script or help css, this parameter is optional

 

This is the end of part 1. In part 2, we will take a closer look into the cab file, since you will be creating and modifying these cab files to create/modify help collections.