Integration of Online Help

[Development@SIB]

Almost all professionally developed software comes with meaningful documentation. A user manual is necessary to support the user in his or her work. The internet is often used as a medium to make help available at any time. JVx provides a framework for the integration of online help. It is sufficient to provide text and pictures as standard HTML pages, JVx handles the integration.


How to integrate Online Help?

JVx Online Help is available for Download!

The archive contains the web client as well as the necessary libraries and configurations for the application server:

Code: Select all

- client
  - (Web client files)
- server
  - lib
    - (Server side libraries for Application Server)
  - web.xml (Deployment Deskriptor for Application Server)
- LICENSE.TXT
- NOTICE.TXT


We use the installation of Apache Tomcat to test online help. We want to create a new context in the webapps directory, called application and containing the subdirectories help and WEB-INF:

Code: Select all

- tomcat
  - bin
  - conf
  - logs
  - temp
  - webapps
    - application
      - help
      - WEB-INF
    - ROOT
  - work


All files and directories in the archive´s client directory are copied to the help Verzeichnis des Archivs. In das Verzeichnis WEB-INF kopieren wir alle Dateien und Verzeichnisse aus dem server Verzeichnis des Archivs.

Now it is time to start the application server and to test using the URL
http://localhost/application/help/. As a result, the following page should appear:

help_content.png (73.56 KiB) Viewed 8267 times

Files and Directories

We have decided to select the subdirectory help to integrate online help. This has not only proven useful in practice, it is also the default configuration in the deployment descriptor (web.xml):

Code: Select all

<servlet-mapping>
  <servlet-name>Help</servlet-name>
  <url-pattern>/help/services/Help</url-pattern>
</servlet-mapping>


However, you are of course free to adapt the configuration to your environment.

Although help is now displayed, the contents and text are only placeholders. Text is contained in the file help/index.html can be customized with any text editor:

Code: Select all

<!-- Dynamicly added text -->
<meta name="gwt:property" content="title=You are in the help .....">
<meta name="gwt:property" content="tree-title=Table of contents">
<meta name="gwt:property" content="print=Print">


The available contents/texts/documents are saved in the directory structure, as shown in the following example:

Code: Select all

- structure
  - 01_General
    - Userinterface
    - index.html
  - 02_Application
  - 03_Documents
    - references.pdf
  - index.html
  - structure.css
  - System overview.html


This should result in the following view, depending on the content of the file index.html:

help.png (83.44 KiB) Viewed 8267 times

Naming Conventions

The previous example outlines the structure of the help system: The file system is also your online help..

In addition, the following naming conventions are provided:

• Files with the extension .css are NOT displayed
• Files with the name index.html are NOT displayed
• Sorting is determined by a numerical prefix followed by _ (the prefix is not displayed) e.g.: 01_Z, 02_A
• If a directory contains the file index.html,it is displayed upon clicking on the relevant help entry
• Files with the extension .html are displayed; all other files, such as pdf, csv are offered for download. The mechanism can be used, for example, for providing specifications
• Icons for directories are determined based on the directory´s name (without sorting prefix) e.g.: 01_General -> general.png und general_expanded.png (png is required)
• Icons for files are determined based on the extension, e.g.: references.pdf -> pdf.png

Images/Icons

Icons for directories and files are saved in the directory help/images/tree. If no specified icons are available, the default icons (folder.png, folder_expanded.png, files.png) are used.

The file help/images/company.png has to be altered to change the company icon. Here the picture´s size has to be considered!