O suporte de introdução é um conjunto de pontos de extensão e de peças do workbench que permitem que os plug-ins definam páginas especializadas que apresentam um produto de plataforma aos novos usuários. As informações de introdução são normalmente mostradas na primeira vez em que o produto é iniciado. O suporte de introdução é normalmente configurado no nível do produto, embora os plug-ins individuais possam contribuir com informações de introdução para as configurações de introdução dos produtos conhecidos.
Do ponto de vista do workbench, a raiz do suporte de introdução está na parte de introdução. Essa parte é especificada em uma definição de extensão. Quando o workbench é inicializado, ele cria um site de introdução que reserva espaço para a página de introdução. A implementação da parte de introdução para o site é determinada utilizando as informações de configuração do produto. Assim que uma parte da introdução é mostrada, é possível mover-se entre dois modos:
Assim que uma parte da introdução é estabelecida, ela deve ser configurada com informações de introdução. Isso é feito utilizando uma config da intro que também é contribuída utilizando uma extensão. Os plug-ins individuais podem ser incluídos na configuração da introdução do produto básico, utilizando suas próprias extensões.
Observaremos a página de introdução SDK da plataforma como um exemplo para entender melhor esses conceitos.
A interface da IIntroPart e o ponto de extensão de org.eclipse.ui.intro formam o mecanismo genérico que pode ser utilizado para criar seu próprio suporte de introdução para um determinado produto. A finalidade principal dessa extensão é definir a classe que implementa IIntroPart e especificar a ligação entre um id de produto e uma parte da introdução. Por exemplo, a seguinte contribuição define uma parte hipotética da introdução a ser mostrada pelo workbench na inicialização:
<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>Primeiramente, essa contribuição define a parte da introdução e designa o id "someId" para ela. Em seguida, liga essa parte da introdução a um produto cujo id é "com.example.someProductId". Na inicialização da plataforma, a classe especificada no atributo class será instanciada pelo workbench e apresentada ao usuário como a introdução ao produto. Esse é o nível mais baixo da integração na interface de IIntroPart.
A plataforma fornece sua própria implementação de IIntroPart chamada CustomizableIntroPart que permite que o conteúdo e a apresentação da introdução sejam personalizados. A seguir está o snippet que define a parte da introdução para o workbench. Não verificaremos os mecanismos da implementação de uma parte da introdução já que desejamos enfatizar a definição do conteúdo da introdução. (Consulte a documentação do ponto de extensão e o javadoc utilizado como referência anteriormente para obter detalhes adicionais se necessário.)
<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>A contribuição acima define CustomizableIntroPart como a parte da introdução a ser utilizada para a plataforma SDK do Eclipse. O restante dessa discussão mostra como utilizar e estender essa parte.
A CustomizableIntroPart da plataforma permite que o conteúdo e a apresentação da introdução sejam personalizados utilizando o ponto de extensão org.eclipse.ui.intro.config. (Essa configuração da introdução pode ser estendida utilizando o ponto de extensão de org.eclipse.ui.intro.configExtension.) Essa estrutura permite que os desenvolvedores de plug-in do produto enfatizem o desenvolvimento do conteúdo da introdução em vez de implementar um esquema da parte de introdução a partir do ponto de partida. Se uma classe de introdução diferente for especificada, esses dois pontos de extensão não serão utilizados e a classe especificada deve implementar seu próprio esquema para o formato e configuração do conteúdo da introdução.
A org.eclipse.ui.intro.config descreve o id da configuração da introdução que deve mostrar o conteúdo e o nome do arquivo XML que contém a definição específica para o conteúdo da introdução. Espera-se que somente uma configuração de introdução seja definida para uma CustomizableIntroPart determinada. (Somente a primeira configuração da introdução pode se mostrada em uma 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>O caminho para o arquivo é relativo para o diretório do plug-in. (Observe a utilização da variável $nl$ no nome do diretório, que significa que o arquivo estará localizado em um diretório específico do idioma nacional do ambiente de destino.)
A extensão de configuração permite que você especifique o conteúdo e a apresentação do conteúdo. Enquanto o elemento do conteúdo enfatiza a definição das páginas, o elemento da apresentação descreve os atributos relacionados à apresentação que descrevem como as páginas serão mostradas. O id de página para a home page de introdução (no modo completo) deve ser especificado e o id de página de espera (no modo de espera) é opcional. A home page é a página que é mostrada quando o produto é iniciado pela primeira vez. Uma apresentação pode especificar uma ou mais implementações para mostrar as páginas. As implementações são especificadas por plataformas e sistema de janelas, permitindo que você aproveite os recursos específicos da plataforma para mostrar o conteúdo da página. Por exemplo, a plataforma do windows tem um widget do navegador HTML robusto, então uma implementação com base em HTML é utilizada para o conteúdo da introdução. Outras plataformas sem esse recurso utilizam uma implementação com base em SWT que mapeia as descrições de página para uma formulário com base em SWT. Uma implementação que não especifica um sistema de janelas ou um sistema operacional será considerada a implementação genérica; para assegurar que uma introdução é mostrada em todas as plataformas, é importante definir essa implementação. O workbench irá procurar uma implementação que corresponda ao sistema operacional atual e ao sistema de janelas. Se não for possível localizá-la, a implementação genérica será escolhida. A maioria desses detalhes é manipulada no nível de configuração do produto, então não discutiremos mais isso aqui.
Agora, observaremos o conteúdo em si. O conteúdo é descrito em termos de páginas. Todas as páginas têm um atributo deid. Esse é o id que é utilizado ao definir as páginas home e de espera e outros locais em que há referência a uma página. Caso contrário, os atributos relevantes dependem do tipo de página que está definido. Há dois tipos básicos de páginas:
A melhor maneira de obter uma amostra do formato da definição do conteúdo é procurar as implementações no SDK. O seguinte snippet mostra apenas a primeira parte do conteúdo para a página raiz do SDK, que é a primeira página de introdução mostrada.
<introContent> <page alt-style="css/root_swt.properties" style="css/root.css" id="root" style-id="page"> <title style-id="intro-header">Welcome to Eclipse Platform 3.0</title> <group id="links-background"> <group id="page-links"> <link label="Overview" url="http://org.eclipse.ui.intro/showPage?id=overview" id="overview" style-id="left"> <text>Find out what Eclipse is all about</text> </link> <link label="Tutorials" url="http://org.eclipse.ui.intro/showPage?id=tutorials" id="tutorials" style-id="left"> <text>Let us guide you through Eclipse end-to-end tutorials</text> </link> <link label="Samples" url="http://org.eclipse.ui.intro/showPage?id=samples" id="samples" style-id="right"> <text>Explore Eclipse development through code samples</text> </link> <link label="Whats New" url="http://org.eclipse.ui.intro/showPage?id=news" id="news" style-id="right"> <text>Find out what is new in this release</text> </link> </group> </group>
Os elementos em uma página também podem ser filteredFrom de uma implementação específica. Isso permite que os designers de página projetem com plataformas específicas em mente. Há muitos outros atributos poderosos que podem ser utilizados ao descrever uma página e seu conteúdo. Consulte a documentação do ponto de extensão para org.eclipse.ui.intro.config e sua especificação do formato do arquivo de conteúdo da introdução associada para uma referência completa dos elementos válidos, subelementos e seus atributos.
Uma configuração da introdução pode ser estendida de três maneiras:
Os plug-ins podem contribuir com o conteúdo da introdução para uma página definida em algum outro lugar. No entanto, a página de definição deve definir um atributo de âncora que age como um marcador de local para o novo conteúdo. A página da visão geral de SDK define duas âncoras para incluir os elementos relacionados ao JDT e ao PDE na página da visão geral.
<group id="page-content"> <text style-id="page-title" id="page-title">OVERVIEW</text> <text style-id="page-description" id="page-description">O Eclipse é um tipo de plataforma de ferramentas universal - um IDE extensível aberto para qualquer coisa e para nada em específico. Fornece um ambiente de desenvolvimento rico em recursos que permite que o desenvolvedor crie, de modo eficiente, as ferramentas que se integram facilmente à Plataforma Eclipse.</text> <group id="overview-links"> <link label="Workbench basics" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-2.htm" id="basics"> <text>Aprenda sobre os conceitos básicos do workbench do Eclipse</text> </link> <link label="Team support" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-26.htm" id="team"> <text>Descubra como colaborar com outros desenvolvedores</text> </link> <anchor id="jdtAnchor"/> <anchor id="pdeAnchor"/> </group> </group>Essas âncoras podem ser utilizadas como referência pelos plug-ins que incluem conteúdo na página. O conteúdo é incluído utilizando a extensão de org.eclipse.ui.intro.configExtension. Além de estender o conteúdo da página, esse ponto de extensão também permite a contribuição das partes de conteúdo em espera e ações personalizadas.
Para estender uma configuração de introdução existente, é possível utilizar o elemento configExtension. Neste elemento, você especifica o configId da configuração de introdução sendo estendida e o arquivo de conteúdo que descreve o novo conteúdo.
<extension point="org.eclipse.ui.intro.configExtension"> <configExtension configId="org.eclipse.platform.introConfig" content="$nl$/overviewExtensionContent.xml"/> ... </extension>O formato do arquivo de conteúdo é semelhante ao do conteúdo da configuração de introdução, exceto de que deve conter um elemento extensionContent, que define o caminho para a âncora em que o conteúdo da extensão deve ser inserido.
<introContent> <extensionContent alt-style="css/swt.properties" style="css/overview.css" path="overview/page-content/overview-links/jdtAnchor"> <link label="Java development" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.jdt.doc.user/gettingStarted/qs-BasicTutorial.htm" id="java"> <text>Familiarize-se com os programas de desenvolvimento Java utilizando o Eclipse</text> </link> </extensionContent> </introContent>Depois de contribuir com o conteúdo personalizado para os pontos de âncora predefinidos, um determinado produto pode ligar-se a essa introdução, utilizando o org.eclipse.ui.intro discutido anteriormente. Quando o produto é executado, a introdução que foi estendida será mostrada com o conteúdo adicional. Isso permite que o produto tenha sua própria marca e outras informações específicas do produto, enquanto reutiliza uma introdução do produto relacionado com atenção junto com o próprio conteúdo principal.
Uma determinada introdução também poderia seletivamente incluir trechos de uma introdução do produto relacionado. Neste caso, o produto poderia definir sua própria introdução e configuração de introdução e, em seguida, fazer referência aos elementos importantes definidos em outra configuração de introdução, utilizando um include no arquivo de conteúdo. Esse mecanismo é valioso em situações em que os produtos relacionados são construídos na parte superior de outro e é necessário apresentar usuários aos conceitos principais nos produtos de nível mais alto.
Os plug-ins também podem implementar uma parte para exibir conteúdo alternativo quando a página de introdução está no modo de espera. Por exemplo, a plataforma define uma parte de espera que mostrará uma folha de dicas para o conteúdo da introdução relacionada. A parte é ativada utilizando um link de página com uma URL especializada. As partes em espera são ativadas utilizando uma URL contendo um comando especial para mostrar uma parte em espera, como http://org.eclipse.ui.intro/showStandby?partId=somePartId. A parte é definida no subelemento standbyContentPart na extensão de org.eclipse.ui.intro.configExtension. Umid, Iddeplugin e classe devem ser especificados para a parte. A classe deve implementar IStandbyContentPart. O seguinte snippet mostra como a plataforma define uma parte em espera para mostrar as folhas de dicas.
<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 folha de dicas pode ser ativada a partir de uma página de introdução utilizando um subelemento de link cuja URL é http://org.eclipse.ui.intro/showStandby?partId=org.eclipse.platform.cheatsheet&input=org.eclipse.pde.helloworld. Esta IntroURL ativaria a parte de conteúdo em espera de org.eclipse.platform.cheatsheet e configuraria sua entrada para "org.eclipse.pde.helloworld". Os mecanismos detalhados para implementar uma parte em espera estão além do escopo desta discussão. ConsulteIStandbyContentPart e suas classes relacionadas para obter informações adicionais.
Utilizando o ponto de extensão de org.eclipse.ui.intro.configExtension, os plug-ins podem contribuir com suas próprias ações personalizadas que podem ser utilizadas como um valor de url para um elemento de link em uma página. Por exemplo, considere o seguinte link:
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
Esta IntroURL executará uma classe de ação chamada ShowSampleAction, que está em um pacote "org.eclipse.pde.ui.internal.samples" no "org.eclipse.pde.ui" do plug-in. O id da amostra a ser executada é"org.eclipse.sdk.samples.swt.examples".
Para definir uma versão personalizada desta URL de introdução, você pode utilizar a seguinte marcação:
<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>Com a extensão acima, você pode utilizar a seguinte URL para executar a mesma ação:
http://org.eclipse.ui.intro/myCommand?id=org.eclipse.sdk.samples.swt.examples
A ação "myCommand" será substituída pelo valor do atributo replaces e quaisquer parâmetros de URL remanescentes serão anexados à extremidade. Assim que a substituição for feita, a URL resultante será expandida de volta para:
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