Ficheros de configuracion de JavaHelp
Para poder trabajar con JavaHelp, además de los ficheros .html en los que escribimos nuestra ayuda, necesitamos varios ficheros de configuración, en los que JavaHelp encontrará toda la información de dónde están nuestros ficheros .html y cómo presentarlos.
Vamos a ver aquí sólo los ficheros básicos mínimos imprescindibles, sin entrar en demasiados detalles ni mostrar todas las posibilidades que ofrecen. Toma este artículo como una forma de empezar y entender la filosofía de estos ficheros. Luego necesitarás algo más avanzado.
Los ficheros .html[editar]
Debemos escribir el texto de nuestra ayuda en ficheros .html. Cada fichero se mostrará completo en la ventana de ayuda, por lo que debemos dividir esos ficheros en tantos como pantallas de ayuda distintas queramos. Dentro de un directorio que podemos llamar "ayuda", podemos escribir estos ficheros, organizándolos por subdirectorios a nuestro gusto.
Como ejemplo, en el subdirectorio huevo, ponemos un fichero freir_huevo.html con un contenido similar a este
<html>
<head>
<title>Freir un huevo</title>
</head>
<body>
<h1>Freir un huevo</h1>
<p>Coge el huevo, cascalo y a la sarten</p>
</body>
</html>
Un mapa de JavaHelp[editar]
El primer fichero que necesitamos es un fichero en el que se indiquen todos los ficheros .html que componen nuestra ayuda. En este fichero-mapa damos a cada fichero .html una clave o nombre, que nos servirá a partir de ahora para identificar dicho fichero de ayuda.
Este fichero mapa tiene formato xml, pero se le suele poner extensión .jhm (java help map). Lo normal es colocarlo en el directorio "ayuda" que creamos antes, junto o por encima de los ficheros .html de nuestra ayuda.
ayuda
+---- mapa.jhm
+---- la_sarten.html
+---- huevo
+----- freir_huevo.html
+----- cascar_huevo.html
Los ficheros la_sarten.html y cascar_huevo.html son otros ficheros de ayuda que hemos puesto.
El contenido del fichero mapa.jhm, es formato xml y puede ser como este
<?xml version='1.0' encoding='ISO-8859-1'?> <!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 2.0//EN" "http://java.sun.com/products/javahelp/map_2_0.dtd"> <map version="1.0"> <mapID target="freir" url="huevo/freir_huevo.html" /> <mapID target="cascar" url="huevo/cascar_huevo.html" /> <mapID target="sarten" url="la_sarten.html" /> </map>
La primera parte es lo habitual en cualquier fichero .xml
El resto, entre etiquetas map, son varios mapID. Una para cada fichero .html que tengamos de ayuda, con path relativo a la ubicación de este fichero .jhm -y del resto de ficheros de configuración que vayamos poniendo-. A cada fichero le damos una etiqueta con target, de forma que luego esa etiqueta nos servirá para referenciar al fichero, tanto en otros ficheros de configuración, como más adelante en nuestro código.
Tabla de Contenidos en JavaHelp[editar]
El siguiente fichero que necesitamos es una especie de tabla de contenidos. En ese fichero se van indicando los capítulos y subcapítulos de la ayuda. Lo que pongamos en este fichero es el típico árbol que saldrá a la izquierda en las ventanas de ayuda. Si ahora mismo, con tu navegador, pulsas F1 -o el botón de ayuda-, te saldrá una ventana de ayuda. Verás en ella, a la izquierda, un árbol con varios temas. Ese árbol el la tabla de contenidos.
El fichero de tabla de contenidos es también un fichero .xml, esta vez sí, con extensión .xml. En él simplemente ponemos el árbol, indicando el texto para cada nodo del árbol y el fichero .html que se debe mostrar cuando se pinche en ese nodo. Se puede, además, indicar cosas como si se quiere el nodo expandido o no por defecto, el icono, etc, etc. Pero vamos a lo simple, un fichero de contenidos simple toc.xml puede ser como este
<?xml version="1.0" encoding="ISO-8859-1"?>
<toc version="1.0">
<tocitem text="La sarten" target="sarten"/>
<tocitem text="El huevo">
<tocitem text="Freir un huevo" target="freir"/>
<tocitem text="Cascar un huevo" target="cascar"/>
</tocitem>
</toc>
Entre etiquetas toc, y en la forma que queramos luego el árbol, vamos poniendo varios tocitem anidados. En cada tocitem ponemos un text que es el que se mostrará en pantalla y opcionalmente, un target, que el fichero .html que se mostrará cuando pinchemos en el árbol este item. Por supuesto, se referencia al fichero .html a través de la clave que le dimos en el fichero mapa.jhm
Este fichero toc.xml lo colocaremos en el mismo directorio que el fichero mapa.jhm
HelpSet: el fichero principal de configuración de JavaHelp[editar]
Ahora nos falta el fichero principal de la ayuda. Es un fichero, también en formato xml, pero con extensión .hs (help set). En este fichero indicamos cuales son los otros dos ficheros que queremos usar -el mapa mapa.jhm y el de contenido toc.xml-, así como qué cosas queremos en nuestra ventana de ayuda.
Para este ejemplo simple, el fichero símplemente tendrá dos bloques. Uno para indicar cual es el fichero mapa map.jhm y otro bloque para indicar que queremos que la ayuda tenga una tabla de contenidos a partir del fichero toc.xml
El fichero ayuda.hs puede tener un contenido como este
<?xml version="1.0" encoding='ISO-8859-1' ?>
<!DOCTYPE helpset
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"
"http://java.sun.com/products/javahelp/helpset_1_0.dtd">
<helpset version="1.0">
<title>Friendo huevos</title>
<maps>
<homeID>sarten</homeID>
<mapref location="mapa.jhm"/>
</maps>
<view>
<name>Tabla Contenidos</name>
<label>Tabla de contenidos</label>
<type>javax.help.TOCView</type>
<data>toc.xml</data>
</view>
</helpset>
Como antes, la primera parte es la típica de un fichero xml. La etiqueta principal de este fichero es helpset.
Luego va un title, que el título que aparecerá en la barra de nuestra ventana de ayuda.
Un bloque maps, en el que se indica cual es el fichero de mapa con la etiqueta mapref, y cual es el fichero .html que se presentará inicialmente por defecto. Este fichero .html se indica en la etiqueta homeID y por supuesto, no se pone directamente el fichero .html, sino la etiqueta que le dimos en el fichero mapa mapa.jhm
El segundo bloque view es para indicar que queremos una tabla de contenidos. El type es para indicar que es de tipo tabla de contenidos. Hay otras opciones, como búsqueda, índice, etc. De momento, sólo tabla de contenidos y es eso lo que hay que poner javax.help.TOCView, para que javahelp identifique que es una tabla de contenidos.
name no es más que un nombre, label es el tooltip que aparecerá al dejar el ratón sobre la pestaña de tabla de contenidos que aparecerá en la venana de ayuda. Y finalmente, lo más importante, data es el fichero que define el árbol de la tabla de contenidos, nuestro fichero toc.xml
Este fichero ayuda.hs lo colocaremos en el mismo directorio que mapa.jhm y toc.xml
Aunque estos son los ficheros mínimos, podemos ampliar las funcionalidades de nuestra ayuda añadiendo Más ficheros de JavaHelp