Integrating Custom Help Pages to the SharePoint 2007 Help System

• Download sample - 125.78 KB

Introduction

We know that Microsoft SharePoint 2007 ships with an integrated help system. If you have never seen the integrated help, click on the top right image, which will bring up the help page in a popup Window. Most of the times, we want to provide our own help pages to the site which we are developing based on SharePoint. Instead of developing our own help management system, it is wise to integrate our custom help pages with the SharePoint built-in help system.

Understanding the SharePoint Help System

The SharePoint built-in help pages are collection of help collection(HC). Some of the help collection are MS.OSS.HC, MS.WSS.HC and MS.WSS.Admin.HC. Every help collection consists of one manifest (*.manifest) file, metadata (*.xml) file for each helpItem, content file for help topic, image, JS, and CSS and a helpmap (*.xml) file.

Manifest File

This is the heart of every help collection.The manifest file defines the available help items and its relationship in the help collection. Every object, like help topic, help category, image, CSS, JS is represented as helpItem in the manifest file.

The following different types of helpItem are currently available:

• HelpCategory: Represents a group of topics. Generally the help topics are grouped into category and sub-category. A help category can have one or more subcategory or help topics.
• HelpTopic: Represents a single help page in the application, e.g. Customize Web Parts.
• HelpContext: Represents a help context. This is used to provide context sensitive help for pages. For example MS_WSS_ItemLevelPermissions.
• HelpImage: Represents an image. The images used in the help pages, help topic, are represented as helpImages. The help system fetches the corresponding image display when we request a help topic.
• HelpCss: Represents the *.css file used in the help pages. We have no need to include this as usual in the *.htm pages. The help system does this for us.
• HelpSc<code>ript: Represents the *.js files used in the help pages. It works the same as helpCss.

The following extract is from the MS.OSS.manifest file, which represents help pages for Microsoft Office SharePoint Server.

 1 <?xml version="1.0"?>
 2 <helpCollection>
 3     <name>OSSEndUser</name>
 4     <id>MS.OSS.manifest</id>
 5     <changedDate>2006-09-13 23:41:54Z</changedDate>
 6     <createdDate>2006-09-13 23:41:54Z</createdDate>
 7     <author>Microsoft</author>
 8     <version>11.0.9313.4</version>
 9     <lcid>1033</lcid>
10     <defaultHelpItem>MS.OSS.HA10108748</defaultHelpItem>
11     <brandingImage />
12     <rootCategory>MS.OSS.CL10074912</rootCategory>
13     <feedback show="False" />
14     <helpItems>
15         <helpItem>
16             <id>MS.OSS.HA01160950</id>
17             <parents>
18                 <parent sortOrder="0" primary="true">MS.OSS.CH10176039</parent>
19             </parents>
20         </helpItem>

21         <helpItem>
22             <id>MS.OSS.HA01160951</id>
23             <parents>
24                 <parent sortOrder="1" primary="true">MS.OSS.CH10176039</parent>
25             </parents>
26         </helpItem>

27         <helpItem>
28             <id>MS.OSS.HA01160962</id>
29             <parents>
30                 <parent sortOrder="11" primary="true">MS.OSS.CH10176040</parent>
31             </parents>
32             <relatedItemsPointingToMe>
33                 <item sortOrder="1">MS.OSS.HA01160960</item>
34             </relatedItemsPointingToMe>
35         </helpItem>
36         <!-- Other help items here -->
37     </helpItems>
38 </helpCollection>

Some of the important elements in the above manifest file are:

• <lcid>: The locale Id of the help collection. 1003 is for English.
• <rootCategory>: The root category for the help collection. This helpItem is parent for all the main categories in the help collection.
• <helpItem>: Represents each help item in the help collection.
• <parent>: The parent help item for this help Item. An help item can have more than one parent, so that the help item can participate in more than one help category. The sort order specifies, the position of the help item when it is displayed under this parent. For example, if help item (category) A is parent for helpItem B & C, then you define them like this:

01         <helpItem>
02             <id>MS.OSS.B</id>
03             <parents>
04                 <parent sortOrder="0" primary="true">MS.OSS.A</parent>
05             </parents>
06         </helpItem>

07         <helpItem>
08             <id>MS.OSS.C</id>
09             <parents>
10                 <parent sortOrder="1" primary="true">MS.OSS.A</parent>
11             </parents>
12         </helpItem>

In the above example the helpItem B will be displayed first, then helpItem C.

• <relatedItemsPointingToMe>: This element is used to achieve two different functionalities. One is to display list of helpItems, help topics, in the "See also" section. The other one is to map an HelpContext Item (more on this later).

Metadata Files

For every helpItem element in the manifest file, there is one metadata file, which describes the helpItem. This metadata files tell whether the helpItem is a helpCategory, helpTopic, helpImage, or helpContext.

helpCategory looks like this:

1 <?xml version="1.0"?>
2 <helpCategory>
3   <name>Math and trigonometry</name>
4   <id>MS.OSS.CH10176039</id>
5   <createdDate>2006-09-13 23:41:54Z</createdDate>
6   <changedDate>2006-09-13 23:41:54Z</changedDate>
7   <author>Microsoft</author>
8   <version>11.0.9313.4</version>
9 </helpCategory>

helpTopic looks like this:

 1 <?xml version="1.0"?>
 2 <helpTopic>
 3   <name>Manage and share Web Parts and Web Part Pages</name>
 4   <id>MS.OSS.HA10024106</id>
 5   <createdDate>2006-09-13 23:41:55Z</createdDate>
 6   <changedDate>2006-09-13 23:41:55Z</changedDate>
 7   <author>Microsoft</author>
 8   <version>11.0.9313.4</version>
 9   <contentFileExtension>htm</contentFileExtension>
10   <keywords>
11     <keyword>WebPartProxy</keyword>
12     <keyword>WPPMaintenance</keyword>
13   </keywords>
14 </helpTopic>

helpContext looks like this:

1 <?xml version="1.0"?>
2 <helpContext>
3   <name>MS_WSS_ItemLevelPermissions</name>
4   <id>MS.OSS.MS_WSS_ItemLevelPermissions</id>
5   <createdDate>2006-09-13 23:41:55Z</createdDate>
6   <changedDate>2006-09-13 23:41:55Z</changedDate>
7   <author>Microsoft</author>
8   <version>11.0.9313.4</version>
9 </helpContext>

helpImage looks like this:

 1 <?xml version="1.0"?>
 2 <helpImage>
 3   <name>0225_ZA06044838.gif</name>
 4   <id>MS.OSS.0225_ZA06044838</id>
 5   <createdDate>2006-09-13 23:41:55Z</createdDate>
 6   <changedDate>2006-09-13 23:41:55Z</changedDate>
 7   <author>Microsoft</author>
 8   <version>11.0.9313.4</version>
 9   <contentFileExtension>gif</contentFileExtension>
10 </helpImage>

In the metadata, the filename really doesn't mater, only the extension and the content matter. But generally the filename will be the combination of Id and extension. The id value should match with the helpItem's Id value otherwise the help collection will not be installed properly. The name is used to display in the help category and help topics.

Content Files

Every helpTopic, HelpImage, HelpCss, and HelpScript in the help collection have a corresponding content file. For helpTopic it is a *.htm file. HelpContext and HelpCategory will not have any content files.

To include an image in the HTM file, use the following syntax:

<IMG src="helpContent.aspx?id=MS.OSS.0225_ZA06044838&lcid=1033" >

We do not need to do anything special for including the CSS and JS files. If it is part of the help collection, it will be added to the page when we request for a particular help topic by the SharePoint help system.

The HTM file should not be defined as the conventional *.htm file. Rather the file should only contain the content and should not contain the HTML or body element. the real HTML file is constructed by the SharePoint help system and this content is included as part of the generated HTML file and rendered to the client.

Help Collection Folder Structure

The manifest, metadata, and content files should be placed in a specific structure, then we have to create a *.cab file from these files. For example the help collection for MS.OSS is as follows.

A root folder, name it as MS.OSS.HC. It contains two sub folders, and the MS.OSS.Manifest.xml file. The sub folders are content and metadata. The metadata folder contains metadata files in XML format. The content folder contains all other contents.

CAB Files

The SharePoint help system requires a CAB file as input for each help collection. so we have to create a CAB file from the above said files. We can use the cabsdk from Microsoft and use the following commandline option to create the CAB file.

cabarc -r -p n MS.OSS.HC.cab *.*

Installing the CAB File to the SharePoint Help System

Once we have the CAB file, we can use the HCINSTAL.EXE, which is available in <12Hive>\Bin directory. We can either install one or all the help collection. The CAB file can be placed anywhere and the path can be given as an argument to hcinstal.exe. But we can place the CAB file in the <12hive>\HCCab\1033 folder and use the following command to install the help collection.

Hcinstal.exe /act InstallAllHCs

The above console application returns 4 if the help collection is installed properly. If nothing is done, this will return 32. When something is wrong with the help content, it will return 256.

What Happens When Installing the CAB File

when we use the HCinstal console application to install the CAB file, lots of interesting things are going on behind the scenes. The manifest file is parsed and checks whether a meta data is available for a particular helpItem. Based on this manifest file, a fresh manifest file is created and kept in the Central administration site.

Go to the Central Administration site -> view all site content -> helpFold (document library). This is document library which is populated when we install the help content. The help content is placed in a different folder like, manifest, metadata, content for each locale.

When you click on the Manifests folder, you will see all the installed help collections in the SharePoint system.

In the above image we can see every help collection installed in SharePoint. The first one, abc.xyz.manifest, is the custom help pages which I installed on my machine.

In addition, the content folder contains all the HTM, image, CSS, and JS files. The metadata folder contain all the metadata files.

To re-install the help collection, delete the item from the above manifest and try to install using the HCinstal console application.

Once we installed properly, the CAB file is not required further and is no longer used by the SharePoint help system. All the help request is served from this HelpFold document library.

HelContext or Context-Sensitive Help

Context sensitive help in SharePoint is implemented using:

• Helpmap file for each helpcollection
• HelpContext help item, and
• Associating the helpcontext with an helptopic

The helpmap files reside in the 12hive\TEMPLATE\XML\HELP folder. The following extract is from Oss.xml file, which is the helpmap file Office SharePoint Server help collection.

 1:  <helpmaps>
 2:    <helpmap>
 3:      <key>AboutGroups</key>
 4:      <collectionId>MS.OSS.manifest</collectionId>
 5:      <contextId>MS.OSS.AboutGroups</contextId>
 6:    </helpmap>
 7:    <helpmap>
 8:      <key>AboutSubsites</key>
 9:      <collectionId>MS.OSS.manifest</collectionId>
10:      <contextId>MS.OSS.AboutSubsites</contextId>
11:    </helpmap>
12:    <!-- other help mapgs -->
13:  <helpmaps>

The Key element represents the helpcontextkey, the CollectionId element represents the helpcollection to which the helpcontext belongs to. And the ContextID is used to define Helpcontext helpitem in the manifest file and helpcontext metadata.

The key is used to override the default help pages for each page in a site. For example, when you click the help icon in the right corner on your site, it will bring up the following helppages.

To override this with your page or category, you can override the helpcontext key declaration in the ASPX file as follows:

1:  <script type="text/javascript" language="JavaScript">
2:         var navBarHelpOverrideKey = "YourHelpContextKey";
3:  </script>

For more on this overriding, have a look on Chris O'Briens's blog here.

When you request the helppage for a helpcontext key, if the helpcontext key is associated with an helptopic, the help topic will be displayed. For example, when you click the Learn about managing permission settings, in the List settings -> Advanced settings you will be shown the helptopic for "Manage permissions for a list, library, folder, document, or list item".

The help context for item level permission is defined in the helpmap file as follows.

1:  <helpmap>
2:      <key>MS_WSS_ItemLevelPermissions</key>
3:      <collectionId>MS.OSS.manifest</collectionId>
4:      <contextId>MS.OSS.MS_WSS_ItemLevelPermissions</contextId>
5:  </helpmap>

A helpitem for this is also declared in the manifest file and the same is associated with another helptopic helpitem within the relatedItemsPointingToMe element as follows:

 1:  <helpItem>
 2:        <id>MS.OSS.HA10021564</id>
 3:        <parents>
 4:          <parent sortOrder="4" primary="true">MS.OSS.CH10118094</parent>
 5:          <parent sortOrder="4" primary="true">MS.OSS.CH10124858</parent>
 6:          <parent sortOrder="4" primary="true">MS.OSS.CH10178838</parent>
 7:        </parents>
 8:        <relatedItemsPointingToMe>
 9:          <item sortOrder="1">MS.OSS.HA10021494</item>
10:          <item sortOrder="1">MS.OSS.HA10021579</item>
11:          <item sortOrder="1">MS.OSS.HA10098376</item>
12:          <item sortOrder="1">MS.OSS.HA10100149</item>
13:          <item sortOrder="1">MS.OSS.HA10113018</item>
14:          <item sortOrder="1">MS.OSS.MS_WSS_ItemLevelPermissions</item>
15:        </relatedItemsPointingToMe>
16:      </helpItem>

So when we request with a helpcontext key like this http://servername:4050/_layouts/help.aspx?Lcid=1033&Key=MS_WSS_ItemLevelPermissions, It looks for the key in the sitemapfile, and takes the collectionId and contextId. When it finds the helpcontext is associated with an helptopic, as explained above, it renders the particular helptopic. When the helpcontext is declared only in the helpman file and there is no related entry in the manifest file and metadata file, the root category for that helpcontext gets displayed.

The Sample Help Pages

A sample help page includes two help categories, three help topics and a help context. After you install, you can use this URL http://servername:4050/_layouts/help.aspx?Lcid=1033&Key=HelpContext_SampleA, to bring up the following sample helpcontext page.

When you click the "Sample Application Help and How-to, you will be shown the following two categories.

When you click Sample category A, you will be shown the list of topics for this category.

Installing the Sample Help Pages

To install the sample help pages (for that matter, any custom help pages), just follow these simple steps:

1. Copy the ABC.XYZ.HC.cab file to the 12hive\HCCab\1033 folder
2. Copy the Abc.Xyz.xml file to the 12hive\TEMPLATE\XML\HELP folder
3. Install the CAB file using the above mentioned Hcinstal.exe