Integrating Help into SharePoint 2010 solutions

March 2010

Note: This article is part of a collection of posts from four years of the Get the Point blog for SharePoint end-users.

This post focuses on features that developers and solution-distributors can use to integrate their Help into the SharePoint 2010 Help System.

SharePoint Help Basics

First, a refresher on basics from our previous post:

SharePoint Help is grouped into what we call a "Help collection." A Help collection is simply a collection of HTML files, images, and other resources such as CSS and JS files that apply to a single product or feature. For example, SharePoint 2010 has a Help collection, as does the Word Web App.

There are two kinds of Help collections, and they are stored in different places:

Site collection-specific Help collections are stored in the root web of the site collection (covered in our previous post).
Farm-wide Help collections are stored in Central Admin (covered in this post).

Users can open Help by clicking the Help icon (blue circle with a white question mark). From there, they can search or browse to find the Help they need.

Build and Deliver SharePoint Help

Here are the steps you take to build and then deliver your custom Help:

Create a cabinet file (CAB) that contains all your Help content.
At deployment time, call a PowerShell cmdlet to import the CAB into SharePoint.

We will review how to complete these steps in the next two sections.

Building a Help Collection CAB

Help contents are delivered packaged in a CAB. One CAB contains exactly one Help collection. A Help collection consists of three types of Help items:

Help Articles are the content pages.
Help Categories provide a hierarchical structure to Help.
Help Files are supporting files, such as like images (gifs, jpgs, etc.) as well as JavaScript and CSS files.

These are packaged into a Help collection CAB. There are three parts to a Help collection CAB:

The Manifest is an XML file that sits at the root of the CAB. This XML file contains properties that apply to the Help collection and it contains a manifest of all the items that are part of the Help collection as well as how they relate to each other.
Metadata files are a set of XML files (one per item) that define the properties for that particular Help item.
Content files which are the actual files (HTML, images, JavaScript) that are part of the Help.

All put together, the Help collection CAB looks like this:

integratehelpwithSP2010pk1

Manifest File

At the root of the CAB, there must be a file called "[Help collection product].manifest.xml" — for example, MyBlogHelpCollection.manifest.xml —which contains all the properties for that particular Help collection. Here's a sample of a manifest file and a link to the schema.

<?xml version="1.0"?>

<name>MyHelpCollectionName1033</name>

<id>MyManifest</id>

<author>Blog Post Author</author>

<lcids>

</lcids>

<product>MyProduct</product>

<onlineBrowseUrl>http://myonlinehelp.com/default.aspx?ck={CONTEXTKEY}&lcid={LCID}</onlineBrowseUrl>

<onlineSearchUrl>http://myonlinehelp.com/search.aspx?q={QUERYTEXT}&lcid={LCID}</onlineSearchUrl>

<rootCategory>MyRootCategory</rootCategory>

<id>MyRootCategory</id>

</helpItem>

<id>MyFirstSubCategory</id>

<parent sortOrder="4" primary="true">MyRootCategory</parent>

</parents>

</helpItem>

<id>MyHelpArticle</id>

<parent sortOrder="1" primary="true">MyFirstSubCategory</parent>

</parents>

<item sortOrder="1">MySecondHelpArticle</item>

</relatedItemsPointingToMe>

</helpItem>

<id>sharepointhome</id>

</helpItem>

</helpItems>

</helpCollection>

Here's a description of each element

Element	Description
helpCollection	Root element
name	The name of the Help collection folder to be created. This must be unique for each language.
id	Every xml file in the Help collection CAB has an ID. This must be a unique string for each XML file.
changedDate	This is set as the Last Modified Date when the Help collection is created.
createdDate	This is set as the Created Date when the Help collection is created.
author	This is set as the Author when the Help collection is created.
version	The version for this Help collection. Use this element when you want to be able to deploy an update. The Help importer code will verify that it is importing a new version of the Help.
version	The version for this Help collection. Use this element when you want to be able to deploy an update. The Help importer code will verify that it is importing a new version of the Help.
lcids	The languages this Help collection applies to. For reference, here is a Local ID chart.
product	The unique identifier for this Help collection. This ID must remain the same across localized versions of this Help collection.
hosting	Determines whether this Help collection came from Microsoft.
enabled	Determines whether this Help collection is active or inactive by default. This should be set to false unless your solution is automatically activated or accessible from every site collection. If a site collection feature must be activated for your feature to show up, then set this to false.
version	The version for this Help collection. Use this element when you want to be able to deploy an update. The Help importer code will verify that it is importing a new version of the Help.
lcids	The languages this Help collection applies to. For reference, here is a Local ID chart.
product	The unique identifier for this Help collection. This ID must remain the same across localized versions of this Help collection.
hosting	Determines whether this Help collection came from Microsoft.
enabled	Determines whether this Help collection is active or inactive by default. This should be set to false unless your solution is automatically activated or accessible from every site collection. If a site collection feature must be activated for your feature to show up, then set this to false.
onlineBrowseUrl	If you have a website, you can decide to render Help from your website instead if the Farm Administrator has not disabled that option. This is a full URL and the following tokens will be replaced at runtime:
onlineSearchUrl	This is the full URL if you have a website to host Help on. The following tokens will be replaced at runtime:

Metadata Files

The XML files under the metadata folder contain all the metadata for all the Help Items. Every Help Item defined in the manifest.xml file must have a metadata file – otherwise the CAB will fail to install.

Here's a sample metadata file for each Help Item type as well as a link to the schema:

<?xml version="1.0"?>

<name>My Help Article's Title</name>

<id>MyHelpArticle</id>

<author>Blog Post Author</author>

<contextKey>TestKey</contextKey>

</contextKeys>

</helpTopic>

Help Category

<?xml version="1.0"?>

<name>RSS and alerts</name>

<id>MyFirstSubCategory</id>

<author>Blog Post Author</author>

</helpCategory>

Help File

<?xml version="1.0"?>

<name>sharepointhome.gif</name>

<id>sharepointhome</id>

<author>Microsoft</author>

</helpImage>

Content Files

The actual files (i.e. the HTM files, jpgs, gifs, JavaScript, etc.) are stored in the content folder. Their filenames are determined by the ID and the contentFileExtension elements in their corresponding metadata file.

To use Word to author Help files, take a look at our previous post.

Because you don't know the server name where Help will be deployed, you cannot use absolute paths for JavaScript, images, or links to other files. Instead, you can use the following format:

To Load Images or Scripts

Set the source as:

helpContent.aspx?id=[id]&lcid=[lcid]

For example:

To Link to Other Help Articles or Categories

Set the link as:

help.aspx?tid=[id]&lcid=[lcid]

For example:

<a href="help.aspx?tid=MySecondHelpArticle&lcid=1033">Linked Text</a>

Putting It All Together

Now that we have all the components ready to go, we can build the CAB. To do so, follow these steps:

Before you start, make sure you download the cabsdk from Microsoft. Download this file and expand it.
Create a folder (i.e. MyBlogHelpCollection)
Copy your manifest.xml file into this folder.
Create two new folders called "content" and "metadata".
Copy your metadata files into the metadata folder
Copy your content files into the content folder.
Open a command prompt, and go to the directory you just created (i.e. MyBlogHelpCollection).
Run the following command "cabarc -r -p n MyBlogHelpCollection.cab *.*"

And you are now the proud owner of a Help collection CAB.

Deploying a Help Collection CAB

Now that you have a Help collection CAB, the next step is to deploy it. To deploy a Help collection CAB, you call the following PowerShell cmdlet:

Go to Start > All Programs > Microsoft SharePoint 2010 Products.
Right-click on SharePoint 2010 Management Shell and click Run as administrator.
Type the following cmdlet:
Install-SPHelpCollection –LiteralPath "[full path to the help collection path]"
This cmdlet creates a timer job. Wait for a few minutes. To verify whether your Help collection was successfully installed, run the following cmdlet and look for your help collection:
Get-SPHelpCollection

TroubleshootingTips

• If your CAB was malformed, the Help collection will fail to install. To find out why, take a look at a Timer Job called Help Collection Installer. You can find this in SharePoint Central Administration -> Monitoring -> Check Job Status -> Job History.

• The Help collection installer job runs under its own credentials. Thus, make sure that the CAB file is accessible from the user under which timer jobs are running. If in doubt, give Read access to Everyone.

• If you get an error like this: No manifest .xml file was found under… make sure that the referenced element has a valid manifest file.

Displaying Help

Now that you have successfully deployed your Help collection, it's time to get it to display.

Activating Your Help Collection

If your Help collection is not set to be on by default, you can activate it by running the following object model at Feature activation time:

using Microsoft.SharePoint.Help;

public class YourFeatureReceiver : SPFeatureReceiver

{

// activating the help collection during feature activation

public override void FeatureActivated(SPFeatureReceiverProperties properties)

{

//other activation code

using (SPSite site = properties.Feature.Parent as SPSite)

{

string collectionProduct = "MyBlogHelpCollection";

site.ActivateHelpCollection(collectionProduct);

}

Similarly, at deactivation time, you can call DeactivateHelpCollection.

Opening the Help Viewer

So, you have now created your own Help collection, you've deployed it, and activated it. The last piece of the puzzle is getting the Help Viewer to open to your help collection. There are two ways to do this:

• By overwriting any page's Help context

• Creating your own Help link

Overwriting a Page's Help Context

You can overwrite a Page's Help Context to override the Help button that is shown on the top right of every page.

integratehelpwithSP2010pk1

You can do this by adding the following line to either the masterpage or pagelayout for the page that you want to set the context for:

navBarHelpOverrideKey = "[Product]_[ContextKey]";

navBarHelpOverrideKey = "[Product]";

For example:

navBarHelpOverrideKey = "MyBlogHelpCollection_MyContextKey";

navBarHelpOverrideKey = "MyBlogHelpCollection";

The [Product] part of the key determines which Help collection to show. The [ContextKey] part determines which article or category within that Help collection to point to.

Opening the Help Viewer

If, in addition to the Help icon, you want to add or substitute your own Help entry-point, you can do so by calling the following JavaScript function:

HelpWindowKey('[Product]_[ContextKey]');

HelpWindowKey('[Product]');

Dan Zarzar

Lead Program Manager, Microsoft Assistance Platform Team

Microsoft Office Tutorials

Saturday, December 2, 2017