Project

Once you have access to an online help file, you have access to every page of it. That's usually a good thing, because users are curious. (I mean, they are inquisitive, and not merely objects of curiosity.) But in the case of the Library Project, that curiosity could lead to topics that are really no business of ordinary patrons. Most of the features in the Library application are for administrative use only. To keep things as calm as possible, the Library Project includes two online help files.

• LibraryBasic.chm. A patron-focused help file that describes only the parts of the program the patron can access.

• LibraryAdmin.chm. A file targeting administrators and librarians that fully describes the features of the application.

This chapter's project section builds both of these online help files, and integrates them into the Library application.

Building the Help Files

I've written the content for both online help files for you. You'll find it all in the Online Help subdirectory in the primary install directory for this book, with distinct directory branches for Basic and Admin files. Figures 23-9 and Figure 23-10 list the files found in each directory.

Figure 23-9. The files for patron-level online help

Figure 23-10. The files for administrator-level online help

Most of the HTML files have a one-to-one link with specific forms in the application. For instance, the ItemLookup.htm file contains the online help content for the ItemLookup.vb form in the application. And this help page shows up in both the basic and administrative versions of the file. When the user presses F1 from the Item Lookup form, the application tries to show the online help page "ItemLookup.htm." If the user is a standard patron, it accesses this page in the LibraryBasic.chm file; administrative users access the same page name, but from the LibraryAdmin.chm file instead.

Each help source folder contains .hhp, .hhc, and .hhk files that define the project, the contents, and the index details respectively. The administrative version also includes a few GIF graphic files.

I've already compiled each file and placed a copy of the .chm file in these directories.

Add Help Support to the Application

To keep things simple and somewhat centralized, we'll employ the ShowHelp method described earlier to display online help for each form in the application. Because of the busy-work nature of the changes involved in this chapter's project code, I've already made all of the updates to the project. Most of the changes involve making the exact same change to every form in the project, all of which I'll describe next.

Project Access

Load the "Chapter 23 (After) Code" project, either through the New Project templates, or by accessing the project directly from the installation directory. This chapter does not include a "Before" variation of the project code.

The Maintenance.vb form already provides a way for the administrator to specify the locations of each online help file. It updates two settings through the My.Settings object.

My.Settings.HelpFile = Trim(RecordBasicHelp.Text) My.Settings.HelpFileAdmin = Trim(RecordAdminHelp.Text) 

Those settings also get stored in two global variables.

MainHelpFile = RecordBasicHelp.Text MainAdminHelpFile = RecordAdminHelp.Text 

That means that we only need to call ShowHelp from each form and access one of the two files whenever the user presses F1.

But what if the administrator never uses the Maintenance.vb form to configure the locations of the help files? Because the help files will probably be installed in the same folder as the Library.exe program file, we should look there automatically. The InitializeSystem method in General.vb already sets the two global variables to the values stored in the settings.

' ----- Locate the online help files. MainHelpFile = My.Settings.HelpFile & "" MainAdminHelpFile = My.Settings.HelpFileAdmin & "" 

Just in case these settings don't exist, let's add code, just after these lines, that provides default access to the files.

If (MainHelpFile = "") Then MainHelpFile = _    My.Computer.FileSystem.CombinePath( _    My.Application.Info.DirectoryPath, "LibraryBasic.chm") If (MainAdminHelpFile = "") Then MainAdminHelpFile = _    My.Computer.FileSystem.CombinePath( _    My.Application.Info.DirectoryPath, "LibraryAdmin.chm") 

Because we need to continuously adapt to the current user state of the application (whether the user is a patron or an administrator), a centralized routine that displays help from the correct file seems best. Here's the code for OnlineHelp, a new method in the General.vb file.

Public Sub OnlineHelp(ByVal whichForm As _       System.Windows.Forms.Form, _       ByVal contextName As String)    ' ----- Show the online help. Differentiate between the    '       basic and the administrative online help usage.    Dim fileToUse As String    ' ----- Which file to use.    If (LoggedInUserID = -1) Then       fileToUse = MainHelpFile    Else       fileToUse = MainAdminHelpFile    End If    If (fileToUse = "") Then       MsgBox("Online help is not properly configured.", _          MsgBoxStyle.OkOnly Or MsgBoxStyle.Exclamation, _          ProgramTitle)       Return    End If    ' ----- Show the online help.    Try      Help.ShowHelp(whichForm, fileToUse, _         HelpNavigator.Topic, contextName)    Catch       MsgBox("An error occurred while trying to access " & _          "the online help file.", MsgBoxStyle.OkOnly Or _          MsgBoxStyle.Exclamation, ProgramTitle)    End Try End Sub 

The biggest task in this chapter involves going to each form in the project and making these two changes.

• Set the form's KeyPreview property to True.

• Add a call to OnlineHelp from the form's KeyDown event handler.

Here's the code added to the ChangeUser.vb form.

Private Sub ChangeUser_KeyDown(ByVal sender As Object, _       ByVal e As System.Windows.Forms.KeyEventArgs) _       Handles Me.KeyDown    ' ----- F1 shows online help.    If (e.KeyCode = Keys.F1) Then _       OnlineHelp(Me, "ChangeUser.htm") End Sub 

A few of the forms process online help requests a little differently from the others. About.vb doesn't include its own online help page. Instead, it displays Welcome.htm. Splash.vb doesn't show any online help because the user isn't really supposed to interact with it. ReportBuiltInViewer.vb, the form that shows each of the five built-in reports, displays help for a related form via ReportSelect.htm. CheckLookup.vb form has two associated online help pages: one for check-out and one for check-in of items. Its KeyDown event handler chooses the right page based on the current mode of the form.

If (e.KeyCode = Keys.F1) Then    If (CheckInMode = True) Then       OnlineHelp(Me, "CheckLookup_In.htm")    Else       OnlineHelp(Me, "CheckLookup_Out.htm")    End If End If 

The Main.vb form is even more diverse, choosing from among nine distinct online help pages when in administrative mode. Each panel on the main form is like a whole separate form, so I added an online help page for each panel. Code in the form's KeyDown event handler shows the right page based on the currently displayed panel.

If (PanelLibraryItem.Visible = True) Then    OnlineHelp(Me, "MainForm_Library.htm") ElseIf (PanelPatronRecord.Visible = True) Then    OnlineHelp(Me, "MainForm_Patron.htm") ElseIf (PanelHelp.Visible = True) Then    OnlineHelp(Me, "MainForm_Help.htm") ElseIf (PanelCheckOut.Visible = True) Then    OnlineHelp(Me, "MainForm_Out.htm") ElseIf (PanelCheckIn.Visible = True) Then    OnlineHelp(Me, "MainForm_In.htm") ElseIf (PanelAdmin.Visible = True) Then    OnlineHelp(Me, "MainForm_Admin.htm") ElseIf (PanelProcess.Visible = True) Then    OnlineHelp(Me, "MainForm_Daily.htm") ElseIf (PanelReports.Visible = True) Then    OnlineHelp(Me, "MainForm_Print.htm") Else    OnlineHelp(Me, "MainForm_Basic.htm") End If 

The Help panel on the main form includes buttons designed to jump to the table of contents and index of the current online help file. I added event handlers for these buttons. The code for both MainForm.ActHelpContents_Click and MainForm.ActHelpIndex_Click is just like the code in the generic OnlineHelp routine, except for the final call to ShowHelp.

Private Sub ActHelpContents_Click(ByVal sender As Object, _       ByVal e As System.EventArgs) _       Handles ActHelpContents.Click    ' ----- Show the online help table of contents.    ...    Help.ShowHelp(Me, fileToUse, _       HelpNavigator.TableOfContents)    ... End Sub Private Sub ActHelpIndex_Click(ByVal sender As Object, _       ByVal e As System.EventArgs) _       Handles ActHelpIndex.Click    ' ----- Show the online help index.    ...    Help.ShowHelp(Me, fileToUse, HelpNavigator.Index)    ... End Sub 

Once the online help (.chm) files are in place, and once the application is properly configured to locate those files on the workstation, the user can access help from any form by pressing the F1 key. Figure 23-11 shows help accessed from the Library Items panel of the main form.

Figure 23-11. Answering the call for help

Speaking of correctly configuring the .chm files, we still have to figure out how to get the entire applicationincluding the online help filesonto the client workstation, and at a cost that will put food on the table. We'll look at these deployment issues in the next chapter.