Describir y empaquetar el contenido de las ayudas emergentes

Las ayudas emergentes se describen asociando el ID de contexto declarado en el código de la UI a una descripción y a una lista de enlaces que llevan a los temas relacionados de la ayuda en línea. Estas asociaciones se hacen dentro de un archivo XML. Puede crear cualquier número de archivos XML que contengan asociaciones de ayudas emergentes para cada conector. La descripción y los enlaces de cada ID de contexto se colocan dentro de los elementos <context> del archivo XML. Cada elemento context puede tener un elemento <description> opcional que sirve para describir el objeto de la UI, así como cualquier número de elementos <topic>, que enlazan con la documentación en línea.

<contexts>
	<context id="panic_button">
		<description>Este es el botón Pánico.</description>
		<topic href="tasks/pushing_the_panic_button.htm" label="Pulsar el botón Pánico"/>
		<topic href="reference/panic_button.htm" label="Referencia del botón Pánico"/>
	</context>
	...
</contexts>

Una vez descritos los contextos en el archivo (o archivos) XML, ya podrá hacer referencia a los archivos de contexto en el manifiesto del conector. Observe que el ID de contexto anterior no está totalmente calificado. Esto está permitido siempre que el archivo de contexto sea una contribución suministrada en el manifiesto del conector que definió el ID del contexto. Es decir, el ID del contexto se resuelve en el ID del conector que suministró el archivo XML como contribución.  

El conector, para contribuir suministrando archivos de contexto, debe utilizar el punto de extensión org.eclipse.help.contexts.

   <extension point="org.eclipse.help.contexts">
      <contexts name="myInfopops.xml"  />
   </extension>

Podrá hacer referencia a los archivos de contexto desde otros conectores si incluye el atributo plugin. Esto le permite agrupar la totalidad de su documentación, incluso las ayudas emergentes, en un solo conector, y hacer referencia a él desde el conector del código de la UI o desde otro conector relacionado.

   <extension point="org.eclipse.help.contexts">
      <contexts name="myInfopops.xml" plugin="com.example.helpExample"  />
   </extension>

Como puede ver, dispone de gran flexibilidad a la hora de organizar las ayudas emergentes en uno o más archivos contenidos en uno o más conectores. La cuestión principal a tener en cuenta es que los ID de contexto de los archivos se resuelvan correctamente. Si no califica totalmente un ID de contexto, deberá contribuir suministrando los archivos XML de contexto en el conector que declaró los ID de contexto. Si utiliza identificadores de contexto totalmente calificados en el archivo XML de contexto, dispondrá de una flexibilidad completa a la hora de situar los archivos XML y de decidir qué conector suministra los contextos como contribución.

Ayudas emergentes de múltiples conectores

Otro nivel de flexibilidad es la capacidad de contribuir suministrando ayudas emergentes del mismo ID de contexto desde distintos conectores. Esto es de utilidad si hay, por ejemplo, distintos conjuntos de conectores de documentación que se puedan o no instalar en la configuración de un usuario. Esto permite que cada conector de documentación declare sus contextos de forma independiente. El usuario final verá el contenido fusionado de las ayudas emergentes de todos los conectores que hayan contribuido con contextos para el ID del widget.

Tenga presente que hay que utilizar el ID de contexto totalmente calificado del widget, porque ninguno de los conectores de documentación declararon el ID de contexto. Cuando hay múltiples conectores que contribuyen suministrando ayudas emergentes para un mismo ID de contexto, el que se muestra en primer lugar es el contenido definido en el conector que declaró el contexto (el conector de la UI). Las descripciones y los enlaces adicionales se añaden a continuación, aunque en un orden indefinido.

Copyright IBM Corp. y otros 2000, 2002.