Creación de SISTEMA DE AYUDA en Java utilizando JAVAHELP

Quizás muchos de vosotros no hayáis pensado que incluir la típica “Ayuda” en la barra de herramientas de vuestras aplicaciones le ofrecerá un valor añadido a vuestro cliente y quizás os pueda ahorrar de las pesadas conservaciones con cliente que ha contratado vuestros servicios.

En muchos de los casos las aplicaciones quizás no requieran, por su complejidad, un manual de soporte al usuario final. Sin embargo, en proyectos mayores servirá como documentación adicional que el usuario podrá consultar para resolver posibles problemas que puedan surgirle sin necesidad de tener que ponerse en contacto con el desarrollador de la aplicación.

Que dispongamos de esta herramienta para la plataforma Java y que su uso no sea sumamente complicado no significará que sea necesario desarrollar la ayuda para el clásico tres en raya; el usuario no la consultará nunca y eso se verá traducido en trabajo inútil que nunca será valorado. ¿Para que comprarte un 200cv si no puedes pasar de 120 km/h…?

Llegados a este punto creo que no es necesario describir que es JavaHelp. Se trata de un conjunto de herramientas que permiten crear el clásico sistema de ayuda con unos resultados profesionales.

El resultado dependerá, como no, de lo que se lo trabaje cada uno. Quizás alguna vez hayáis entregado un manual de usuario a vuestro cliente; pues bien, este manual puede haber sido más o menos consultado en función del empeño que hayáis puesto en él.

Para poder llevar a cabo nuestro sistema de ayuda deberemos disponer de la máquina virtual JAVA, de un IDE para el desarrollo (yo utilizo NetBeans), un editor de texto y del fuente JavaHelp, que podéis descargar en http://java.sun.com/products/javahelp/download_binary.html. El binario contendrá las clases necesarias para desarrollar la ayuda y los ficheros JAR necesarios para distribuir con la aplicación.

Como habéis podido ver en tutoriales anteriores, el estándar XML ofrece un abanico infinito de posibilidades. Aquí no iba a ser menos. Para el desarrollo de nuestra ayuda deberemos crear 3 archivos que seguirán el citado estándar. Los formatos de los ficheros serán *.jhm, *.xml y *.hs. Ándate con cuidado, JavaHelp es Case-Sensitive.

1.- Fichero JHM: El formato para este archivo deberá ser el siguiente:

Lo que haremos en este fichero será definir cada una de las páginas que compondrán nuestra ayuda (que deberán estar en formato HTML). Un ejemplo podría ser “altaCliente.html”, “bajaCliente.html”, “asociarCliente.html”… Además definiremos los iconos que se utilizarán para mostrar los nodos (carpeta raíz desplegada, carpeta raíz cerrada,…).

Un ejemplo real de este fichero podría ser el siguiente:

En el ejemplo se han definido 5 páginas (archivos html) y 6 iconos (archivos de imagen).

2.- Fichero XML: Ahora será necesario, para cada entrada creada anteriormente, asignarle un nombre, que será el que se muestre en el árbol jerárquico. Analicemos el siguiente ejemplo:



CategoryOpenImage y CategoryClosedImage hace referencia al icono que se mostrará cuando el nodo padre del árbol esté desplegado/plegado. TopIcImage será el icono que se mostrará en los nodos hoja, text será el texto del nodo y target la referencia asociada a la página, que se ha identificado en el fichero JHM.

3.- Fichero HS: El formato de este fichero, así como la explicación de cada uno de los valores es el siguiente:



Una vez creados estos 3 ficheros crearemos un índice con las palabras clave que compongan nuestro manual. Para ello deberemos hacer uso del script jhindexer que encontraremos en javahelp/bin. Supongamos que tenemos todos nuestros ficheros html en la carpeta JavaHelp (como es mi caso); deberemos teclear, pues, en la línea de comandos jhindexer JavaHelp.

El Script nos creará una carpeta (JavaHelpSearch). Es importante que este comando lo ejecutemos una vez tengamos la jerarquía de directorios creada ya que si movemos los ficheros deberemos volver a ejecutar el script ya que se perderán las referencias a los índices creados.

Ahora será interesante realizar una vista de cómo se mostrará nuestra ayuda antes de integrarla en la aplicación. Para ello utilizaremos un jar que se encuentra en demos/bin (dentro de la carpeta JavaHelp, claro está). Para realizar esta vista previa ejecutaremos la instrucción java – jar hsviewer.jar. Se nos mostrará un cuadro de diálogo en el que deberemos especificar, en el primer campo, el nombre del fichero hs junto con su extensión (por ejemplo: ayuda.hs). En el segundo campo deberemos definir la ruta.

El último paso será añadir el sistema JavaHelp a nuestra aplicación. Primero deberemos añadir las clases necesarias para su correcta compilación y funcionamiento. Posteriormente deberemos definir la URL del fichero con extensión hs y crearemos una instancia del objeto HelpSet. El tercer paso será instanciar un objeto de la clase HelpBroker. Únicamente nos quedará asignar el evento al botón que vayamos a utilizar para mostrar la ayuda (por ejemplo al pulsar F1). El código resultante podría asemejarse al siguiente:

…
import javax.help.*;
…
try {
URL hsURL = HelpSet.findHelpSet(null, "../help/fichero.hs");
hs = new HelpSet(null, hsURL);
} catch (Exception e) {
System.out.println("HelpSet "+hs+" no encontrado")
return;
}
…
HelpBroker hb = hs.createHelpBroker();
help_browser.enableHelpOnButton(btnHelp, "introduction", hs);

Recuerda que será necesario que añadas una de las librerías de sistema (las de extensión jar) en el classpath de tu aplicación (por ejemplo, jh.jar).