Tutorial de JavaHelp

Índice:

• ¿Qué es JavaHelp?
• ¿Qué puedo hacer con JavaHelp?
• ¿Qué necesito para trabajar con JavaHelp?
• Manos a la obra (El Ejemplo)
• Observaciones
• Conclusiones

¿Qué es JavaHelp?

JavaHelp es un API que junto con un conjunto de herramientas nos permite crear potentes ayudas para integrarlas en nuestras aplicaciones.

Las ayudas que puedes realizar con JavaHelp no tienen nada que envidiar a ninguna de las ayudas que puedan tener cualquiera los programas más profesionales del mercado.

Además, a diferencia de otros sistemas de ayuda, JavaHelp es independiente del sistema operativo.

¿Qué puedo hacer con JavaHelp?

Pues puedes hacer ayudes muy profesionales con índices, Tablas de contenidos, Glosario de términos, sección de favoritos, motor de búsqueda, formato increíblemente rico, Ayudas poppups, Context-Sensitive, etc..

Eso si, te lo tienes que trabajar.

¿Qué necesito para trabajar con JavaHelp?

Necesitas la máquina virtual de Java y el JavaHelp que se puede descargar desde la siguiente dirección: http://java.sun.com/products/javahelp/download_binary.html.

Desde esa dirección te descargas el JavaHelp 2.0_02 y lo descomprimes en la carpeta que te venga bien. El fichero contiene entre otras cosas las herramientas (scripts) que te permitirán crearte el índice, la tabla de contenido. Y los JARS que debes distribuir junto a tu aplicación para que funcione el sistema de ayuda.

Manos a la obra (El Ejemplo)

Vamos a hacer un ejemplito sencillo, pero muy didáctico.

Haremos una ayuda con una tabla de contenido jerárquica con carpetas y páginas, en donde el usuario pueda realizar búsquedas y modificaremos los iconos por defecto para que quede más profesional…

Puede descargarse las imágenes y las páginas Web que necesitamos para este ejemplo haciendo JavaHelp.zip.

Para crear la ayuda que deseamos realizar necesitamos crear tres ficheros de texto con formato XML.

1) El primero de ellos tiene extensión .jhm (JavaHelp Map) y en el definimos una asociación entre todos los ficheros HTML, imágenes, etc. que componen la ayuda y un identificador. Es decir en los demás ficheros que componen JavaHelp y en nuestras aplicaciones siempre nos referimos a través de un identificador.

ejemplo.jhm

Los tres primeros elementos hacen referencia a Páginas Web y el resto a iconos que se usarán en las ventanas en sustitución a los iconos por defecto.

2) El segundo de ellos define la tabla de contenido que deseamos para nuestra ayuda. También es un fichero de texto con formato xml.

ejemploTOC.xml

• categoryclosedimage: Icono que representa una carpeta cerrada.
• categoryopenimage: Icono que representa una carpeta abierta.
• topicimage: Icono que representa a un nodo hoja del arbol.
• Text: Texto que se mostrará al usuario.
• Target: Página Web que se mostrará al seleccionar el nodo.

3) El tercero y ultimo de los ficheros que necesitamos para este ejemplo se llama Java HelpSet, tiene extensión .hs y en el se fusiona y configura en sistema de ayuda que deseamos. Es decir que ventanas y vistas queremos utilizar (Búsqueda, Tabla de contenidos, Popup, etc) todo.

ejemplo.hs

Bueno pues ya tenemos los ficheros que necesitamos.. pero antes de mostrar la ayuda, tenemos que pedirle a JavaHelp que nos cree una base de datos con las palabras que componen nuestros ficheros HTML de ayudas.

Para ello usaremos el script jhindexer que se encuentra en el directorio javahelp/bin.

Como nuestros ficheros HTML de ayudas estaban en el directorio JavaHelp escribimo:s jhindexer JavaHelp.

Nos creará un directorio de nombre JavaHelpSearch que no tenemos que tocar ni cambiar de sitio… Lo usará el motor de búsqueda de JavaHelp. Eso si, si cambiáis los HTML, deberéis volver a ejecutar el jhindexer.

Antes de aprender como llamaríamos desde nuestra aplicación a JavaHelp para que mostrase la ayuda, vamos a mostrar la ayuda utilizando una aplicación que viene con JavaHelp.

La aplicación está en el directorio demos/bin de la carpeta donde instalamos el JavaHelp y la podemos ejecutar desde la línea de comandos con la siguiente instrucción:

java –jar hsviewer.jar

Nos aparecerá una ventana similar a la que se muestra en la siguiente imagen y en ella seleccionamos el HelpSet donde definimos nuestra ayuda.

Aceptamos y nos aparecerá nuestra ayuda (ver Ilustración 1)

.

Ahora para finalizar, mostramos el código que debemos poner en nuestras aplicaciones para que al pulsar F1 se muestre la ayuda.

Observaciones

– Cuidado con las mayúsculas y las minúsculas en todas partes.. para JavaHelp index.htm es distinto a Index.htm.. es decir es Case-Sensitive.

– El Renderer de páginas HTML de JavaHelp no es un Internet Explorer o un Mozilla, así que si queréis que se vean decentemente las ayudas usar un conjunto de HTML básico… por ejemplo un HTML versión 4 transacional.

Conclusiones

JavaHelp es una opción interesante para crear las ayudas para aplicaciones y applets Java. Pues es potente, flexible e independiente del sistema operativo.

Hacer una buena ayuda ya depende de las ganas que le quieras dedicar.