Customizing Help
| SharePoint's online help (see Figure 5.14) replicates the functionality of a CHM file. It offers context-sensitive help and provides a CHM-like user interface. Unfortunately, it lacks the capacity to do keyword searches. Unlike a CHM file, SharePoint's online help system is easily extensible. As such, this extensibility lends itself to implementing a keyword system of your own or just about anything else. Figure 5.14. SharePoint Help for the Create Page. Every online help page is in fact an HTML page. Modifying the content is as simple as modifying an HTML file. Adding additional content is also just as easy. Underpinning this system are STS.XML and client-side JavaScript. STS.XML provides a mapping of predefined keys to URLs. The JavaScript on SharePoint web pages uses those predefined keys to look up appropriate help. This is how clicking Help on the Documents and Lists page will return specific help for documents and lists, while clicking Help on the Create page will return specific help for the creation of Lists, Libraries, and Web Pages. Help File BasicsSharePoint maps the physical folder C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\ISAPI\HELP to the virtual folder http://<servername:port>/_vti_bin/help. These folders contain help for Windows SharePoint Services and SharePoint Portal Server. The folder hierarchy is detailed in Table 5.3, while an example of the virtual mapping is shown in Figure 5.14.
It should be noted that there are more than HTML and image files in the help folders. The HTML help folders also hold JavaScript and CSS files. For example, CS0002.HTM, listed in Listing 5.9, references one CSS and two JavaScript files. Listing 5.9. CS0002.HTM (Create Page Help) <Head> Partial Listing
Because all the help files reference a CSS, formatting changes to the help files can be made easily. Changing the text formatting, background color, or just about any other style changes only requires a simple change to the CSS file. The commonness of resources among pages also exists for JavaScript code. Perhaps the most used JavaScript function is ToggleDiv, which is defined in SEXPCOLLAPSE.JS and was referenced in Listing 5.9. It expands and collapses high-level topics so the user is not overwhelmed with choices. For instance, the function in the Create page help shown in Figure 5.14 is used to expand and collapse the three subtopics(1) Learn about libraries, lists, discussion boards, surveys, workspaces and sites; (2) Create lists, surveys, discussion boards, or libraries; and (3) Create Web pages, sites, and Workspaces sites. Microsoft cleverly refers to these expandable lists as expandos. In Listing 5.10, we examine the first expando in the Create page's online help. Clicking on the topic executes ToggleDiv with the id of the div to expand or collapse. Listing 5.10. CS0002.HTM (Create Page Help) Partial Listing
Customizing Help Files and Context-Sensitive Help (STS.XML)It almost goes without saying that a future service pack might update the help files. Thus, your modifications to the online help system could be overwritten and lost. In fact, WSS SP2 updated one of these help filesWSAPSUBC.HTM. Therefore, it is recommended that the entire help system be copied and accessed from another folder when customizations are desired. Let's walk through an example of modifying the Windows Share-Point Services help. The first step is to make a copy of the STS folder in C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI\HELP\1033. Name the newly copied folder STS-2005. Next, we modify CS0002.HTM to replace the text Microsoft Share-Point Products and Technologies Assistance Center (refer to Figure 5.14) with Microsoft's SharePoint site (see Figure 5.15). As shown in Listing 5.11, change the URL and text. The resulting web page is displayed in Figure 5.15. Listing 5.11. Modified CS0002.HTM (Create Page Help) Partial Listing
Figure 5.15. SharePoint Create Page Help with updated link. To capture the image for Figure 5.15, we manually navigated to the STS_2005/HTML virtual folder. Now the question is how to link help pages to our SharePoint pages. The answer is through the mapping interface that SharePoint provides. These mappings exist in the C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\XML\HELP folder. SPSMAP.XML defines the default mappings for Share-Point Portal Server help, and STS.XML defines the default mappings for Windows SharePoint Services help. However, we want to define custom mappings in our own file. SharePoint constructs a dictionary of mappings for all files in the C:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\XML\HELP folder. The custom files are parsed in alphabetical order, and then the SharePoint default files (SPSMAP.XML and STS.XML) are parsed. Thus, if A.XML, B.XML, and STS.XML all have the same mappings defined, the values in A.XML will take precedence over the other files. To create our custom mapping file, we copied STS.XML and renamed it STS_2005.XML. Next, we changed the STS path to STS_2005. This change ensures that our modified HTML files will be used instead of the SharePoint default help files. Listing 5.12 details the new STS_2005.XML. It consists of a series of key and url mappings. The mapping for the CreatePage is also included in the snippet. Listing 5.12. STS_2005.XML (Modified Version of STS.XML)
Now you must be asking, how are the keys embedded within CREATE.ASPX and other web pages? The answer is JavaScript functionality. You might recall the navigation bar defined in ONET.XML. In case you don't, it is shown in Listing 5.13. It defines the Url for Help as executing the HelpWindowKey function with a key of NavBarHelpHome. As defined in Listing 5.12, this will map to STS_2005/HTML/WSTOC.HTM. In essence, clicking on the navigation bar's Help link will launch the help table of contents. Listing 5.13. Default ONET.XML Top Navigation Bar
However, the navigation bar's NavBarHelpHome key can be overridden within a web page. For instance, the CREATE.ASPX page that has been the focus in this section uses this navigation bar but overrides the default value through the navBarHelpOverrideKey JavaScript variable. The override through JavaScript is shown in Listing 5.14 and specifies that the CreatePage key should be used in lieu of any default key. Listing 5.14. CREATE.ASPX Overriding the NavBarHelpHome Key
Of course the Help link on the top navigation bar doesn't hold exclusivity when launching help. You could call the HelpWindowKey function from any place on the page. You would pass the desired key as a parameter to the HelpWindowKey function. After executing an IISReset, our new help system will be used instead of the SharePoint online help system. As mentioned previously, the STS_2005.XML file trumps the same keys defined in STS.XML. This is why the CreatePage key will be mapped to the url defined in STS_2005.XML rather than STS.XML. One interesting aspect of these mappings happens when a specified key cannot be found. In that case, the helphome key is used in its place. Just as with other keys, the custom mapping files take precedence over SharePoint's default STS.XML and SPSMAP.XML. Now that you understand the help system, any deficiencies it might have in your enterprise can be remedied. Just remember to avoid making direct changes to SharePoint's default help files because your good work might be erased with the next service pack. |
EAN: 2147483647
Pages: 64