Introduction | Browser
Page - Navigation Pane
Page - Navigation Tabs
Page - Frame
Page - Toc & Index
Page - Search
Page - Generate
This window is available from the Authoring menu (main window).
FAR 5.7 Changes - 10/12/2015
Starting with FAR 5.7:
With Uncompressed help (AKA Web-Help) we simply add Navigation files (Toc/Index/Search) to your existing web site. Uncompressed means files are not compressed to a single .CHM or .HxS help file. The strength of uncompressed help is that it can be used anywhere HTML can be used -- a web server; USB thumb drive; CD or DVD; etc.
A page with IFrames is created. The left frame displays the TOC, Index or Search. The right frame displays your normal web content. And in FAR v5 we also allow a top banner frame for company log etc.
This dialog will add several files to the root of your local web. It will _not_ change your existing web files.
Copyright & Licensing
The Index JS code and Search JS code were written by the FAR team. We have not tried to hide or obfuscate the code in anyway. This means you can easily debug and modify it. Remember that the code is copyright and owned by us, so please respect it as you would any 3rd party executable (IE. you can't steal the code and build a similar product that competes with FAR).
You must own a copy of FAR HTML to publish a web containing FAR navigation code. If you have 2 teams publishing 2 different webs then both teams need to purchase a copy of FAR HTML. If a team member already owns a copy of FAR then you are covered. If a member of another team owns a copy of FAR you can use that, as long as that member stops using FAR (IE. transfers the license to you). No other cost or royalty is required.
This dialog allows you to create web site navigation in several different styles and configurations. It is difficult to please everyone so we encourage you to get familiar with the HTML code generated and modify it as required. Otherwise contact us and we will try and add in your changes.
Our helpware site contains an example created using FAR Uncompressed Help:
Lets talk about browser compatibility.
Browser we have tested under Windows:
IE 6/7/8 Excellent Firefox 1/2/3 (Mozilla5/Gecko) Excellent Google Chrome 2.0 Excellent Opera 8/9 Excellent Opera 7.54u2 Very Good. Some issues with layout if a small or large font chosen. No Toc Sync. Safari 3.2 Excellent Netscape 7.2/8 Excellent
Removed from FAR 5.7
Pure HTML TOC/Index
Recommended for very older browsers.
Not very stylish but old browsers should have no trouble with this HTML code. Search is up to you. If you are on the web use the Google free search engine.
HH JAVA TOC/Index Controls
Many years ago (1997) Microsoft released a JAVA version of the HH ActiveX control. At the time JAVA promised to be the future of web and cross-platform development. Unfortunately MS did not maintain this controls and it's no longer compatible with most browsers.
HH ActiveX TOC/Index Controls
Note: Dec 2004 MS Security update MS05-001 has now disabled hhctrl.ocx (HH ActiveX) controls from working on the web. Read more. Still ok for use on a local PC.
The MS HTML Help 1.x ActiveX controls will only work in Internet Explorer 4 or greater. Remember only IE supports ActiveX.
If you have users who don't mind being restricted to IE these are nice controls. Unlike the JS controls these controls can load .HHC and .HHK files natively. And the TOC can display all those pretty HH 1.x TOC icons.
Microsoft do not produce a portable Search engine so for search you must use FAR JS search, Google (if web based) or whatever.
Browser usage figures can be found on the web. At this stage FAR JS Navigation works with all the popular browsers.
File > Open Base Folder
Select the base folder of the local web you want to work with.
EG. If the folder "c:\projects\MyProject1\" contains all your project help files and folders, then select that folder. All files - .HHK, .HHC, frame files etc. are added to this directory. None of your existing Web files are modified.
Dialog settings are saved and loaded from a file called "farinfo.ini" (also in the base folder). See File > Save.
File > Save
Stores the dialog settings to a section in the INI file "farinfo.ini" in the current base folder. You can safely delete this file at anytime (but you will return to the default settings). The section used to save settings under is specified in the Top Panel.
File > Load Defaults
Set all fields to their original default values. This reset affects only the current INI section, other sections containing data will remain the same. Note that some image settings will remain unchanged.
File > Windows Explorer
Open a Windows File Explorer window at the current base folder.
File > Exit
Close this window. Prompts you to save if there are unsaved changes.
Displays this on-line help.
The top panel is below the main menu and above the page tabs.
Click this hyper-link to select a new Base Folder. This is simply a convenient repeat of the "File > Open Base Folder" command. The edit field displays the name of the current Base Folder.
Save in Section:
Click this hyper-link to Save all dialog data to disk. This is simply a convenient repeat of the "File > Save" command.
All data is saved to/loaded from the specified section in farinfo.ini which lives in the current Base Folder. Use the Add & Remove buttons to add/remove sections to/from the Section Name dropdown list. Note that the "Default" Section Name cannot be removed.
Saving various dialog configurations into different sections means you can recall different configuration later. This is done by simply selecting a section name from the dropdown lost. You will be prompted to save before moving from one section to another (but only if there is unsaved data).
Select the type of browser you want to test the output HTML in.
FAR lists the following browsers if found: IE/FireFox/Google Chrome/Opera/Safari/Netscape.
Create navigation files
Click this hyperlink to generate your final output. This is simply a convenient repetition of the command on the "Generate page".
Test in browser
Click this hyperlink to open the generated help system in the selected test browser (see Test Browser above).
Like MS Help FAR can provides the 3 standard navigation panes: Contents, Index & Search.
Pane: [X] Contents, [X] Index, [X] Search
Select which of the 3 panes you want to generate using FAR.
Note that if you are using Gif Tabs the Contents pane should be included (checked). This is simply because when this feature was originally written we created Gif images that always used a TOC. In FAR Version 4 we have removed the limitation that forced you to include a Contents tab.
If you are artistic you could create your own set of Gif navigation tabs, or translate the existing GIF images.
Background: Contents, Index, Search Dropdowns
Select the background color or image for each pane you have checked.
At the top of the dropdown list are some special items:
Custom... Select this item to select a color from a color select dialog. Use BG Image 1,
Use BG Image 2,
Use BG Image 3
Select either image 1, 2 or 3. These three images can be defined in the Background Image section. No Color Select this item to use no color code. _LightGray Simply the color #f1f1f1. Something we frequently use here in-house. _buttonface (Removed from FAR v5.7) Also defined further down the list but redefined here at the top of the list for convenience. Don't use buttonface if your non-IE browser is being used.
Note (Removed from FAR v5.7): Although you specify a color by name (such as "Button Face") some color names only work in the MS Internet Explorer browser. These are typically the programming type names such as "Buttonface", "WindowText" etc. Best to avoid these names and use "Custom" or a standard colors.
These fields are available when a Background color is specified (field above). To disable Gradient colors set the selected value to "*No Color".
This setting when enabled creates a gradient between two colors. Color#1 is the Background color. Color#2 is the Gradient color. Check the Vertical gradient checkbox to create a vertical gradient, uncheck for a horizontal gradient.
Since not all browsers support color gradients FAR actually creates a gradient image file (called hh_Gradient1.jpg, hh_Gradient2.jpg and hh_Gradient3.jpg) when the Generate button is clicked.
Select up to 3 background image files (GIF or JPG). Once images have been selected, use the Background dropdown controls (above) to set a background image for a pane.
Click this button to select a GIF or JPG Image file from any location.
Click this button to clear the image selection.
Each time an image is selected, FAR copies the image as hh_bgImage1.jpg, hh_bgImage2.jpg, hh_bgImage3.jpg (or .GIF if a GIF was selected) into the base folder.
Setup the TOC colors and icons.
Background: Choose the background color of the TOC panel. Only this dropdown contains the "transparent" option. Transparency allows you to have TOC items over an image or gradient background.
Node Select: Selection the background color of the selected item.
Node Rollover: Selection the background color of the mouse over item.
Node Border: Color of the selected and rollover border surrounds.
Text Color: General text color.
Selected Text: Selected text color.
Rollover Text: Mouse over text color.
Icon Set: FAR v5 allows you to choose a TOC icon set. Each set can have 3 icons (page, folder-closed, folder-opened). The default icons are stored in <FAR.EXE-dir>\extra\ and are copied to your web's root folder whenever you generate new navigation files. These default files are named treenodedot.gif, treenodeplus.gif, treenodeminus.gif. These is also the names used when they are copied to your web folder.
Additional icon sets are stored in <FAR.EXE-dir>\images\tocIcons\.
To add your own TOC icons, place 3 images (.GIF or .JPG with same dimensions) into the above folder. File name must be - treenodedot(myName).gif, treenodeplus(myName).gif and treenodeminus(myName).gif. The myName text will be displayed in the Icon Set dropdown.
[X] Include Close Button
Check this box if you also want to add a Close button to each navigation pane.
Use Form Buttons
If you select this page tab then HTML <Form> Buttons will be used to move between navigation panes.
Button Text: Specify the text for each navigation pane button (and the close button if enabled).
Button Color: Check the box to specify the foreground and background color of the buttons.
Active Button Color: Check the box to specify the foreground and background color of the active button
EG. If Contents pane is selected at runtime then Contents button is the Active button.
Active Button Disabled: Check the box to always disabled the active button.
EG. See image below - When the Contents page is selected then the Contents button is disabled.
Clicking the Contents button while on the Contents page does nothing except reload the same navigation page. Thus we can safely disable it.
Notice that under Windows XP & Windows 2003 buttons are Themed buttons (as pictured above). If you check the "Button Color" checkbox you will lose the beautiful XP themed look.
Use GIF Tabs
Select this page tab and .GIF Images files will be used to select navigation panes.
Select to choose a set of tab images to use. Select any file in the set and FAR will copy the complete set of tab images into the base folder as hh_navtab11.gif, hh_navtab12.gif etc. The images are displayed as reference in this page. Hold the mouse pointer over each image to check its filename. Notice as you uncheck Index or search pane checkboxes (above) the images are hidden.
Note: All image sets assume you are using a contents navigation pane.
FAR provides some basic tabs sets to choose from. Note: Because of overlap, the Contents/Index/Search/Close tab sets may not function well when Index or search is unchecked. To fix this we sometimes provided modified tab sets EG. Std_Toc_Search_??.gif can be selected if you uncheck the Index pane. Create your own tabs sets if you don't find what you want.
xxx_11.gif, xxx_12.gif, xxx_13.gif Contents page tabs TOC/Idx/Search xxx_21.gif, xxx_22.gif, xxx_23.gif Index page tabs TOC/Idx/Search xxx_31.gif, xxx_32.gif, xxx_33.gif Search page tabs TOC/Idx/Search xxx_00.gif Image used after each of the above.
Include Close Button = Unchecked.
xxx_0x.gif Image used after each of the above.
Include Close Button = Checked.
Tip: If your tab images are not displaying correctly, reselect the tab set. This forces the tab set GIF files to be copied to the base folder.
This is the text displayed in the title bar of your browser. It's the <title>text</title> for the frame file.
Check this if you want a title frame along the top of the browser window. Typically you would add to this topic showing off your product name & company branding.
Frame Topic: The HTML topic to display in this top non-scrolling frame.
Frame Height: Literally the height of the top frame.
Frame Divider Height: The thickness of the divider separating top and bottom framesets.
Frame Divider Color: Color of the divider.
Removed from FAR 5.7
Frame Border: Hide/shows the horizontal divider. Does not effect some browsers (EG. Google Chrome shows no effect).
Top Frame 3D Border: On most browsers this creates a 3D sunken border around the top frame.
Settings for the bottom left and right frames. Navigation goes in the left frame while your HTML content goes in the right.
Default Topic: Select the HTML file to be displayed in the right hand frame.
Left Frame Width: Specify the width of the left frame.
Frame Divider Width: The thickness of the divider separating left and right frames.
Frame Divider Color: Color of the divider.
Removed from FAR 5.7
Frame Border: Hide/shows the vertical divider. Does not effect some browsers (EG. Google Chrome shows no effect).
Left Frame 3D Border: On most browsers this creates a 3D sunken border around the left frame.
Right Frame 3D Border: On most browsers this creates a 3D sunken border around the right frame.
Click the button to select an HTML file.
Click this button to edit the TOC or Index file in the preferred text editor (see main window Options > Preferences).
Click this button to open the file in the test browser.
Redirect to Frame if opening single TOC, Index or Search file
If you check this option then some extra code is placed inside TOC, Index and Search HTML files. If the user tries to open say the TOC file by itself (typically hh_toc.htm) then the TOC file immediately opens itself in its usual position in a Framed window.
Left Frame Footer
Check this box to display a custom HTML message at the bottom of each navigation pane.
Extra Header Code
New for FAR 5.8 (813)
Check this box to insert these HTML code lines into the <head> section of the main host html file (recommended) when generating help.
The default code includes the following 2 lines. For more info see FAR Help Wiki.
<link rel="icon" href="favicon.ico?v=2" type="image/x-icon" />
<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE11"/>
More about FAR Uncompressed Help and Frames
Normally a FrameSet file opens in a fixed configuration. ie. TOC on left side and home page on the right. How could you open the Index on left and some other page on right?
In FAR 188.8.131.522 you can pass the left and right file names as a bookmark (anchor). This works with either the FAR hh_goto.htm, redirect.htm or hh_start.htm files. Here are some examples:
Open the default FrameSet file
Now we add some parameters:
Use a single bookmark to override the right frame.
Redirection file again. Redirection params are simply passed onto the redirect file (in this case hh_start.htm above).
Use two parameters to set both frames. The bookmark contains 2 parameters separated by a + char.
The first param sets the right pane. The second param sets the left pane.
In this case we override the left frame only.
The first param is empty so the right frame gets the default file name.
Tip: If a file does not seem to change try pressing F5 to refresh the page.
30-Nov-2006 - hh_goto.htm
We found that a single IE browser session wont update if you are serving up the same HTML page (hh_start.htm), even though you are changing the bookmark.
Example: Click these 2 links. The second link wont work since hh_start.htm is already loaded. The browser ignores the change in bookmark.http://helpware.net/FAR/help/hh_start.htm#file_menu.htm
One way to overcome this problem is to use hh_goto.htm (created at the same time and in the same folder as hh_start.htm). It simply redirects you to hh_start.htm, passing on any parameters. So parameters for hh_start.htm are the same for hh_goto.htm.
If you are setting up contextual help then try using hh_goto.htm instead of hh_start.htm
Example: These links both workhttp://helpware.net/FAR/help/hh_goto.htm#file_menu.htm
This page is only available if you have checked either the Content or Index pane checkbox on the first page.
Specify either a MS HTML Help (.hhc/.hhk) or MS Help 2.x (.hxt/.hxk) TOC and Index files.
Specify TOC & Index control type
- The TOC and Index generated are purely DHTML and Script. No ActiveX or Java is used. Your HHC and HHK files are used to generate the HTML code but are not required to be shipped.
The DHTM TOC is the same used by NDOC 3.x. The TOC tree.JS code file itself was originally written by Jean-Claude Manoli and as requested we have left the copyright notice in the header of the tree.js file. Please do the same. The code is used with permission. We have added several improvements and fixes to the code.
See also Browser Compatibility
- Pure HTML
- No script. No DHTML. This navigation is very plain but should work with even the oldest browser.
Use a redirection file to load pure HTML navigation if JS or IE4 support is not found. See Generate page.
- HH ActiveX Controls
- The MS HTML Help ActiveX visual controls are used to display the HHC and HHK files. As stated above MS have blocked the HH ActiveX (hhctrl.ocx) from working on the web [web ref]. So only use this type of navigation if you are running on the local PC. These controls require IE4 or greater. Most other browsers do not support ActiveX.
- HH Java Controls
- The MS HTML Help Java Applet is used to display the HHC and HHK files. We advise you not to use this setting since the applet was never maintained by Microsoft and is quite out dated.
Click the button to select a TOC or Index file from the base folder.
Click this button to edit the TOC or Index file in the preferred text editor (see main window Options > Preferences).
Specify a table of contents file
Enter the name of a TOC file to use. HTML Help TOC files (.hhc) are ANSI only. While MS Help 2.x TOC files (.hxt) can be Unicode. Use the FAR TOC & Index editor to convert between file types using the Save As dialog.
The file should live in the base folder. Enter the filename with no directory part. If the folder does not have a TOC file then click the "Create TOC" button. FAR will then search for HTML files and create a .HHC file for you. If you already have a .HHC file then click the "Edit TOC" button to open it in the FAR TOC & Index Editor.
Normally you would create a TOC file once, then maintain it using FAR TOC & Index Editor.
Specify an Index file
Enter the name of an Index file to use. HTML Help Index files (.hhk) are ANSI only. While MS Help 2.x Index files (.hxt) can be Unicode. Use the FAR TOC & Index editor to convert between file types using the Save As dialog.
Same comments for the Table of Contents above apply here.
If these settings are disabled its because you uncheck the Index pane checkbox on the first page.
Show TOC Filter
[FAR 5.8+] Check this box to display a filter edit box above the TOC ('Contents' must be checked on the first page). As you type into the filter box TOC labels are highlighted that contain the text entered.
[FAR 5.7+] When checked a dropdown button shows next to the TOC Filter edit box. 'Show TOC Filter' (above) must be is checked. The dropdown button displays search options and a search button.
FAR provides two full-text search options:
Custom Search Code
Here you simply enter the code for the search navigation pane to use.
If you own your own domain name and want search to cover the entire domain then we recommend you use Google. There is no beating Google for speed and quality. Google provides free code that allows you to search only your domain.
Click the Setup Google Code with my domain link to generate Google code. When prompted enter your domain name. EG. www.HelpwareGroup.com. Note that if you use non-Western coding or UTF then you need to also edit the two items coded as "iso-8859-1". See Google.com for more info.
Before your navigation UI search code will work you must generate the search database file searchdata.js. To do this go back to the FAR main window and...
- Set the FAR drop filter to HTML files only.
- Drop the Root folder of the local web onto FAR.
- Remove any HTML files from the FAR list not wanted in the search data.
Select a Search Page Layout
Select one of the available search page layouts from the dropdown and generate the navigation code (Generate page).
There is not much more to say here except try each layout and see which you prefer. If you don't like the search text or layout then edit the final Search HTML. Note that half the layouts use offer "Partial word matching" and half offer "Match whole words only" -- These are simply opposites of each other. If you compare the code you will see that the Full Match checkbox has a NOT operator in the code.
Click to edit the file in the text editor.
Click to test the file in select web browser. The icon will change depending on what test browser is selected.
Create Navigation Files
Create Navigation Files button
This is the final step. This creates the required navigation files in the base folder, and copies all required auxiliary files (such as tree.css, tree.js, search.js etc) from the FAR \extra\ folder into the base folder.
As soon as the Frame/TOC/Index/Search files are created, the Frame is loaded into your test browser.
Create Nav Options
When you click the Create button, an Options dialog displays which files are allowed to be overwritten. Deselect any files you don't want overwritten. Why would you you this? You may have a file that you have customized and do not want FAR to change.
You can also set these options without performing a build by clicking the "Create Nav Options" link.
The Options are saved with all other control settings. So every project section has its own set of options.
Note that the Options dialog wont show if you Create using batch mode.
Click this button to view a list of files used or created by FAR that should be shipped with your web site.
If you don't like our choice of HTML output file names you can enter your own names.
Create Redirection File
Redirection file was useful when browser compatibility was poor but now is not so important.
Since FAR 5.7 you can now ignore this section. The old help on redirection continues below...
Create Redirection File button
- In the "Create Navigation Files" group above set all file prefixes to "hh_".
- Now set the file prefix to say "ht_".
Select for pure HTML TOC and Index (and something safe for search)
and again Generate the navigation files.
then click Create Redirection File.
Now when you open redirect.htm you should see navigation that will work no matter what browser is used.
If the right pane is from a different domain there will be security restrictions and the JS TOC sync code will kick up an error (we call this on page load and when the Sync link is clicked). You can simply ignore this or you could edit the code and disable the call to TocSync on page OnLoad (and also the call at end of page).
Take a Look at the frame source. Notice that the 2 frames have been given names called "left" and "right".
<FRAMESET COLS="265,100%" framespacing=3 frameborder=1>
<FRAME SRC="hh_toc.htm" name="left" scrolling="no">
<FRAME SRC="index.htm" name="right" scrolling="auto">
Edit your TOC and Index files. On the Properties page of the FAR TOC/Index Editor is a field called Frame. Make sure this is set to right. So now all pages are opened in the correct Target called right.
For the search or footer HTML make sure that any anchor or form tags contain Target="right" to direct content to the right frame
Example: <a href="somefile.htm" target="right">Click me</a>
FAR 5.7 - Similar except we now use IFrame instead of Frameset <iframe src="hh_toc,htm" hight="100%" name="left" scrolling="no" ..>
We changed from double-click to single click in FAR build 691.
To enabled the old double-click method edit the Settings.ini file (in the FAR.EXE folder) and at the bottom of the file ([MAIN] section) add the following text:
Please read notes on WebHelp and using NavScript.js here http://kb.helpwaregroup.com/far/webhelp/navscript-js
By including the file NavScript.js (included with FAR 5.7 extras install folder) a link is displayed to reopen the navigation pane when the nav pane is closed.
Go to this page now and try clicking the link (top of page) to open the navigation frame: http://helpware.net/FAR/help/index.htm
You are welcome to use the code. Here's what you need to do:
1. Add the file NavScript.js to the root folder where "hh_goto.htm" lives.
(hh_goto.htm is a file generated by FAR 4.3/5 Uncompressed Help)
You can get NavScript.JS file from the FAR 5.7 \Extras\ install folder
2. Add the following script immediately after your <body> tag.
Files one level down from the root folder would look like this...
Files two levels down from the root folder would look like this...
... and so on.
3. Tweak the script to suite your own situation.
Again please read the latest WebHelp KB notes here which describes using NavScript.js in detail.
2008-7-11: The script now detects if the page is inside a CHM. If it is then it doesn't display the Open Navigation link (since a CHM help file has its own navigation).
29/9/2008: Added a new command to the FAR 5 Find and Replace dialog to insert the above script in a single pass.
Open the Adv Find and Replace dialog and click the [v] insert menu button. Select "$R$[..] -- Insert NavScript.js web help script".
10-12-2015: An updated NavScript.js now ships with FAR 5.7 and is compatible with FAR 5.7 web help output. It allows toc sync to work even when browser security is an obstical.
But if you modify these base templates it affects all projects created by FAR so we first check for files in this folder:<My Project BaseDir>\extra\
When a file is found in this folder it is used in preference to <far.exe>\extra\ . A full list of templates and files used by Uncompressed help can be found in <far.exe>\extra\_readme.txt