Java Help with Helen

SOLA Community - Java Help with Helen

Revision History
Date Version Description Author

Mar 31, 2015 1.0 Release Andrew McDowell

Mar 30, 2015 v1.0 Page 2 of 23

 SOLA Community - Java Help with Helen

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

4. Integrating the Help into SOLA 22

4.1 Adding the SOLA Help files to the SOLA source code 22
4.2 Setting up Context Sensitive Help 22
4.3 Test and Commit 23

Mar 30, 2015 v1.0 Page 3 of 23

 SOLA Community - Java Help with Helen

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.

Mar 30, 2015 v1.0 Page 4 of 23

 SOLA Community - Java Help with Helen

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.

Figure 1 - Existing SOLA Help Project

Mar 30, 2015 v1.0 Page 5 of 23

 SOLA Community - Java Help with Helen

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.

Mar 30, 2015 v1.0 Page 6 of 23

 SOLA Community - Java Help with Helen

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.

Mar 30, 2015 v1.0 Page 7 of 23

 SOLA Community - Java Help with Helen

2.5.1 Capturing screenshots

Most of the images in the User Guide are screenshots that illustrate the full extent of the
form being described. You should use full screenshots that show the menu and frame of the
application in preference to partial screen captures (i.e. clipped images) as full screenshots
provide visual cues and better context to the reader by reflecting what a user sees when
they run the application. Taking a clipped image showing a limited portion of the form should
only be used where the User Guide describes a specific feature that requires additional
illustration.

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.

Mar 30, 2015 v1.0 Page 8 of 23

 SOLA Community - Java Help with Helen

Figure 2 - MS Word Layout dialog

For the SOLA Help, the width of each screen needs to be resized to a maximum of 640px.
Although it is possible to specify the image size directly in the Help topic HTML page – do
not do this. The image resize function for JavaHelp is very rudimentary and it results in poor
quality images. You should use a suitable image editing app to resize the images instead.
One very good free tool for image resizing is paint.net (http://www.getpaint.net/index.html). It
provides a “Best Quality” resize option that yields a similar result to the MS Word Image
Resize function.

Figure 3 - Resize dialog for paint.net

Notes

 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

Mar 30, 2015 v1.0 Page 9 of 23

 SOLA Community - Java Help with Helen

source code and placed in the images/icons folder of the help project. Do not clip them
from a screenshot.

Mar 30, 2015 v1.0 Page 10 of 23

 SOLA Community - Java Help with Helen

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.

Figure 4 - Helen GUI

If you need to get a better understanding of the Helen GUI, the best reference is the Helen
Help (Help > Help Topics or ). There are also two tutorials explaining how to use Helen in
Wizard Mode and Advanced Mode. It’s recommended you use the Advanced Mode for
editing the SOLA Help files, however you can use the Wizard Mode if you prefer.
3.2 HTML Page Views
Each HTML page represents a topic within the help file. When you open an HTML page in
Helen you will see it provides 2 different views of the page; a Design view and a Code view.
3.2.1 Design View
The Design view provides an HTML WYSIWYG editor (What you see is what you get) that
lets you format and edit the topic much as you would using a Word Processor. You can also
copy and paste text directly from MS Word or another document editor. Be aware that you
should only copy and paste plain text from a source document as any formatting from the
source document (text formatting or embedded images) will likely display as a sequence of
tags when pasted into Helen. If you do see tags displayed in Helen (see the figure below for
an example), you can remove the tags by simply selecting and deleting them.

Mar 30, 2015 v1.0 Page 11 of 23

 SOLA Community - Java Help with Helen

Figure 5 - Text copied from MS Word with an embedded image

3.2.2 Code View
The code view shows the raw HTML code for the help topic. To access the Code view, click
the Code tab at the bottom of the Content Pane. You will mainly use the Design view for
editing the HTML documents, but you will need to use the Code view from time to time to
correct formatting and to set the title element for each page. The title element is not editable
from the Design view however when a user does a search using the Help Viewer, it’s the title
of the topic that’s displayed in the search results rather than the heading. The default value
for the title is the file name which usually isn’t very helpful to end users. To avoid this issue
you should use the Code view to make sure the title element is set to the same value as the
h1 heading element, e.g.

Figure 6 - Setting the title element

3.3 Adding and Removing Help Topics
To add a new Help Topic, simply right click the folder in the Project Tree that you want to
add the HTML page to and choose New HTML Document. This will open the New HTML
Document dialog. Add a Document name (i.e. filename) and set the display values for the
index and TOC. Note that you can update these values later if necessary.

Figure 7 - New HTML Document dialog

Mar 30, 2015 v1.0 Page 12 of 23

 SOLA Community - Java Help with Helen

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.

Figure 8 - Design view

The above illustration highlights the formatting common to the HTML Help topics. Those
formats are

Mar 30, 2015 v1.0 Page 13 of 23

 SOLA Community - Java Help with Helen

1 – Header Heading 1 text style.

2 – Text Normal text style.

3 – Icon Image Use the Helen Insert Image tool to embed image icons.

Figure 9 - Image dialog

All icon images should be 16x16 images with Horizontal Space set
to 4. 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.

If you notice an image icon that appears distorted or stretched

when you view the help topic from the Help Viewer, verify the Width
and Height properties are set to 16 and the Ratio checkbox is
checked as shown above.
4 – Screenshot & Use the Helen Insert Image tool to embed screenshots. These
Caption
should be centred and have a maximum width of 640 pixels.
The screenshot caption is the Normal text style, bolded and
centred.
5 – Margin The Help topic should have a minimum left margin of 20 pixels (or
right margin if the language has right to left orientation). You can
set this quickly using the Indent Tool . Select the text (or the
entire page content) and click the tool once to set a 20 pixel indent.
6 – Table As with the User Guide, most tables are used for text alignment
and they omit borders. To add a table into a help topic, use the
Table tool . The tool lets you to select the number of columns
and rows for the table.

Mar 30, 2015 v1.0 Page 14 of 23

 SOLA Community - Java Help with Helen

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.

Figure 10 - Table Properties dialog

These settings will remove the table border. If you do need to show
a border, set the Border size to 1 or more. You may also want to
reset the Cell padding and spacing when a border is displayed.
Use the Column properties to set the Vertical Alignment to Middle
for each column of the table.

Figure 11 - Column Properties dialog

To add or remove columns use the table tools

7 – Table Bullets
Use the Bullets tool for table bullets. No other formatting is
required.

Mar 30, 2015 v1.0 Page 15 of 23

 SOLA Community - Java Help with Helen

8 – Subheadings Heading 2 text style

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.

Figure 12 - List Properties dialog

10 – Also See Links

The Also See list uses indented bullets and Hyperlinks to
reference related help topics. The Also See Section provides more
details on how to format this style.
11- Numbering
Not shown on the screenshot above. Use the Numbering tool
for numbering steps. Primary steps should use numeric numbering.
Sub steps should use lower case characters (e.g. a. b. c. etc.)
3.5 Table of Contents
Open the toc.xml file to create or edit the Table of Contents for the SOLA Help. The basic
structure of the TOC should follow the main sections in the User Guide with some minor
adjustments. E.g. the License topic and topics discussing how to use the SOLA Help should
be at the top level.
3.5.1 Adding a TOC Item
To add a TOC item, right click the folder you want the item to be shown in and select Add
Sub Item from the popup menu. It will show as $undefined$ at the bottom of the TOC tree.
Select the new item and enter the display text for the item (Text field) in the Property
Inspector. If the item is to be linked to a help topic, select the appropriate file in the Target
dropdown. If the file is not shown in the Target dropdown, it’s because the file hasn’t been
added into the map.xml file. See the Map section for further details.

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.

Mar 30, 2015 v1.0 Page 16 of 23

 SOLA Community - Java Help with Helen

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.

Figure 13 - Table of Contents File

3.6 Index
The index.xml file can be used to create an Index view of the SOLA Help content. This is not
the same as the Full Text Search Index. This index is intended to represent an index you
would find in the back pages of a user manual or technical reference.

Figure 14 - Index File

New items can be added to the index using the same method as adding TOC items. The
index structure for SOLA is a relatively basic 2 tier structure, with a folder representing a key
SOLA concept and one or more items linking to help topics relevant to that item. Use your

Mar 30, 2015 v1.0 Page 17 of 23

 SOLA Community - Java Help with Helen

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.

Mar 30, 2015 v1.0 Page 18 of 23

 SOLA Community - Java Help with Helen

Figure 15 - Master Also See page

3.9 Project Level Configuration
Project level configuration is set in the HelpSet.xml file. When you view this file in Helen, it
displays a number of tabs including General, Map, Presentations, Implementation,
index.xml, toc.xml and Search.

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.

Figure 16 - HelpSet.xml General tab

3.9.2 Map tab
On the Map tab, you need to set the Start Page. This is the help topic that will be displayed
by default when the user opens help from the Help menu. Note that if you launch the help
using the F1 key, it should display the help topic corresponding to the screen you are

Mar 30, 2015 v1.0 Page 19 of 23

 SOLA Community - Java Help with Helen

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.

Figure 17 - Customizing the JavaHelp Viewer

For the Window Icon, use the logo for the SOLA application you are working on. It should be
approx. 48x48 pixels with a transparent background.

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 (&#160;) into the file as shown below.

Figure 18 - Presentation Title padded with 8 spaces

Mar 30, 2015 v1.0 Page 20 of 23

 SOLA Community - Java Help with Helen

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.

Figure 19 - Adding Stopwords

Mar 30, 2015 v1.0 Page 21 of 23

 SOLA Community - Java Help with Helen

4. Integrating the Help into SOLA

4.1 Adding the SOLA Help files to the SOLA source code
Once you are satisfied with the SOLA Help content, created the full text search index and
verified the help files, you can copy the files into the SOLA Common Help project. The folder
to place the SOLA Help files is
…code\common\help\src\main\resources\org\sola\common\help where code is the root
directory for the SOLA application source code. If the SOLA Help is English language, you
should place it in a sub-folder called defaultlang. If the SOLA Help is in another language,
you need to determine the 2 character code for the language and create a subfolder with
that name. E.g. for Russian help, the subfolder must be called ru. For French help, the
subfolder must be called fr, etc. Note that the subfolder names must also be lower case.
4.2 Setting up Context Sensitive Help
The SOLA HelpUtility class supports context sensitive help. This means if a user is viewing a
screen in the application, when they press the F1 key, the Help Viewer is displayed showing
the help topic that corresponds to the screen the user is looking at. To make this work, you
need to use Netbeans to set the helpTopic property on the various SOLA screens so that it
matches the map id for the corresponding help topic.

Figure 20 - Setting the helpTopic from Netbeans

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.

Mar 30, 2015 v1.0 Page 22 of 23

 SOLA Community - Java Help with 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.

Mar 30, 2015 v1.0 Page 23 of 23