Extending Help

Microsoft® Windows® SharePoint™ Services provides you with the ability to extend the online help system to add help information about your implementation of Windows SharePoint Services or procedures required by your organization. To modify or extend the help system, you must be a member of the local Administrators group on the Web server.

About the Windows SharePoint Services help system

Windows SharePoint Services help system provides assistance to site users in these ways:

• Assistance text in the user interface.   The text in the user interface provides the first level of assistance to Windows SharePoint Services users. If you add a new page to the site, there should be a paragraph at the top explaining the purpose of the page. If you add user interface controls, text on the pages should guide the user through using the controls.
• "More information on" links to help from user interface text.   When you don't have room on the page for all you need to explain to users, use a "More information on <subject>" link in the user interface to point to a custom help topic. In some cases in Windows SharePoint Services, the actual link text is "Show me more information."
• Context-sensitive help link on the top link bar.   In most cases, the Help link on the top link bar brings up a help topic that explains how to use the page. If a page requires more than one hyperlink, a summary topic contains links to all topics that apply to the page.

The "More information on" and context-sensitive links work by using scripted links in the user interface and an XML mapping file. For more about this subject, see "About mapping to help topics from the user interface."

Note that the user interface does not have links to all help topics in the Windows SharePoint Services help system. There are many concept, procedural, and troubleshooting topics that are accessible only through the table of contents and index.

Location of the help files on the server

Windows SharePoint Services help components reside in folders containing the actual help content and the XML mapping file. One copy of the help files is installed per server, so users from all sites hosted by the server see the same help files.

In the file system, the default location of the US English language help files is (where C: represents the drive where the Windows SharePoint Services files are installed):

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI\HELP\1033\STS\

The content folder has a Web address of:

http://<servername>/_vti_bin/help/1033/sts/

There are two subfolders in the \STS folder, \HTML and \IMAGES. The HTML folder contains help files in .HTM content as well as supporting .CSS and .JS files. The IMAGES folder contains graphics files for the help system.

By default, the XML mapping files reside in the following folder:

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\TEMPLATE\XML\HELP\STS.XML

There is one XML mapping file for all languages.

The folder "1033" indicates that this is the US English version of the help. If you have multiple language packs installed on the server, there will be other directories. The following table lists the available language packs and their corresponding identification number.

About mapping to help topics from the user interface

All help links use scripted code to pass a unique keyword to an ASPx page that redirects the link to a help topic that is specified in an XML mapping file (STS.XML). This allows developers to remap these links without making changes to the Windows SharePoint Services user interface.

To create your own mapping, make your own XML mapping file with a unique name, and place it in the same directory as STS.XML. The precedence for determining which help file appears is as follows:

• Windows SharePoint Services searches for a keyword match in all custom XML mapping files. XML mapping files are scanned alphabetically by name.
• If no keyword match is found in the custom XML mapping files, Windows SharePoint Services searches for a keyword match in STS.XML.
• If no keyword match is found, Windows SharePoint Services scans alphabetically through all custom XML mapping files for the first valid mapping to the "helphome" keyword.
• If no valid mapping for "helphome" is found, Windows SharePoint Services uses the "helphome" mapping in STS.XML.
• If the "helphome" mapping in STS.XML is invalid, the topic WSTOC.HTM appears.

If a custom XML mapping file contains a mapping that fails because the path to the topic specified is incorrect or the file doesn't exist, the Windows SharePoint Services equivalent help topic appears (if it exists).

Note  For performance and stability reasons, do not edit the STS.XML file. Create your own copy of the file and edit it as needed. In your copy of the XML mapping file, remove any of the default mappings that you are not overwriting. You must then place your renamed file in the same folder as STS.XML.

Keyword mappings use the syntax:

<helpmap>
   <key>KEY_NAME</key>
   <url>PATH/TOPIC_NAME.HTM</url>
</helpmap>

"KEY_NAME" represents the keyword included in the help link and "PATH/TOPIC_NAME.HTM" represents the path and name of the target help topic under the current language-specific folder. For US English language files, the default location of this folder is:

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI\HELP\1033

Because this mapping is relative to each localized folder, any mapping changes apply to all language versions of the help files. So any mapping and content changes that you make to one language version of the help files must be repeated for each language installed on the server.

For example, the mapping for the help link on the Windows SharePoint Services home page is:

<helpmap>
   <key>wssmain</key>
   <url>sts/html/cshmpg.htm</url>
</helpmap>

Adding "More information on" links

To create a "More information on <subject>" link on your page, use the syntax:

<A  HREF=javascript:HelpWindowKey("KEY_NAME")>LINK_TEXT</A>

For example:

<A  HREF=javascript:HelpWindowKey("NEW_FEATURE")>More information on this feature.</A>

You must then add the keyword and create a mapping in your XML mapping file as described in the previous section.

Mapping the main help link on a page

The help link in a Windows SharePoint Services top link bar points to the topic mapped to the keyword "NavBarHelpHome." By default, this keyword is mapped to WSTOC.HTM. To change this setting for a single page, insert a help override key into the <BODY> section of your page using the syntax:

<script>
var navBarHelpOverrideKey = "KEY_NAME";
</script>

For example, the override key used on the site home page is:

<script>
var navBarHelpOverrideKey = "wssmain";
</script>

Adding and customizing help topics

To prevent your customizations from getting overwritten due to updated help files being installed with a service pack, you should create a copy of the Windows SharePoint Services help files in a separate folder on the server drive and make your changes there. You can then use a custom XML mapping file to point to your version of the help. Complete these steps:

• Copy all the contents of the HTML and IMAGES folder into a new folder at the same level in the server's file structure. For example:

  C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI\HELP\1033\CUSTOM_HELP\
  

• Place your own topic files in the same directory.

  Note  Do not edit the .JS files in the directory. Doing so can cause Windows SharePoint Services help features to fail for all site users on the server.

• Edit the table of contents file (WSTOC.HTM) and index (stsindex.htm) to point to the combination of Windows SharePoint Services and custom help topics that you want your users to see. The table of contents uses expando code. For information about using expandos, see "Adding an expando to a topic" later in this topic.

• Make a copy of the XML mapping file (STS.XML), rename it (for example CUSTOM_HELP.XML), and place it in the same folder with STS.XML. Windows SharePoint Services scans the directory for additional mapping files alphabetically, and uses the first keyword match that it finds. STS.XML is always scanned last.

• Edit your copy of the XML mapping file to change any mappings that you want to point to your help folder. For example, to change the target topic for the help link on the site home page, you would change:

  <helpmap>
     <key>wssmain</key>
     <url>sts/html/cshmpg.htm</url>
  </helpmap>
  

  to:

  <helpmap>
     <key>wssmain</key>
     <url>CUSTOM_HELP/html/cshmpg.htm</url>
  </helpmap>
  

Adding an expando to a topic

Expandos are sections of text that expand and collapse when the user clicks on them. They are used extensively on the help home page (WSTOC.HTM) and throughout the help system. To use expandos in your help topics you'll need the following:

• The code in the header of the help topic to call the expand/collapse functions in the sExpCollapse.js file.
• The code to expand or collapse all expandos near the top of the body section of any topics that use expandos. This control is needed for accessibility reasons.
• The text that appears when the expando is collapsed must be contained in a special <A> link tag.
• The text that appears when the expando is expanded must be placed within specially coded <DIV> tags.

Code calling sExpCollapse.js

Make sure the following code is placed in the header section of the help topic:

<script type="text/javascript" language="Javascript" src="sExpCollapse.js"></script>

Expand all/Collapse all control

Place the following code in the <BODY> section of the topic after the table that holds the code for the top navigation bar and before the <H1> and <Title> tags.

<div id="divShowAll" STYLE="display:block;" align="right">
<a href="javascript:AlterAllDivs('block');" class="DropDown">
<img id="picHeader" border="0" src="../img/expandtri.gif" alt="Show All">Show All</a></div>
<div id="divHideAll" STYLE="display:none;" align="right">
<a href="javascript:AlterAllDivs('none');" class="DropDown">
<img id="hide" border="0" src="../img/collapsetri.gif" alt="Hide All">Hide All</a>
</div>

This code will already be present in any Windows SharePoint Services help topics that already have expandos. However, you will need to add it to any new topics that you create.

Creating an expando

Expandos use the syntax:

<p>
<a class="DropDown" href="javascript:ToggleDiv('divExpCollAsst_<UNIQUE_NUMBER>')">
<img src="../img/blueup.gif" border="0"
id="divExpCollAsst_<UNIQUE_NUMBER>_img">Title for expando</a>
</p>
<div class="ACECollapsed" border="0" id="divExpCollAsst_<UNIQUE_NUMBER>">
<p>Text to appear in the body of expando when it is expanded.</p>
</div>

Add the code to your topic where you want the expando to appear, and then replace the text for the title and body of the expando. <UNIQUE_NUMBER> identifies the places where each expando must have the unique number identifier in that topic for that expando. The numbers do not need to be sequential, and need to be unique only within the scope of the current topic. For example:

<p>
<a class="DropDown" href="javascript:ToggleDiv('divExpCollAsst_2')">
<img src="../img/blueup.gif" border="0"
id="divExpCollAsst_2_img">Customizing the home page</a>
</p>
<div class="ACECollapsed" border="0" id="divExpCollAsst_2">
<p>This is the home page for your site. It is made up of Web Parts that show you views of the
lists and libraries in your site.  You can add more Web Parts to this page, change the layout of
this page, or change the settings for the Web Parts. The links below tell you how.</p>
<ul>
<li><a href="dwpdem.htm" id="SP01025935" lcid=" ">Overview of Web Part Pages</a></li>
<li><a href="dmwp.htm" id="SP01003446" lcid=" ">Modify Web Parts</a></li>
</ul>
</div>