Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Revision History
Date Version Description Author
Table of Contents
1. Introduction 4
2. Preparation 5
2.1 Complete the User Guide 5
2.2 Downloading Helen 5
2.3 Getting Started 5
2.4 The SOLA Help Project File Structure 6
2.5 Images 7
3. Using Helen 11
3.1 The Helen GUI 11
3.2 HTML Page Views 11
3.3 Adding and Removing Help Topics 12
3.4 Formatting Standards for Help Topics 13
3.5 Table of Contents 16
3.6 Index 17
3.7 Map 18
3.8 Also See Section 18
3.9 Project Level Configuration 19
3.10 Verifying the SOLA Help 21
3.11 Creating the Full Text Search Index 21
1. Introduction
This guide describes how to create and configure JavaHelp for the SOLA Desktop and
SOLA Admin applications (a.k.a. SOLA Help) using the Helen help authoring tool.
JavaHelp is an online help format developed in Java. It includes a help viewer application
(called JavaHelp viewer) that allows users to search, browse, navigate and view help topics.
Helen is a GUI application that can be used to streamline and simplify the process of
creating JavaHelp for an application.
2. Preparation
2.1 Complete the User Guide
The content of the SOLA Help is based on the SOLA User Guide, so you should ensure the
User Guide is up to date before proceeding with creating the SOLA Help files. Updating the
User Guide may also involve capturing screenshots and other images. If so, refer to the
Images section in this guide to avoid duplication of effort and ensure the best quality
screenshots and icon images are available for both the User Guide and the SOLA Help.
2.2 Downloading Helen
Helen can be downloaded from http://www.software7.biz/. It comes with a 30 day trial, but it
is recommended that you purchase the Standard Copy without Maintenance (approx. $US
209). The installation is straight forward – just follow the wizard prompts.
The first time you start Helen, it will be in Wizard Mode and it will prompt you to either create
a new project or open an existing project. Click the Advanced Mode button to avoid dealing
with the wizard. Also change the Start Mode preference (see Tools > Preferences) to Start
in Advanced Mode.
2.3 Getting Started
Whether you are creating a brand new SOLA Help project (for a new SOLA product) or
creating a new language translation you should copy one of the existing SOLA Help projects
to use as a starting point. This is because the existing projects contain HTML files, images
and configuration that are likely to be common to other SOLA applications and language
translations.
If you are creating a new language translation, copy the defaultlang folder (located at
…code\common\help\src\main\resources\org\sola\common\help) from the source code of
the SOLA application you are working on. If, on the other hand, you are creating a brand
new SOLA Help project for a new SOLA application, copy the defaultlang folder from the
source code of the SOLA Registry application. Open the project by double clicking the
SOLAHelp.jhp file. The jhp file is the Helen Project configuration file.
Notes
Helen doesn’t remember the last folder you accessed, so you should paste the
project copy in a top level directory or subdirectory (e.g. C:/Work/). If you use a long
folder path for your project, it can get annoying having to navigate into the folder
structure every time you try to open a file. When you finish preparing the SOLA Help,
you can copy it back into the appropriate location within the help source code
repository.
If you only need to edit an existing SOLA Help project, navigate to the appropriate
folder directly in the source code and double click the jhp file and complete your
edits.
2.4 The SOLA Help Project File Structure
JavaHelp is comprised of a number of HTML files, images and configuration files. There are
more than 200 individual files for the SOLA Help, so it’s important that you keep these files
well organized. The recommend file structure for the project is based around the main
sections of the User Guide as illustrated in Figure 1 above.
The following describes the main files and folders of the project.
SOLAHelp.jhp The Helen project configuration file. It identifies all files that make
up the JavaHelp project. Open this file to display the help project in
Helen. Note that you can rename this file as it’s not referenced by
JavaHelp.
HelpSet.xml XML file that contains the configuration details for the JavaHelp
project. Helen provides several GUI forms that can be used to set
JavaHelp configuration values.
Note that this file may also be called helpset.hs. If is it, you should
rename it to HelpSet.xml. This is because the HelpUtility class in
SOLA explicitly references HelpSet.xml. If you do rename this file,
open the Helen project file (e.g. SOLAHelp.jhp) using a text editor
and update the corresponding file name in there as well.
TOC.xml XML file describing the structure to use for the Table of Contents
tab in the Help Viewer.
Index.xml XML file describing the structure to use for the Index tab in the Help
Viewer.
Map.xml XML file describing a mapping name for each file that is part of the
JavaHelp project. Used to simplify references to files within the help
project.
stopwords.swd Identifies common words to omit when generating the help search
index (e.g. the, of, is, etc.). It is usually not necessary to add
stopwords to this file when creating the search index for English
text as Helen uses a default set of English stopwords. However it
may be necessary to add common stop words for other language
translations.
appendix Folder containing HTML files representing the appendix pages from
the User Guide.
concepts Folder containing HTML files representing the SOLA concept
pages from the User Guide.
howto_... Folder containing HTML files representing the How To topic pages
from the User Guide. There can be a large number of How To
topics in the User Guide so you should have a separate howto_
folder representing each major How To section from the User
Guide.
images All screenshots and supporting images from the User Guide that
need to be displayed in the SOLA Help files. Screenshots and other
images should have a maximum width of 640 pixels. See the
Images section for more details on how to resize and manage
images.
images/icons icons is a subfolder of the images folder and it contains copies of
the 16x16 image icons used by the SOLA application.
introduction Folder containing HTML files representing the introductory pages
from the User Guide such as the licence page, SOLA Overview and
Acknowledgements.
Note that it’s not necessary to add the Getting Started section of
the User Guide into the SOLA Help as it describes how to install
the SOLA application and users cannot access the SOLA Help until
after they have completed the installation process.
JavaHelpSearch Folder created when generating the JavaHelp search index. You
should avoid editing or changing the files in this folder.
release_notes Folder containing HTML files representing the release notes for
each application version. Optional.
screens Folder containing HTML files representing the pages in the User
Guide describing the SOLA application screens.
troubleshooting Folder containing HTML files representing the troubleshooting
section of the User Guide. Optional.
If you have copied an existing SOLA Help project, this file structure should already be in
place. You may need to make some changes to it such as adding extra howto_ folders or
omitting folders that are not relevant (e.g. release_notes) depending on the content of the
SOLA User Guide.
Notes
You should avoid changing file and folder names unless absolutely necessary. Java
is case sensitive when dealing with file and folder names. If you change a file or
folder name such as changing uppercase letters to lowercase or vice versa, then you
may also need to manually change any help files (configuration and HTML files) that
reference the original file/folder name as well. Also be aware that git is case
insensitive for file and folder names. If you need to change the case of a file or folder
name, use the command git mv –f <FileName> <filename>.
2.5 Images
Images are an important part of the User Guide and the SOLA Help. Before starting with the
Helen help authoring tool, ensure all of the necessary screenshots and icon images have
been captured and resized appropriately. Also ensure the original images are archived so
they can be used for presentations or other materials as necessary.
You should ensure all of your screenshots are taken with the application sized to a common
height and width. The recommended height/width is approx. 675x900 pixels. To get the
application to this size, use Paint (or a similar image editing app) to create a blank canvas
that is 675x900 pixels in size. You can then manually resize the SOLA application on top of
the blank canvas until it matches the canvas dimensions. Note that it may be impossible to
resize the application to exactly 675x900 pixels, but within +/- 5 pixels is OK.
To capture a screenshot use the print screen function. This is usually invoked from the
keyboard using the CTRL-ALT-PrtScn key press. Make sure the SOLA application has focus
before using the key press as the ALT key ensures that only the screen with focus is
captured.
Print Screen captures the screen image to the clipboard, so you should paste the image into
an image editing app and save it as a png file. If you have copied the defaultlang folder to
setup the initial help project it’s likely the screen shot will simply be replacing an existing
screenshot in the images folder due to variations in colours or functions. Make sure you
overwrite the existing image with the new one without changing the filename because the
image filenames are referenced directly by the SOLA Help files. If you change the filename,
make you sure you update the filename reference in the affected help files.
2.5.2 Size of screenshots for User Guide and Online Help
The captured screenshots (675x900px) are too large for the User Guide and the SOLA Help
as is. Instead they are intended to be kept as high quality master images that can be resized
for the User Guide, SOLA Help, printouts, presentations and other documentation. Once all
screenshots have been captured to the image folder of the help project, create a zip archive
of the image folder (including the icons folder) and copy the archive to the appropriate
Dropbox folder.
MS Word has a very good image resizing function, so the master images can be copied
directly into the User Guide and adjusted to have a maximum height of 9cm. The easiest
way to do this is to right click the image (after you have pasted it) and open the Layout dialog
from the Size and Position menu. On the Size tab, set the Absolute height to 9cm.
Avoid distorting the image when resizing it by ensuring the aspect ratio is maintained.
2.5.3 Image Icons
A large number of 16x16 image icons are used throughout the SOLA application for button
and menu graphics. Image icons must be copied from the resources folder in the application
source code and placed in the images/icons folder of the help project. Do not clip them
from a screenshot.
3. Using Helen
3.1 The Helen GUI
Helen uses a relatively intuitive interface with a menu, toolbar, project tree and a content
pane showing details of the active file. From time to time you will also see a Property
Inspector pane allowing you to set various JavaHelp attributes as well as a Message
Console for reporting any warnings or issues with the help files.
When you click Create a new HTML page will be created and entries will be added to the
TOC, Index and the Map. You may need to move the entries in the TOC and Index into the
appropriate subfolder.
To remove a file, right click the file in the Project Tree and choose the Remove from Project
Delete option. After deleting a file, make sure you verify the help file as this will identify any
references to the deleted file that need to be fixed up.
Notes
Be sure you delete any help topics that are not relevant for the SOLA application you
are working on. This is important because all HTML files are referenced by the Full
Text Search, so even if you remove irrelevant help topics from the TOC and the
Index, they will still be available through the Search unless you delete them
completely.
3.4 Formatting Standards for Help Topics
Helen provides a number of basic HTML formats that can be used to style page content. The
formatting and styles that must be used for SOLA Help topics are illustrated and described
below.
3 – Icon Image Use the Helen Insert Image tool to embed image icons.
To edit the table layout, use the mouse to right click within the
table. You will see 4 menu options – Table properties, Row
properties, Column properties and Cell properties. Open Table
properties and set the properties as follows.
9 – Indented Bullets
Use the Bullets tool and Indent tool for indented bullets. By
default, the indented bullet will change to an unfilled circle. You
need to right click the bullet list with your mouse and open the List
properties dialog to change the bullet style back to a filled circle.
If the new TOC item is intended to be used as a heading only, you can leave the target set to
<no target>.
You do not need to set any other properties for the TOC item.
If the new TOC item needs to be moved to a specific location in the TOC, drag it using the
mouse into the appropriate position.
judgement to structure the index, however be aware that creating the perfect index can be
time consuming. A simple index is preferable.
An important aspect of the index is that it should be listed in alphabetical order. Helen
provides a Sort Sub Items option in the popup menu to automatically sort all index entries by
their Text value. You should use this option regularly to order the index structure.
3.7 Map
The map.xml file contains a list of mapped references for each file in the project (HTML file
and Image files). Each map item is a name assigned to a physical file so that you can
reference the file from other help topics without hard coding the file location.
Generally when you use Helen to add a new file to the project, it automatically creates an
entry in the map.xml for you. If you manually copy a file into the project, you should also
make sure you add a new map item into the map.xml file. Just open the map.xml file in
Helen and right click the Map node and choose the relevant Add Map Item option (HTML or
Image).
3.7.1 Mapping an Anchor
By default, map items refer to a particular file. It is also possible to create a map item that
refers to an anchor point within a file. This can be very useful for hyperlinking when you need
to reference a specific section within a broader help topic. To map an Anchor, use the
Anchor tool to create an anchor at the section header within the help topic. You need to
give the anchor a unique name. Once you’ve done that, add a new Map Item into the
map.xml that references both the help topic and the anchor point. The new Map Item can
then be used in other hyperlinks to direct the user to the specific section within the help
topic.
3.8 Also See Section
Many of the SOLA Help Topics include an Also See section at the bottom that hyperlinks to
other help topics of direct relevance to the current topic. This provides an important method
for the user to navigate the SOLA Help and you should ensure the Also See section
accurately reflects the Also See lists from the User Guide.
The Also See section includes a number of hyperlinks and formatting which can be time
consuming to create from scratch within each help topic. Instead, you should create one file
that has all of the relevant structure and hyperlinks. You can then copy this into each help
topic and edit it has required (i.e. delete the unnecessary links). If you have copied an
existing SOLA Help project, you should find a file called also_see in the appendix folder that
has the hyperlinks and formatting already setup. As you make changes to the SOLA Help,
edit this master Also See list so that you can quickly update the Also See section for any
new or existing topics when necessary.
If you have copied an existing SOLA Help Project, most of these values should already be
configured, but it is worthwhile to verify the settings and update them if required.
3.9.1 General tab
On the General tab you should set the Title Bar Entry to indicate the name for the help
project. You can give this any name as it will not be displayed to the user. You also need to
check the Add Search Index checkbox so a full text search index can be created (see
Creating the Full Text Search Index section below).
For non-English help, you should set the Locale to the appropriate language code. This is
used by Helen to assist when creating the full text search index as well sorting items in the
Index. For English based help, leave this value empty.
viewing. Usually the about topic is the best option to use as the Start Page, but you can use
a different topic if you think it is more appropriate.
3.9.3 Presentations
You need to create a custom Presentation for the SOLA Help. This is effectively the
standard Help Viewer with some minor customization. If there is no entry on the
Presentations tab, click Add… to create a new presentation. If you see an entry called man
(or similar name), highlight it and click Edit…. Both buttons should show the Presentation
Editor and you should configure it as shown below.
The Window Title needs some manipulation. The custom colour theme used for the SOLA
applications is inherited by the Help Viewer when the help is opened from the SOLA
application. You will notice that the icon and the window title will overlap unless the window
title is padded to the right by 8 spaces. Unfortunately any spaces you enter in the Window
Title field are removed when the values are saved to the underlying xml file. To ensure the
spaces are preserved, you need to edit the HelpSet.xml file using a text editor and type the
HTML entity for space ( ) into the file as shown below.
You should avoid making further edits to the Windows Title field using the Presentation
Editor dialog. If you do you will need to manually edit the title in the HelpSet.xml file again.
3.9.4 Other tabs
Other than adding additional stopwords on the Search tab, no further configuration of the
other tabs should be required. Guidelines for adding stopwords are discussed in the
Creating the Full Text Search Index section.
3.10 Verifying the SOLA Help
To verify the SOLA Help, use the Check Project Consistency tool . This will validate all
of the project elements and show any warnings or errors in the Message Console. There will
be some warning messages that you can ignore, such as No target defined for top level
folders in the Index and the TOC. Error messages will usually indicate an inconsistency in
the help files (i.e. references to files that no longer exist) so you should investigate and
resolve those issues where possible. The messages in the console are hyperlinked, so you
can double click them to be redirected to the relevant issue.
3.11 Creating the Full Text Search Index
JavaHelp provides inbuilt support for a full text search index allowing the user to search the
entire content of the help based a key word or words. For this index to work you need to;
1) Check the Add Search Index option in the Optional Navigation Views of the General
tab of the HelpSet.xml file
2) Use the Create / Update Search File tool in the Helen toolbar to generate or
regenerate the search indices.
Notes
If you make any changes to the help files (e.g. change the text, update the title
element or add a new help topic), then you must regenerate the indices using the
Create / Update Search File tool. It’s best to avoid creating the search index until the
very last activity before integrating the help project into the SOLA application.
Make sure you have set the title element on every help topic page using the HTML
Code view. The title is displayed in the search results and is set to the filename by
default. You should set the title element to the same value as the topic heading.
3.11.1 Stopwords
Stopwords are common words (such as the, of, is, it, etc.) that should not be indexed. Helen
has a global stopword file to omit common English words. However it may be necessary to
add common stopwords for other language translations. If you do need to add extra
stopwords, use the Search tab on the HelpSet.xml file.
In most cases the map id will be the same as the filename assigned to the help topic. E.g. for
the application_details.html file, the map id is application_details. If you need to confirm the
map id, check the map.xml file using Helen.
Notes
The helpTopic property is only available for screens that inherit from the
ContentPanel class. Modal screens and popups in SOLA do not support context
sensitive help.
If you want the context sensitive help to display a section within a broader help topic,
use an anchor in the topic and create a map id for the anchor as described in the
Map section above.
4.3 Test and Commit
Once the SOLA Help has been copied into the Common Help project and all of the
helpTopic properties configured, you can compile and test the SOLA application to verify the
help displays as expected and that the F1 context sensitive help is also working. If this all
works, you can commit and push the changes to Github.