Overview
HTML Help
HTML Help v1.0 was released by MS in 1997 who also released the HTML Help Workshop which is an application to generate an HTML Help .CHM file.
This was a decided improvement over the old WinHelp system and various releases were made up to 1.4 for HTML Help and 1.3 for the Help Workshop.
Then support stopped in 2009 and the only MS support for these packages now is the correction of critical bugs
Whilst I feel that HTMLHelp was an advance over WinHelp, I was never entirely happy with it as I couldn't ever find a way to style the display of the .CHM file. I suspect that was because development stopped before styling became a major issue with Html.
This package came from my attempts to rectify these display problems to my satisfaction. It isn't a single application like HTML Help Workshop but a set of files and minor apps. which allow you to style .HTM files to display Help for a VB package There are lots of bits & pieces, but you're in control!
The Help structureThe basic structure is as for most Help systems. There is a split screen display with a choice of "Contents", "Index" and "Search" tabs at the left and display space at the right: what you're looking at now! There is no print button as any section can be printed from the browser menu. Nor are there 'Hide' or 'Option' buttons as I don't see the necessity for these.
The styling of the left-pane display is my choice and is described more fully in the following sections but the point is, if you don't like linked tree lists or little 'plus' and 'minus' symbols, you can replace these with the structure you prefer and the graphics you want, even little MS books, (
), if you wish!
The actual Help file, 'hlp.htm'
This file creates two objects which are used to display the Contents, Index or Search files in the left block and the requested information in the larger, right block. The areas used by each object are styled by the 'split.css' CSS file.
When it is first loaded, it loads the type of Help file selected in the VB application in the left area as 'source.htm', (see VB notes), 'data.htm', in the right area.
The Contents file, 'content_itms.htm'
This, like each of the three operational files, starts by setting up the three tab menu display and then lists the 'Content' items in a connected tree-list below.
As with all of the tree-lists, there are buttons to 'Expand all' or 'Collapse all'. As it's considered that a 'Content' file has a fairly simple structure, there are no aids for its constuction.
The Index file, 'index_itms.htm'
This displays an alphabetic list of the items you've chosen to include with the same basic layout as described above for the 'Contents' file. However, as this is likely to be a large file, an aid for its construction is provided by 'Index file Maker'.
The Search file, 'search_itms.htm'
This displays a form in the left area which has a text box at the top in which you enter the word or phrase to be found. Below this is a 'List topics' button which starts the search. The search is case insensitive and, if any items are found, their titles are displayed in a List Box below the button. If none are found, a message to this effect is displayed in the top text box. If no key is entered, nothing happens!
The user then selects an item from the list and clicks the 'Display' button at the foot of the page. This will process the file concerned using a Javascript file which highlights in yellow each complete occurrence of the requested word or phrase, no matter what capitalisation is used.
The data file, 'data.htm'
This file contains all of data the Help items. Each item is contained within a 'div' tag which has its visibility set to 'none' until it's selected.
This method is used to stop having to read and write files for the 'Search' option as Javascript is very uncooperative at writing data to a client-side file which is how it sees your Help system.
The 'source' file, 'source.htm'
This 'Source' file is used as one way of starting off with the selected operational file. The VB code makes an API call to open the 'hlp.htm' file but it then has to pass a parameter to this file to then open whichever of the 'Contents', 'Index' or 'Search' file is required. The way chosen to do this is to rename a copy of the required file as 'source.htm' and then have 'hlp.htm' always open this when it's first loaded.
The Visual Basic
The set-up section
VB uses an API call to activate help and this must be defined at the start of your program.
The 'Help' calls
The main form has a Help menu listing the options shown on the right.
(Description of the 'Pop-up' process can be found here)
Clicking an option runs the associated procedure.
In each case, the URL of the 'hlp.htm' file is stored together with that of the selected operational file and the 'run_help' procedure is used to set up the help files.
The Help procedures
'run_help' uses 'setup_htm' to set up the selected operational file as 'source.htm' and then uses the Shell API to open the 'hlp.htm' file in your default browser, (see Script section).
'setup_htm' defines a File System Object, stores the 'source.htm' file path and, if there is already a version of 'source.htm', it's deleted. The FSO is used to get a copy of the selected operational file which is then renamed as 'source.htm'.
File construction aids
This will create the 'index_itms.htm' file from a set of data on an Excel Worksheet
It was created for use with help files when it was found that the manual creation of an index files was long, boring and prone to errors! It's specifically designed to create files using the linked tree-lists of these examples and would have to be greatly modified if you want a different system.
You start by listing the section codes of your data Help file in the first column of an Excel Worksheet called 'RAW DATA' in a workbook called 'index_maker.xls' which also has a 'SORT DATA' sheet. In the second column you write the index entries which pertain to that file, delineated by commas, remembering to cross-reference when possible as you don't know what a user will actually enter for a search.
e.g. You don't know if a user will enter "Creating" or "Index" when looking for information on "Creating an Index file", so allow for both options.
When all the information is entered the file is saved and the package run. It takes the data you've entered on the 'RAW DATA' sheet, copies it onto the 'SORT DATA' sheet, fills in the blanks in the file name column and then sorts the data on the basis of the items in the second column. It then creates the code for the index file from these sorted items.
Graphics
The Tree graphics
The tree structure used comes from Stephen Morley to whom I'm very grateful as I spent a long time trying to work this out for myself. However, the graphics have been modified and you may well want to create your own.
The tree graphics consist of images for three buttons and for six sets of lines which link together to create the list.
The buttons,
,
,
The lines,
,
,
,
,
,
You may well find that the joins aren't exact. If this is so, the vertical lines concerned can be tweaked a pixel either way with a graphics program to correct this. Also, if you allow text to wrap round then gaps will appear in links.
The rest of the graphics are just illustratory .GIFs or .PNGs of parts of the package.
The style sheets
General
There are three files,
Menus
There are two menu files,
Trees
There is one tree file, 'help_tree.css', which again came from Stephen Morley. Whilst this could be changed, I wouldn't recommend it and certainly the names can't be changed as they are referenced by the Javascript that creates the list.
Pop-ups
The Pop-up styling is part of the, 'help_rnd_box.css', file. This is dealt with by the #pup ID which can be used to set up the default colour, transparency, etc. of the pop-up display boxes.
THE SCRIPTS
Tree lists
The file used for this is 'CollapsibleLists_mod_comp.js'. This was written by Stephen Morley in its original form. I've modified it to include functions to 'Expand all' and 'Collapse all' items in a list.
Searching
This uses the Javascript file, 'process.js'.
The functions are run by clicking the buttons on the 'search_itms.htm' form. At the moment, it finds all occurences of the requested word or phrase and highlights it in yellow. These could be changed by editing the script. Trials were carried out to have the script only recognise individual words rather than part words but this was found to be unsatisfactory.
Pop-ups
The Pop-ups use the script 'popup_old.js'
The original popup code came from Nicolas Honing. I've modified it to allow extra parameters,
Using the package
What do you have to do to use all of these bits & pieces to create a Help system?
Well, the first is that you have to write all your Help files but then this needs to be done no matter which system you're using. In this case, all of the information is put into one file, 'data.htm', (see below).
The files can be split into two groups: those that can be used 'as is', (unless you want to customise them), and those which have to be edited or re-written
Type of file | Can remain unchanged | Need to be changed |
---|---|---|
HTML | hlp.htm | content_itms.htm |
search_itms.htm | index_itms.htm | |
data.htm | ||
CSS | (all files) | |
Scripts | CollapsibleLists_mod_comp.js | process.js |
popup.js |
Therefore, only four files have to be re-written or edited.
content_itms.htm
As mentioned before, whilst you could keep the start and end of the sample file, all of the list code will need to be re-written. If you're using the supplied Tree system, the first <ul> tag must be assigned the "treeView" class, the first <ul> tag that you want to be collapsible is assigned the "collapsibleList" class and care must be taken that every LAST <li> tag is assigned the "lastChild" class so that its link will be terminated. Writing indented code in a utility such as Notepad++ is a great help in this.
index_itms.htm
The essentials of this process are described in the File construction aids page.
process.js
The only change needed is the contents of the section numbers array, 'itms[]', which is found on line 26. The inclusion of zero is to ensure that the array subscripts match the active data items. The use of an array instead of the actual digits, 1 to n, allows for the removal of sections from the data file without the need to have to renumber all subsequent sections.
data.htm
This represents the greates change as all of the data needs to be re-written.
However, the basic structure of the file mustn't be changed from that shown below.
<div id="v0" style="display: none"> <!--BLANK starting block DIV. Leave empty-->
</div>
<div id="v1" style="display: none"> <!--START ITEM block DIV -->
<p style="font-size:.1em"> </p> <!--Padding-->
<div id ="t1" style="display: none">[Title of first section]</div> <!--ITEM TITLE (Needed for Search)-->
<!--BODY text of item-->
......
......
</div>
<!--END ITEM block DIV -->
The <div>s with 't' IDs always remain hidden and are just used to populate the selection box on the 'Search' form. Each section will presumably start with a heading which will be the same as or similar to the title.
The method of operation of the file is that all the section <div>s start off with their display style set to "none". When a section is selected, this is changed to "block" to display the text. A particular part of a section can be displayed in the usual way by inserting an ID 'marker', (<div>s in this example), to which the display will jump. The ID is added as a second parameter in the 'display()' call without a leading '#'. i.e. display([section code], [postion code]), e.g. parent.display('v9','u4');.
This means that your browser 'Back' control doesn't work as all of the information is on one page. The 'Back' button next to the heading will literally take you back to the previous section and no farther, as the viewing history isn't stored.
A few thoughts about the body text
The 'Search' algorithm has been kept very simple in that it only searches the contents of paragraph tags. This means everything inside a paragraph is searched and, unless you're careful, highlighting can be applied where it's not wanted; perhaps where it will ruin your code.
e.g. if pop-up text which contains the key word is included in a paragraph, the highlighting code will be added which will cause the pop-up to fail and leave bits of code on your display.
Similarly, if your key word occurs within a style or class description, it will be highlit which will probably destroy the styling.
Basically, the rule is to enclose in <p> tags the text you want to be searched and use <div> tags for areas which are to be left alone.
External links
Any external links from data.htm will be displayed in the right-hand pane which can be navigated and cleared by the browser Back button rather than the one at the top of the display. However, there are occasions when the system locks up and nothing works. I'm still trying to find out why.
Alternatively, if you want to keep the section of data displayed, you can add target="_blank" to the <a> tag so that the link is opened in a new window which will van then be closed to show the help panes again.
Customising the package
Changing colours
This is the easiest customisation you can make. The colour data for the CSS is in 'help.css', 'tab_menu1.css' and 'help_rnd_box.css'. At the top of each file is a list of the colours used in both rgb and hex notation. Until variables for CSS are implemented in most browsers, (see CSS3 variables), you'll just have to work through and change each colour as it appears.
Corners
Another thing you might try is altering the curvature of the rounded corners on the menu tabs and display cartouches. These are defined in 'tab_menu1.css' and 'help_rnd_box.css'. The work here could be cut down by deleting all the legacy versions for radiused corners which aren't needed if you're using the most up-to-date version of your browser.
Tree list display
It's possible but more difficult to alter the Tree list display. One that I used to use before adopting the present form used indented lists with coloured dots. This was adapted from Stuart Langridge's aqlists, by Matt Kruse with minor additions by me.
However, as mentioned before, you couldn't use Index Maker with this, 'though you might be able to run it and then edit the changes needed?
Highlighting
The highlighting effect is defined in process.js by the variables 'hi_pre' & 'hi_post' at lines 25 & 26 and these could be edited to change the colour, size, etc. of the key text in the document.
Using and distributing the package
The package is © Philip Bolt 2011 - 2014, except for those parts produced by other authors listed below.
However, you may use and distibute my material under the conditions specified in the Design Science License, a copy of which can be seen at https://www.gnu.org/licenses/dsl.html.
This work is also licensed under a Creative Commons Attribution 1.0 Generic License.
There is also the added restrictions that any file you distribute must have a header which acknowledges my authorship and provides a reference to my website, www.redhall.org.uk.
Material by other authors may only be used in accord with their conditions. The items concerned are,
This means that you may not sell or exchange any part of this material, either on its own or as a part of a larger package, but you can modify the code to suit your needs and distribute it as part of a freeware package.