Hojas de apuntes compuestas

Las hojas de apuntes compuestas proporcionan ayuda para problemas complejos dividiendo el problema en un conjunto de tareas más pequeñas. Las hojas de apuntes compuestas se registran utilizando el punto de extensión org.eclipse.ui.cheatsheets.cheatSheetContent.

Formato de archivo de contenido

El contenido de la hoja de apuntes compuesta se define en un archivo aparte conforme a la especificación del archivo de contenido de hoja de apuntes compuesta. El archivo de contenido es un archivo XML y consta de un conjunto de tareas organizado en grupos en una estructura de árbol.

<compositeCheatsheet> es el elemento raíz de una hoja de apuntes compuesta. Tendrá una sola tarea raíz que puede ser <task> o <taskGroup>. Los elementos <taskGroup> pueden tener uno o varios hijos, cada uno de los cuales puede ser <task> o <taskGroup>. Un elemento <task> no tiene tareas hijo.

Las tareas y los grupos de tareas pueden contener elementos <intro> que contendrán el texto a visualizar antes de que se haya iniciado la tarea y los elementos <onCompletion> contendrán el texto a visualizar una vez realizada la tarea. Tanto los elementos <intro> como <onCompletion>, pueden contener código de texto de formulario, en el ejemplo siguiente, los códigos <b> y </b> se utilizan para poner el texto en negrita.

Las tareas también contienen elementos <param>. Una tarea de hoja de apuntes puede tener cualquiera de los parámetros siguientes: "id" es el ID de una hoja de apuntes registrada, "path" es la vía de acceso relativo o el URL del archivo de contenido de la hoja de apuntes e "skipIntro" es un parámetro booleano que si es true hace que la hoja de apuntes empiece en el primer paso en lugar de en la introducción. Es necesario especificar "id" o "path", pero no ambos.

Un nodo <dependency> de la tarea "B" a la tarea "A" representa el requisito de que la tarea A debe finalizar para que pueda empezar la tarea B.

Parámetros de tarea de hoja de apuntes

Si una tarea tiene kind = "cheatsheet" se abrirá una hoja de apuntes al iniciar la tarea. Hay tres parámetros posibles para una tarea de hoja de apuntes.

Nombre de parámetro  Descripción
id El id de una hoja de apuntes que se ha registrado utilizando el punto de extensión org.eclipse.ui.cheatsheets.cheatSheetContent. Esto identifica la hoja de apuntes a la que se asociará esta tarea. Debe especificarse el id o el parámetro de vía de acceso (pero no ambos).
path El URL de un archivo de contenido de hoja de apuntes. Puede tratarse de un URL absoluto o relativo al archivo de contenido de la hoja de apuntes compuesta. Si se especifican id y path, se utilizará path para ubicar el archivo de contenido y no se tendrá en cuenta el parámetro id.
showIntro Un parámetro booleano con el valor predeterminado true. Si el valor es "false", la hoja de apuntes mostrará inicialmente el primer paso en lugar de la introducción.

Ejemplo de una hoja de apuntes compuesta

El archivo siguiente es un ejemplo de cómo crear una hoja de apuntes compuesta a partir de hojas de apuntes existentes. Muestra cómo crear grupos de tareas y hacer que las tareas puedan saltarse.

<?xml version="1.0" encoding="UTF-8" ?>
<compositeCheatsheet name="Ejemplo de hoja de apuntes compuesta">
    <taskGroup name= "Ejemplo de hoja de apuntes compuesta">
         <intro> Este es un ejemplo de <b>hoja de apuntes compuesta</b> creada a partir de hojas de apuntes existentes.
                 <br/><br/>Puede seleccionar una tarea con la que trabajar siguiendo los hiperenlaces o
                 seleccionando una tarea en el árbol.
         </intro>  
         <onCompletion>Enhorabuena, ha finalizado todas las tareas.</onCompletion>
         <task kind="cheatsheet" name= "Ramificación y fusión mediante CVS" skip="true">
              <param name = "id" value = "org.eclipse.platform.cvs_1" />
              <intro>Esta hoja de apuntes está destinada a los usuarios de CVS. Si no utiliza CVS o
              no tiene previsto ramificar y fusionar, puede saltarse esta tarea.
              </intro>
               <onCompletion>Enhorabuena, ahora ya sabe cómo ramificar y fusionar.</onCompletion>
         </task>
         <taskGroup name= "Crear proyectos Java" kind = "sequence">
             <intro> Primero aprenderá a crear un proyecto Java simple, luego creará
             un proyecto Java que utiliza SWT.
             <br/><br/>Este grupo de tareas es una secuencia que significa que,
             si pulsa la subtarea "Aplicación SWT autónoma",  no permitirá iniciar esa tarea
             hasta que "Crear un proyecto Java" haya finalizado.
             </intro>
              <onCompletion>Enhorabuena, ha construido ambas aplicaciones Java.</onCompletion>
             <task kind="cheatsheet" name= "Crear un proyecto Java" id = "createJavaProject">
                 <param name="id" value = "org.eclipse.jdt.helloworld"/>
                 <param name="showIntro" value = "false"/>
                 <intro>Esta hoja de apuntes le guía en el proceso de creación de una aplicación sencilla llamada hello world.
                        La hoja de apuntes puede lanzar asistentes para crear un proyecto nuevo y una clase nueva.
                 </intro>
                 <onCompletion>Enhorabuena, ha creado satisfactoriamente una aplicación hello world</onCompletion>
             </task>
             <task kind="cheatsheet" name= "Aplicación SWT autónoma">
                 <intro>Los plug-ins de Eclipse que contribuyen a la interfaz de usuario utilizan SWT (Standard Widget Toolkit.) 
                    Esta guía de tareas puede utilizarse para aprender más acerca de SWT. 
                 </intro>
                 <param name = "id" value = "org.eclipse.jdt.helloworld.swt" />
                  <onCompletion>Enhorabuena, ha creado satisfactoriamente una aplicación SWT.</onCompletion>
             </task>      
         </taskGroup>
    </taskGroup>
</compositeCheatsheet>

Ampliabilidad de hojas de apuntes compuestas: provisional en Eclipse 3.2

Las hojas de apuntes compuestas son ampliables, sin embargo, en Eclipse 3.2 esta ampliabiliad es provisional y las clases pueden cambiar antes de convertirse en API. El soporte de las hojas de apuntes compuestas puede ampliarse utilizando el punto de extensión org.eclipse.ui.cheatsheets.cheatSheetContent que tiene dos elementos taskEditor y taskExplorer que permiten la contribución de editores y exploradores de tareas.

La contribución de un editor de tareas define una especie de tarea nueva que se visualiza en la sección de detalles de tarea. Para contribuir con un editor de tareas, implemente una subclase de  TaskEditor y añada el elemento taskEditor a plugin.xml.

La representación del explorador de tareas también puede configurarse con un punto de extensión, en la plataforma Eclipse se incluye un explorador de árbol. La primera vez que se abre una hoja de apuntes compuesta, el explorador predeterminado es un árbol, un atributo en el elemento <compositeCheatSheet> permitirá alterar temporalmente el valor predeterminado. Si se registra más de un explorador, el menú de la vista contendrá un elemento de menú para pasar de uno a otro explorador. Para contribuir con un explorador de tareas, primero implemente una subclase concreta de  TaskExplorer, después añada un elemento taskExplorer al plugin.xml.

Enlaces relacionados

Trabajar con hojas de apuntes
Trabajar con hojas de apuntes compuestas
Crear hojas de apuntes
Directrices de autoría
Especificación de archivo de contenido de hojas de apuntes compuestas
Punto de extensión org.eclipse.ui.cheatsheets.cheatSheetContent