Las hojas de apuntes son vistas especiales que guían al usuario a través de una serie de tareas complejas para alcanzar una meta global. Por ejemplo, una hoja de apuntes puede utilizarse para guiar al usuario a través de todos los pasos necesarios para crear, compilar y ejecutar un programa simple Java. Las hojas de apuntes se lanzan desde la opción de menú Ayuda>Hojas de apuntes.... También pueden lanzarse desde una página introductoria.
Las hojas de apuntes se definen mediante el punto de extensión org.eclipse.ui.cheatsheets.cheatSheetContent. El contenido de la hoja de apuntes se define en un archivo independiente a fin de facilitar su traducción a otros idiomas.
La adición de una hoja de apuntes es bastante directa. Examinemos una hoja de apuntes añadida por JDT para construir una aplicación simple Java:
<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent"> <cheatsheet name="%cheatsheet.helloworld.name" contentFile="$nl$/cheatsheets/HelloWorld.xml" id="org.eclipse.jdt.helloworld"> <description>%cheatsheet.helloworld.desc</description> </cheatsheet> ...De forma muy similar a otras contribuciones del entorno de trabajo, pueden especificarse un nombre, una descripción y un ID para la hoja de apuntes. El nombre y la descripción se muestran cuando el usuario accede a la lista Ayuda>Hojas de apuntes.... También puede definirse una categoría para la hoja de apuntes si desea colocar varias hojas de apuntes en una agrupación lógica. Si no se especifica ninguna categoría, la hoja de apuntes aparecerá en la categoría Otras.
El trabajo real de las hojas de apuntes se realiza en el archivo de contenido. El archivo de contenido es un archivo XML cuyo nombre y ubicación se especifican en el atributo contentFile. La vía de acceso del archivo es relativa al directorio del conector. (Preste atención a la utilización de la variable $nl$ en el nombre del directorio, que indica que el archivo se ubicará en un directorio específico del idioma nacional del entorno destino).
El formato del archivo incluye información general acerca de la hoja de apuntes, seguida de una descripción de cada uno de los pasos (denominados elementos) que el usuario realizará. En su forma más simple, un elemento es simplemente una descripción detallada del paso que el usuario debe realizar. Sin embargo, un elemento también puede especificar una acción que puede ejecutarse para realizar el paso en nombre del usuario. Observemos la primera parte del archivo de contenido (HelloWorld.xml) de la hoja de apuntes Java.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Aplicación simple Java"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Bienvenido a la guía de aprendizaje Java Hello World. Le ayudará a construir y probar la famosa aplicación "hello world". Creará un proyecto Java y una clase Java que imprimirá "hello world" en la consola cuando se ejecute. Vamos a empezar. </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Abrir la perspectiva Java"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> Seleccione Ventana->Abrir perspectiva->Java en la barra de menús de la parte superior del entorno de trabajo. Este paso cambia la perspectiva para configurar el entorno de trabajo Eclipse para el desarrollo Java. Puede pulsar el botón "Pulsar para realizar" para que la perspectiva "Java" se abra automáticamente. </description> </item> ...
La información de título e introducción se muestran en la parte superior de la hoja de apuntes. A continuación, se describen los elementos. El primer elemento de esta hoja de apuntes describe cómo abrir la perspectiva Java. Mejor aún, el atributo action especifica una clase que puede utilizarse para ejecutar la acción en nombre del usuario. La clase debe implementar IAction. Esto resulta más adecuado, ya que permite reutilizar las clases de acción escritas para contribuciones de menú o barra de herramientas.
La clase de la acción puede implementar opcionalmente ICheatSheetAction si la acción utiliza parámetros o necesita tener conocimiento de la hoja de apuntes y su estado. En este caso, se pasará a la acción una matriz de parámetros y una referencia a ICheatSheetManager para que pueda solicitar información adicional acerca de la hoja de apuntes. Pueden pasarse parámetros adicionales al método run de la acción mediante los atributos paramN.
Es muy aconsejable que las acciones invocadas desde hojas de apuntes notifiquen una salida satisfactoria/anómala si la ejecución de la acción puede fallar. (Por ejemplo, el usuario podría cancelar la acción desde su diálogo). Consulte la sección dedicada a IAction.notifyResult(boolean) para obtener más detalles.
Los elementos no tienen que definir acciones. Si el usuario debe debe realizar manualmente el elemento, no es necesario especificar una acción. A continuación figura el tercer paso de la hoja de apuntes Java, que simplemente indica al usuario cómo codificar la aplicación simple. Si no se especifica ninguna acción, la descripción del elemento debe indicar al usuario que pulse el botón adecuado una vez finalizada la tarea.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Añadir una línea System.out.println al método main"> <description> Ahora que tiene la clase HelloWorld, Añada la siguiente sentencia al método "public static void main": System.out.println("Hello world!"); y guarde los cambios. Pulse el botón "pulsar cuando haya terminado" que figura más abajo cuando haya terminado. </description> </item>Los atributos adicionales controlan si el elemento puede pasarse por alto completamente y qué documento debe lanzarse si el usuario solicita ayuda durante el paso. Consulte la documentación del punto de extensión org.eclipse.ui.cheatsheets.cheatSheetContent para obtener una descripción de todos los atributos que pueden definirse en una hoja de apuntes.
Pueden definirse subelementos para organizar con más detalle la presentación de un elemento. A diferencia de los elementos, los subelementos no tienen que visitarse en un orden determinado. Los subelementos también pueden definir acciones que realicen automáticamente la subtarea en nombre del usuario. Las acciones de subelemento se describe del mismo modo que las acciones de elemento.
Pueden utilizarse expresiones condicionales para definir elementos de hoja de apuntes cuyo contenido o comportamiento depende de que se cumpla una condición determinada. Las condiciones se describen en el elemento condition de un subelemento mediante valores serie arbitrarios que se comparan con el atributo when de para elección. Generalmente, las condiciones hacen referencia a variables de hoja de apuntes mediante el formato ${var}, donde var se refiere al nombre de una variable de hoja de apuntes. Algunos ejemplos sencillos ayudarán a ilustrar el funcionamiento de las expresiones condicionales.
Los subelementos condicionales pueden utilizarse para elegir un subelemento de una lista de subelementos posibles. Sólo el primer subelemento cuyo atributo when coincida con el atributo condition se incluirá en la hoja de apuntes. Por ejemplo:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Paso para A." /> <subitem when="b" label="Paso para B." /> </conditional-subitem> </item>Este elemento especifica dos posibles subelementos que dependen del valor de la variable v1. Si el valor de la variable es a, se incluirá el primer subelemento. Si el valor de la variable es b, se incluirá el segundo subelemento. Si la variable no tiene ningún valor, se considerará un error.
Las acciones condicionales son similares a los subelementos condicionales. El elemento perform-when especifica una condición para realizar una acción entre una lista de acciones posibles. La condición se describe de la misma forma, mediante una serie arbitraria que con frecuencia hace referencia a una variable. La acción cuyo atributo when coincida con la condición es la que se realizará. Por ejemplo:
<item ...> <perform-when condition="${v1}"> <action when="a" class="com.example.actionA" pluginId-"com.example" /> <action when="b" class="com.example.actionB" pluginId-"com.example" /> </perform-when> </item>La acción que debe realizarse se elige en función del valor de la variable v1. Si el valor de la variable no es a o b, se considerará un error.
Los subelementos repetidos describen un subelemento que puede expandirse en 0, 1 o subelementos más similares. Los subpasos se individualizan mediante la variable especial ${this}. Esta variable se sustituirá por los valores especificados en el atributo values. El atributo values es una serie de valores separados por comas. Una variable que se expanda en una lista de valores puede utilizarse en el atributo values. Por ejemplo:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Paso ${this}" /> </repeated-subitem> </item>Si el valor de la variable es 1,b,three, aparecerán tres subelementos en la hoja de apuntes, cada uno con una etiqueta exclusiva ("Paso 1," "Paso b," "Paso tres"). La variable puede utilizarse en la etiqueta o en el valor del parámetro de acción. También puede accederse a ella desde ICheatSheetManager durante la ejecución de la acción.
En algunos casos, puede que desee cambiar otras partes de la UI si hay una hoja de apuntes activa. Por ejemplo, puede que tenga un editor que muestra anotaciones especiales si una hoja de apuntes guía al usuario a través de una tarea de edición. En este caso, puede especificarse un escuchador como atributo de la hoja de apuntes. El atributo de escuchador (listener) debe ser el nombre totalmente calificado de una clase Java que cree una subclase de CheatSheetListener. Los escuchas recibirán notificaciones junto con un ICheatSheetEvent cuando se produzca un cambio en el ciclo de vida de la hoja de apuntes, como por ejemplo cuando se abre, se cierra o se completa.
Puede utilizarse el punto de extensión org.eclipse.ui.cheatsheets.cheatSheetItemExtension para añadir atributos arbitrarios a una hoja de apuntes preexistente. El propósito de este punto de extensión es permitir que los conectores añadan botones adicionales que ayuden al usuario en un paso determinado. Estos botones adicionales se visualizan junto el icono de ayuda.
Para utilizar este mecanismo, puede definir cualquier atributo arbitrario dentro de una definición de elemento en el archivo XML de la hoja de apuntes. El nombre del atributo se comparará con los atributos añadidos en extensiones a org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Consulte la documentación del punto de extensión para obtener más detalles.