Giving Your SharePoint Users Site-Specific Online Help

"Press F1 for Help" has been ingrained into the psyche's of PC users since even before Windows. OK, WordPerfect users originally had to press F3 instead, but the concept is the same.

In any case, SharePoint allows you to take advantage of this convention through its page event model. Page-level scripting in SharePoint has received a big boost in attention recently. Ever since Microsoft has announced its endorsement of JQuery in Visual Studio, articles are popping up all over as people learn to leverage this new framework. This is not one of those articles.

Introducing the WPSC

Instead, this is about one use of a component that has been a part of SharePoint (under various names) since it was called the Digital Dashboard Resource Kit - The Web Part Page Services Component (WPSC). I devote a whole chapter in my book to using this and other client-side components, but briefly, the WPSC is a set of JavaScript objects and functions that allow Web Parts to communicate with SharePoint, each other, and your users.

One of these functions allows you to register for events. These events can be defined in other Web Parts, or pre-defined by SharePoint. This example uses one of the pre-defined events - "onhelp". In essence, the WPSC watches for users to press the F1 key, and then raises this event so that any interested components on the page can respond to it.

Making it Happen

In general, working with a WPSC event requires two things:

1. Registration for the event
2. A function to execute when the event is raised (this is called an "event handler" or a "callback function")

For a help function, you will also want a page to contain the help information. You can create this page any way you like, but you might find it useful to make a Wiki Library for your help files. This makes them easy to update and expand as needed. For purposes of this example, let's assume you have a Wiki Library called "MyHelpLib", and the primary help page for this topic is "MyHelp.aspx".

1. The first thing you need to do is add a Content Editor Web Part to your page. From the Site Actions menu, select Edit Page:
   
2. Select a Web Part Zone, and cick the Add a Web Part link.
3. From the Add Web Parts dialog, select the Content Editor Web Part, and click the Add button. (It will probably be in the "Miscellaneous" section)
    
4. Once the part is added, click the "open the tool pane" link in the part:
   
5. Instead of clicking the "Rich Text Editor" button, we're going to click the "Source Editor" button.
   
6. The Source Editor is just a text entry window, with a Save and a Cancel button.
   
7. The code shown in the screen shot is correct, but here it is in plain-text form, which you can copy and paste into your text-entry window: <script language="javascript">
   function showMyHelpPage() {
   window.open('/MyHelpLib/MyHelp.aspx','MyApplicationHelp')
   }
   WPSC.RegisterForEvent("urn:schemas-microsoft-com:dhtml","onhelp",showMyHelpPage);
   </script>
8. Click Save.
9. There is one more change to make before we're ready to exit edit mode. So that this web part doesn't show up on the page, you want expand the Appearance section of the task bar, and change the the "Chrome Type" to None.
   
10. Click the Apply button, and the Exit Edit Mode link.

At its most basic, that's all there is to it! Pressing the F1 key on your page will now summon the help page you defined.

Taking it Further

Of course, that doesn't prevent you from getting even fancier. For example, you may want to set some parameters so your help window is a certain size, and centered on the screen. Once you have the basics set up the way you like them, you could export the Web Part to a .DWP file, and add it to the site's Web Part Gallery. Or, instead of using the script in a Web Part, you might put it into a master page, so it is available throughout your site without further intervention.

The following script is one you might place in shared Web Part or a master page. It adds the formatting parameters, but it also uses a variable for the "help context".

    <script language="javascript">
     var myHelpContext = '/MyHelpLib/MyHelp.aspx';
    function showMyHelpPage() {
     var width  = 500;
     var height = 400;
     var left   = (screen.width  - width)/2;
     var top    = (screen.height - height)/2;
     var params = 'width='+width+', height='+height;
     params += ', top='+top+', left='+left;
     params += ', directories=no';
     params += ', location=no';
     params += ', menubar=no';
     params += ', resizable=no';
     params += ', scrollbars=no';
     params += ', status=no';
     params += ', toolbar=no';
     newwin=window.open(myHelpContext,'MyApplicationHelp', params);
     }
     WPSC.RegisterForEvent("urn:schemas-microsoft-com:dhtml","onhelp",showMyHelpPage);
    </script>

This myHelpContext variable allows you to override which page is displayed by setting it on individual pages. In a web part, you just edit the myHelpContext variable for the page you are on. If the main script is embedded in a master page, you would just add a Content Editor Web Part (as described above) with a very short script block:

In either case, pressing F1 gives that page's help.

Conclusion

In this article, I have given you a taste of the power available to you with the SharePoint client-side scripting model, and the Content Editor Web Part. We used the event model to provide traditional, F1, Help to your users. But the Web Part Page Services Component (WPSC) gives you access to many other functions as well. You can find many of them documented in the Windows SharePoint Services SDK, and you can see more examples of how to use them in my book. I hope you will take this to heart, and discover even more ways of using the SharePoint client-side programming model!