Soporte de introducción

El soporte introductorio es un conjunto de puntos de extensión y componentes del entorno de trabajo que permiten a los conectores definir páginas especializadas que presentan un producto de plataforma a los usuarios nuevos. La información introductoria se muestra generalmente la primera vez que se inicia un producto. El soporte de introducción se configura generalmente a nivel de producto, aunque conectores individuales pueden añadir información introductoria a configuraciones de introducción de producto conocidas.

Desde el punto de vista del entorno de trabajo, la raíz del soporte de introducción se encuentra en el componente intro. Este componente se especifica en una definición de extensión. Cuando se inicializa el entorno de trabajo, crea un sitio de introducción que reserva espacio para la página introductoria. La implementación del componente intro para el sitio se determina mediante información de configuración del producto. Una vez que se muestra un componente intro, puede moverse entre dos modalidades:

Una vez establecido un componente intro, debe configurarse con información introductoria. Esta operación se realiza mediante un elemento de configuración introductoria (intro config) que también se añade mediante una extensión. Los conectores individuales pueden efectuar adiciones a la configuración introductoria del producto básico mediante sus propias extensiones.

Examinaremos la página introductoria del SDK de la plataforma como ejemplo para comprender mejor estos conceptos.

Definir un componente intro

La interfaz IIntroPart y el punto de extensión org.eclipse.ui.intro forman el mecanismo genérico que puede utilizarse para crear soporte de introducción propio para un producto determinado. La finalidad principal de esta extensión consiste en definir la clase que implementa IIntroPart y especificar el enlace entre un ID de producto y un componente intro. Por ejemplo, la siguiente contribución define un componente intro hipotético que el entorno de trabajo debe mostrar el iniciarse:


<extension  
	point="org.eclipse.ui.intro">
	<intro
		class="com.example.SampleIntroPart"
		id="someId">
		icon="someIcon.gif"
	</intro>
	<introProductBinding
		introId="someId"
		productId="com.example.someProductId">
	</introProductBinding>
</extension>
Esta contribución define en primer lugar el componente intro y le asigna el ID "someId". A continuación, enlaza este componente intro con el producto cuyo ID es "com.example.someProductId". Al iniciarse la plataforma, el entorno de trabajo creará una instancia de la clase especificada en el atributo class que se presentará al usuario como introducción al producto. Este es el nivel de integración más bajo en la interfaz IIntroPart.

La plataforma suministra su propia implementación de IIntroPart denominada CustomizableIntroPart, que permite personalizar el contenido y la presentación de la introducción. A continuación figura el fragmento de código que define el componente intro del entorno de trabajo. No examinaremos los mecanismos encargados de implementar un componente intro, ya que debemos centrarnos en la definición del contenido de la introducción. Consulte la documentación del punto de extensión y el javadoc citados anteriormente para obtener más detalles).


<extension  
	point="org.eclipse.ui.intro">
	<intro
		class="org.eclipse.ui.intro.config.CustomizableIntroPart"
		id="org.eclipse.platform.intro">
	</intro>
	<introProductBinding
		introId="org.eclipse.platform.intro"
		productId="org.eclipse.platform">
	</introProductBinding>
</extension>
La contribución anterior define CustomizableIntroPart como componente intro que debe utilizarse en la plataforma SDK de Eclipse. En el resto de esta descripción se muestra cómo utilizar y ampliar este componente.

Utilizar el componente CustomizableIntroPart

El CustomizableIntroPart de la plataforma permite personalizar el contenido y la presentación de la introducción mediante el punto de extensión org.eclipse.ui.intro.config. (Esta configuración de introducción puede ampliarse mediante el punto de extensión org.eclipse.ui.intro.configExtension). Esta estructura permite a los desarrolladores de conectores del producto centrarse en el desarrollo del contenido de la introducción en lugar de implementar un esquema de componente intro desde cero. Si se especifica una clase intro diferente, no se utilizan estos dos puntos de extensión y la clase especificada debe implementar su propio esquema para el formato y la configuración del contenido de la introducción.

Definir una configuración de introducción

org.eclipse.ui.intro.config describe el ID de la configuración de introducción que debe mostrar el contenido y el nombre del archivo XML que contiene la definición específica del contenido de la introducción. Sólo debe definirse una configuración de introducción para un CustomizableIntroPart determinado. (Sólo la primera configuración de introducción encontrada puede mostrarse en un CustomizableIntroPart.)


<extension   
	id="intro"
	point="org.eclipse.ui.intro.config">
	<config
		introId="org.eclipse.platform.intro"
		id="org.eclipse.platform.introConfig"
		content="$nl$/introContent.xml">
	<presentation
		home-page-id="root" standby-page-id="standby">
			<implementation
 				ws="win32"
				style="css/shared.css"
				kind="html"
				os="win32">
			</implementation>
			<implementation
				kind="swt">
			</implementation>
	</presentation>
	</config>
</extension>  
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).

La extensión config permite especificar tanto el contenido como la presentación del mismo. Mientras que el elemento content se centra en la definición de las páginas, el elemento presentation describe los atributos relacionados con la presentación que describe cómo se mostrarán las páginas. Debe especificarse el ID de página de la página de presentación introductoria (en modalidad completa), y el ID de página en espera (en modalidad de espera) es opcional. La página de presentación es la página que se muestra cuando se inicia el producto por primera vez. Una presentación puede especificar una o varias implementaciones para mostrar las páginas. Las implementaciones se especifican por plataforma y por sistema de ventanas, permitiendo al usuario aprovechar las características específicas de la plataforma para mostrar el contenido de la página. Por ejemplo, la plataforma Windows tiene un widget de navegador HTML robusto que permite utilizar una implementación basada en HTML para el contenido de la introducción. Otras plataformas sin esta posibilidad utilizan una implementación basada en SWT que correlaciona descripciones de página con un formulario basado en SWT. Una implementación que no especifique un sistema de ventanas ni un sistema operativo se considerará una implementación genérica; para garantizar que se muestre una introducción en todas las plataformas, es importante definir una implementación de este tipo. El entorno de trabajo buscará primero una implementación que coincida con el sistema operativo y el sistema de ventanas actual. Si no encuentra ninguno, elegirá la implementación genérica. La mayoría de estos detalles se manejan a nivel de configuración del producto, y por tanto no los trataremos aquí con mayor profundidad.

Definir el contenido de la introducción

Ahora podemos preocuparnos del contenido propiamente dicho. El contenido se describe en términos de páginas. Todas las páginas tienen un atributo id. Se trata del ID utilizado al definir las páginas de presentación y espera y en otras ubicaciones en las que exista una referencia a una página. De lo contrario, los atributos relevantes dependerán del tipo de página que se defina. Existen dos tipos básicos de páginas:

La mejor manera de hacerse una idea del formato de la definición de contenido es examinar las implementaciones del SDK. El siguiente fragmento de código muestra sólo la primera parte del contenido de la página raíz del SDK, que es la primera página de introducción que se muestra.


<introContent>
  <page alt-style="css/root_swt.properties" style="css/root.css" id="root" style-id="page">
    <title style-id="intro-header">Bienvenido a Eclipse Platform 3.0</title>
    <group id="links-background">
      <group id="page-links">
        <link label="Visión general" url="http://org.eclipse.ui.intro/showPage?id=overview" id="overview" style-id="left">
          <text>Información introductoria acerca de Eclipse</text>
        </link>
        <link label="Guías de aprendizaje" url="http://org.eclipse.ui.intro/showPage?id=tutorials" id="tutorials" style-id="left">
          <text>Permítanos guiarle por medio de guías de aprendizaje completas de Eclipse</text>
        </link>
        <link label="Ejemplos" url="http://org.eclipse.ui.intro/showPage?id=samples" id="samples" style-id="right">
          <text>Explore el desarrollo de Eclipse por medio de ejemplos de código</text>
        </link>
        <link label="Novedades" url="http://org.eclipse.ui.intro/showPage?id=news" id="news" style-id="right">
          <text>Conozca las novedades de este release</text>
        </link>
      </group>
    </group>

Los elementos de una página también pueden filtrarse (filteredFrom) de una implementación determinada. Esto permite a los diseñadores de páginas realizar el diseño pensando en plataformas determinadas. Al describir una página y su contenido pueden utilizarse muchos otros potentes atributos. Consulte la documentación del punto de extensión org.eclipse.ui.intro.config y su especificación de formato de archivo de contenido de introducción asociada para obtener la lista completa de elementos válidos, subelementos y sus atributos.

Ampliar una configuración de introducción

Una configuración de introducción puede ampliarse de tres maneras:

Ampliar el contenido de una configuración de introducción

Los conectores pueden añadir contenido de introducción a una página definida en otra ubicación. Sin embargo, la página definidora debe definir un atributo anchor que actúe como espacio reservado de ubicación para el contenido nuevo. La página de visión general del SDK define dos anclas para añadir elementos relacionados con JDT y PDE a la página de visión general.

    
<group id="page-content">
	<text style-id="page-title" id="page-title">VISIÓN GENERAL</text>
	<text style-id="page-description" id="page-description">Eclipse es un tipo de plataforma de herramientas universal, un IDE abierto y ampliable para todo y nada en particular. Proporciona un entorno de desarrollo de variadas características que permite al desarrollador crear eficazmente herramientas que se integran fluidamente en la Plataforma Eclipse.</text>
	<group id="overview-links">
		<link label="Conceptos básicos del entorno de trabajo" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-2.htm" id="basics">
			<text>Información relativa a los conceptos básicos del entorno de trabajo de Eclipse</text>
        </link>
        <link label="Soporte de equipo" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-26.htm" id="team">
			<text>Información acerca de cómo colaborar con otros desarrolladores</text>
        </link>
		<anchor id="jdtAnchor"/>
		<anchor id="pdeAnchor"/>
	</group>
</group>
Los conectores que añaden contenido a la página pueden hacer referencia a estas anclas. El contenido se añade mediante la extensión org.eclipse.ui.intro.configExtension. Además de ampliar el contenido de la página, este punto de extensión también permite añadir componentes de contenido en espera y acciones personalizadas.

Para ampliar una configuración de introducción existente, puede utilizar el elemento configExtension. En este elemento, especifique el configId de la configuración de introducción que se amplía y el archivo de contenido que describe el contenido nuevo.

 
<extension
	point="org.eclipse.ui.intro.configExtension">
	<configExtension
		configId="org.eclipse.platform.introConfig"
		content="$nl$/overviewExtensionContent.xml"/>  
    ...
</extension>
El formato del archivo de contenido es similar al del contenido de la configuración de introducción, excepto que debe contener un elemento extensionContent que defina la vía de acceso al ancha en la que debe insertarse el contenido de extensión.
 
<introContent>
	<extensionContent alt-style="css/swt.properties" style="css/overview.css" path="overview/page-content/overview-links/jdtAnchor">
		<link label="Desarrollo Java" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.jdt.doc.user/gettingStarted/qs-BasicTutorial.htm" id="java">
			<text>Familiarícese con el desarrollo de programas Java mediante Eclipse</text>
		</link>
	</extensionContent>
</introContent>
Después de añadir contenido personalizado a puntos de ancla predefinidos de una introducción, un producto determinado puede enlazarse a sí mismo con dicha introducción mediante la org.eclipse.ui.intro descrita anteriormente. Cuando se ejecute el producto, la introducción ampliada se mostrará con el contenido adicional. Esto permite al producto tener su propio sello personal y otra información específica del producto, al tiempo que reutiliza una introducción del producto estrechamente relacionada junto con contenido propio clave.

Una introducción dada también puede incluir selectivamente partes de la introducción de un producto relacionado. En este caso, el producto puede definir su propia introducción y configuración de introducción y, a continuación, hacer referencia a elementos importantes definidos en la configuración de otra introducción mediante un elemento include en el archivo de contenido. Este mecanismo resulta de utilidad en situaciones en las que productos relacionados se construyen uno encima de otro y es necesario presentar a los usuarios los conceptos clave de los productos de mayor nivel.

Añadir un componente de contenido de espera

Los conectores también puede añadir un componente destinado a visualizar contenido alternativo cuando la página introductoria está en modalidad de espera. Por ejemplo, la plataforma define un componente standby que mostrará una hoja de apuntes para el contenido de introducción relacionado. El componente se lanza mediante un enlace de página con un URL especializado. Los componentes standby se lanzan mediante un URL que contiene un mandato especial para mostrar un componente standby, como por ejemplo http://org.eclipse.ui.intro/showStandby?partId=somePartId. El componente se define en el subelemento standbyContentPart de la extensión org.eclipse.ui.intro.configExtension. Deben especificarse atributos id, pluginId y class para el componente. La clase debe implementar IStandbyContentPart. El fragmento de código que figura a continuación muestra cómo define la plataforma un componente standby para mostrar hojas de apuntes.

 
<extension point="org.eclipse.ui.intro.configExtension">
	<standbyContentPart
		id="org.eclipse.platform.cheatsheet"
		class="org.eclipse.platform.internal.CheatSheetStandbyContent"
		pluginId="org.eclipse.platform"/>
</extension>
Esta hoja de apuntes puede lanzarse desde una página de introducción mediante un subelemento link cuyo URL es http://org.eclipse.ui.intro/showStandby?partId=org.eclipse.platform.cheatsheet&input=org.eclipse.pde.helloworld. Este IntroURL lanzará el componente de contenido standby org.eclipse.platform.cheatsheet y establecerá su entrada en "org.eclipse.pde.helloworld". La mecánica detallada de la implementación de un componente standby escapa al ámbito de esta descripción. Consulte IStandbyContentPart y sus clases relacionadas para obtener más información.

Definir una acción IntroURL personalizada

Mediante el punto de extensión org.eclipse.ui.intro.configExtension, los conectores pueden añadir sus propias acciones personalizadas que pueden utilizarse como valor de url para un elemento link de una página. Por ejemplo, considere el siguiente enlace:

http://org.eclipse.ui.intro/runAction?pluginId=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction&id=org.eclipse.sdk.samples.swt.examples

Este IntroURL ejecutará una clase de acción denominada ShowSampleAction, que se encuentra en el paquete "org.eclipse.pde.ui.internal.samples" del conector "org.eclipse.pde.ui". El ID del ejemplo que debe ejecutarse es "org.eclipse.sdk.samples.swt.examples".

Para definir una versión personalizada de este URL de introducción, puede utilizar el siguiente código:

 
<extension point="org.eclipse.ui.intro.configExtension">
	<action
		name="myCommand"
		replaces="runAction?pluginID=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction">
	   </action>
</extension>
Con la extensión anterior, ahora puede utilizar el siguiente URL para ejecutar la misma acción:

http://org.eclipse.ui.intro/myCommand?id=org.eclipse.sdk.samples.swt.examples

La acción "myCommand" se sustituirá por el valor del atributo replaces y el resto de parámetros de URL se añadirán al final. Una vez efectuada la sustitución, el URL resultante se ampliará de nuevo en:

http://org.eclipse.ui.intro/runAction?pluginId=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction&id=org.eclipse.sdk.samples.swt.examples

Avisos legales.