3.1.- Uso de JavaHelp

Para la creación de un sistema de ayuda, hay que realizar los siguientes pasos:

1-. Creación de los temas de ayuda. Lo primero que se debe definir, son los temas de ayuda para el usuario. Los temas de ayuda se denominan topics, y es necesario crear en este paso los "topics" HTML, que nos van a servir para organizar los contenidos de la ayuda.

2-. Creación de los ficheros metadatos JavaHelp. El sistema de ayuda JavaHelp, necesita la creación de un conjunto de ficheros, que permite organizar la información, y la navegación y búsqueda, dentro del sistema de ayuda. Estos ficheros son:

• Fichero map.
• Fichero HelpSet. Este fichero, junto con el fichero map y los topics HTML, son imprescindibles para crear el sistema de ayuda.
• Fichero de tabla de contenidos.
• Fichero índice.
• Fichero con la base de datos de búsqueda.

El sistema de ayuda va a generar un conjunto de ficheros. Estos ficheros, can a tener diferente formato y tienen propósitos diferentes. Una organización coherente del sistema de ayuda en directorios o carpetas, sería la siguiente:

Para la creación de los temas de ayuda (topics), se puede utilizar cualquier herramienta que permita la edición de ficheros de texto. Hay que tener en cuenta que los ficheros de "Temas de ayuda" tienen formato HTML. Dado que estamos generando un sistema de ayuda, es conveniente tener la información organizada, por ello, se suelen agrupar todos los topics que estén interrelacionados, organizándolos jerárquicamente.

Para la organización de los ficheros de ayuda, es recomendable la creación de un subdirectorio o subcarpeta propia.

Fichero map

El fichero map, tiene la extensión jhm (JavaHelp Map) y sirve para asociar todos los ficheros HTML, imágenes, etc. con un identificador. La sintaxis de este fichero se basa en XML. En la imagen siguiente, puede verse un ejemplo del contenido de un fichero map: 

Fichero HelpSet

En este fichero se fusionan y configuran todos los ficheros que forman la ayuda. Es el único fichero, del fichero de ayuda, que se referencia por la aplicación. Al igual que el fichero map, su sintaxis está basada en XML y tiene la extensión "hs". Este fichero va a contener toda la información necesaria, para que se pueda ejecutar el sistema de ayuda.

Este fichero, contiene información acerca del fichero map que se utiliza para relacionar las páginas HTML de la ayuda con sus identificadores. El helpset también contiene información sobre los navegadores que se emplean en el HelpSet, es decir, la tabla de contenidos, índice y búsqueda.

El fichero helpset, tiene un "tag" especial, que es <Home ID>, que sirve para identificar la página que se mostrará, cuando se solicite la ayuda sin especificar ningún identificador concreto.

Fichero TOC (Tabla de contenidos)

El fichero TOC (Table of Contents), sirve para describir el contenido de la ayuda y su distribución en la tabla de contenidos. Como los demás ficheros de configuración de JavaHelp, su sintaxis se encuentra basada en XML. En la imagen siguiente se puede ver un ejemplo del contenido de un fichero TOC:

Fichero Índice

 Utiliza sintaxis XML. Sirve para describir la distribución y contenido que va a tener nuestro sistema de ayuda. A continuación, se muestra, de ejemplo, el contenido de un fichero índice:

Búsqueda

Se puede diseñar un sistema de ayuda, que permita la búsqueda de determinados términos o conceptos, dentro de los contenidos. Para crear el sistema de búsqueda, es necesario utilizar la herramienta jhindexer, para que se pueda generar la base de datos de búsqueda. Si se programa el sistema de búsqueda, se generará una base de datos, que será almacenada dentro de la carpeta JavaHelpSearch. La creación de la base de datos de búsqueda, es un proceso que se realiza sobre los ficheros de contenidos.

El script jhindexer se ejecuta recibiendo como parámetro el directorio donde se encuentren los archivos con ayuda, y generará la base de datos de búsqueda. Su ejecución tiene la siguiente sintaxis:

jhindexer directorio_con_archivos_de_ayuda

La herramienta jhindexer va recorriendo el directorio indexando todos los archivos que va encontrando. Crea para ello la carpeta JavaHelpSearch donde almacena la base de datos de búsqueda. Para verificar el funcionamiento de la búsqueda, se puede ejecutar en línea de comandos la herramienta jhsearch con la sintaxis siguiente:

jhsearch JavaHelpSearch (o bien desde el visor de ayuda).

Ficheros JAR

Una vez finalizada la generación del sistema de ayuda, si quisiéramos distribuirlo con un fichero independiente, es recomendable su encapsulación en un fichero JAR.

Para la creación del fichero JAR con la ayuda, utilizamos la orden jar de Java. La sintaxis que seguiremos será:

jar -cvf ayuda.jar *

donde ayuda.jar será el fichero donde encapsularemos todos los archivos del sistema de ayuda. Este comando lo ejecutaremos en el directorio o carpeta donde hemos creado todos los ficheros de ayuda.

Si queremos ver los archivos incluidos en el archivo JAR, ejecutaremos el siguiente comando:

jar -tvf ayuda.jar

Para extraer los archivos del fichero jar, ejecutaremos el comando:

jar -xvf ayuda.jar

Añadir ayuda a las aplicaciones Java

Si hemos diseñado una aplicación de interfaz gráfica de usuario (GUI), lo normal es que dentro del menú principal tengamos una opción de ayuda. Cuando el usuario o usuaria de la aplicación ejecute esa opción, lo deseable sería que se le abriera una ventana con la ayuda de la aplicación, en el formato JavaHelp. Para poder incorporar la ayuda implementada en JavaHelp, es necesario añadir al proyecto un conjunto de librerías y de paquetes.

Utilizaremos la clase HelpSet que nos permite utilizar desde una aplicación Java, todos los ficheros y datos que constituyen el sistema de ayuda, como puede ser el fichero helpset, la tabla de contenidos, el índice, etc. Dentro de esta clase, vamos a necesitar los métodos findHelpSet, que localiza el fichero helpset y devuelve su URL y el método createHelpBroker, que nos permite crear un objeto HelpBroker.

Para poder utilizar esta clase, será necesario importar a nuestro proyecto el paquete javax.help a través de la instrucción:

import javax.help.*

También será necesario utilizar la clase HelpBroker. Se encarga de visualizar el contenido de la ayuda en la aplicación. Para ello, incorpora una serie de métodos que facilitan la incorporación de ayuda en la aplicación. Al igual que la clase HelpSet, forma parte del paquete javax.help.

Dentro de esta clase destacan los métodos:

• enableHelpKey: que habilita la tecla de ayuda sobre un componente.
• enableHelpOnButton: que permite que se despliegue la ayuda cuando se presiona un botón o un determinado elemento del menú.
• enableHelp: que nos indica el tema de ayuda a mostrar, cuando se pulsa la tecla de ayuda sobre un determinado componente.