Formato XML do Ficheiro de Conteúdo de Introdução

Versão 3.1.0

Este documento descreve a estrutura do ficheiro de conteúdo de introdução como uma série de fragmentos DTD.

introContent


<!ELEMENT introContent (page+ , group* , extensionContent*)>

O elemento introContent define o corpo do ficheiro de conteúdo da introdução. O ficheiro de conteúdo é composto por páginas, grupos partilhados que podem ser incluídos em várias páginas e extensões para pontos de ancoragem definidos noutras configurações.



page


<!ELEMENT page (group* | link* | text* | head* | img* | include* | html* | hr* | title? | anchor* | contentProvider*)>

<!ATTLIST page

url          CDATA #IMPLIED

id           CDATA #REQUIRED

style        CDATA #IMPLIED

alt-style    CDATA #IMPLIED

filteredFrom (swt|html)
bgImage      CDATA #IMPLIED

content      CDATA #IMPLIED

style-id     CDATA #IMPLIED>

Este elemento é utilizado para descrever uma página a visualizar. A introdução pode apresentar páginas dinâmicas e estáticas.

O conteúdo das páginas dinâmicas é gerado a partir dos subelementos da página, descritas de seguida. O estilo ou estilo alternativo será aplicado dependendo da apresentação. Os estilos podem ser mais aperfeiçoados através da referência do ID ou ID de classe.

As páginas estáticas permitem a reutilização dos documentos HTML existentes dentro de uma determinada introdução e podem ser ligadas a partir de qualquer página estática ou dinâmica. As páginas estáticas não estão definidas num elemento page, são simplesmente ficheiros html aos quais outras páginas podem ligar-se.

A página inicial, cujo ID se encontra especificado no elemento presentation do ponto de extensão da configuração da introdução, pode ter um url que indica que é uma página estática. Se não for especificado nenhum URL, então parte-se do princípio que a página inicial é dinâmica. As restantes páginas descritas que utilizem o elemento page são dinâmicas.
Tenha também em consideração que quando se utiliza a apresentação SWT e deve ser apresentada uma página estática, é iniciado um browser externo e a página actual mantém-se visível.

Os subelementos utilizados numa página dinâmica são os seguintes: um subelemento group é utilizado para agrupar conteúdos relacionados e para aplicar o estilo através do conteúdo agrupado. Um subelemento link define uma ligação que pode ser utilizada para ligar a uma página estática ou dinâmica e para executar uma acção ou comando de introdução. Uma ligação normalmente é definida ao nível da página para navegar entre páginas principais verso ligações dentro de uma página. Um subelemento text define o conteúdo textual ao nível da página. Um subelemento head só é aplicável à apresentação baseada na Web e permite que se adicione html extra à secção HTML head. Isto é útil para adicionar scripts java ou folhas de estilo adicionais. Um subelemento img define conteúdo de imagem ao nível da página. Um subelemento include permite que qualquer elemento, exceptuando uma página, seja novamente utilizado. Um subelemento html só é aplicável à apresentação baseada na Web e permite incorporar ou incluir html no conteúdo da página. A incorporação permite que um ficheiro html completamente definido seja incorporado num objecto HTML object, através da referência ao ficheiro html. A inclusão permite a inserção de um fragmento html directamente a partir de um ficheiro html. Um subelemento title define o título da página. Um subelemento anchor define um ponto onde podem ser efectuadas contribuições externas por parte de um elemento <extensionContent>.


group


<!ELEMENT group (group* | link* | text* | img* | include* | html* | anchor*)>

<!ATTLIST group

id           CDATA #REQUIRED

label        CDATA #IMPLIED

style-id     CDATA #IMPLIED

computed     CDATA (true|false) "false"
bgImage      CDATA #IMPLIED

filteredFrom (swt|html) >

Utilizado para agrupar conteúdos relacionados, conteúdos que devem ter estilos semelhantes aplicados ou conteúdos que serão incluídos conjuntamente noutras páginas.


link


<!ELEMENT link (text? , img?)>

<!ATTLIST link

id           CDATA #IMPLIED

label        CDATA #IMPLIED

url          CDATA #REQUIRED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

Pode ligar a um ficheiro HTML estático, um sítio da Web externo ou pode executar uma acção do URL do componente Intro.




As acções predefinidas serão descritas utilizando este formato:

nome de acção - descrição de acção
action parameter1 - descrição do parâmetro
action parameter2 (optional) - descrição do parâmetro
parâmetro3 de acção (opcional) = ("true" | "false") "false" - descrição de parâmetro, escolha entre true ou false e "false" é a predefinição


As seguintes acções predefinidas estão incluídas na infra-estrutura de introdução:

close - fecha o componente Intro
Não são necessários parâmetros

execute - executa um comando específico. Consulte o método serialize() em org.eclipse.core.command.ParameterizedCommand para mais detalhes sobre o formato de serialização do comando. A partir da versão 3.2.
command - um ParameterizedCommand serializado
standby (optional) = ("true" | "false") "false" - indica se a introdução deve ser definida em modo de espera após executar o comando

navigate - navegar pelas páginas da introdução numa determinada direcção ou regressar à página inicial
direction = ("backward" | "forward" | "home") - especifica o sentido de navegação

openBrowser - abrir o url num browser externo. A partir da versão 3.1, esta acção depende do suporte de browser da área de trabalho. Isto significa que qualquer conjunto de preferências do utilizador para o browser será aplicado.
url - um URL válido a um sítio da Web externo ou a um ficheiro HTML estático
pluginId (opcional) - apenas necessário caso seja especificado um ficheiro HTML. Corresponde ao id do plug-in que contém o ficheiro.

openURL - abrir o URL incorporado na página Bem-vindo. No caso da apresentação de SWT, o URL é apresentado num browser externo (semelhante à acção openBrowser anterior). A partir da versão 3.1
url - um URL válido para um sítio da Web externo ou para um ficheiro HTML local.
pluginId (optional) - se o URL é relativo, então especifica o ID do plug-in que contém o ficheiro.

runAction - executa a acção especificada
class - o nome de classe totalmente qualificado da classe que implementa os pontos de extensão org.eclipse.ui.intro.config.IIntroAction, org.eclipse.jface.action.IAction ouorg.eclipse.ui.IActionDelegate
pluginId - o ID do plug-in que contém a classe.
standby (opcional) = ("true" | "false") "false" - indica se a introdução deve ser definida em modo de espera após executar a acção
additional parameters - quaisquer parâmetros adicionais são transferidos para acções que implementam org.eclipse.ui.intro.config.IIntroAction

setStandbyMode - define o estado do componente Intro
standby = ("true" | "false") - true para colocar o componente intro em modo de espera parcialmente visível e false para o tornar completamente visível

showHelp - abrir o sistema de ajuda.
Não são necessários parâmetros

showHelpTopic - abrir um tópico de ajuda.
id - o URL do recurso da ajuda. (Consulte Javadoc de org.eclipse.ui.help.WorkbenchHelp.displayHelpResource
embed (opcional) = ("true" | "false") "true" - indica que o recurso de ajuda tem de ser apresentado incorporado como parte das páginas de boas-vindas. A predefinição é false. Este sinalizador será simplesmente ignorado no caso de uma apresentação de SWt. A partir da versão 3.1
embedTarget (opcional) - o caminho para uma div na actual página Bem-Vindo que irá ter o conteúdo do tópico Ajuda. Caso seja especificado, embed será true predefinição e o URL incorporado será inserido na div com o caminho especificado. O caminho é relativo à página e não deve começar pelo ID da página. Os descendentes da div são substituídos pelo conteúdo do URL. Apenas pode ser utilizada uma div por página como um destino incorporado. Este sinalizador será simplesmente ignorado no caso de uma apresentação de SWt. Também não é suportado quando se utiliza XHTML como conteúdo de introdução. A partir da versão 3.1


showMessage - apresenta uma mensagem ao utilizador usando uma caixa de diálogo informativa standard.
message - a mensagem a mostrar ao utilizador

showStandby - define o componente Intro para o modo em espera e mostra o standbyContentPart com os dados de entrada fornecidos
partId - o ID do standbyContentPart a mostrar
input - os dados de entrada a definir em standbyContentPart

showPage - mostrar a página de introdução com um determinado id
id - o ID da página de introdução a mostrar
standby (opcional) = ("true" | "false") "false" - indica se a introdução deve ser definida em modo de espera após mostrar a página

Se quaisquer parâmetros transferidos para estas acções tiverem caracteres especiais (isto é, caracteres que não são legais num URL), então devem ser codificados utilizando a codificação de URL UTF-8. Para receber estes parâmetros em estado descodificado, pode ser utilizado um parâmetro especial, decode = ("true" "false") , para forçar a descodificação destes parâmetros quando a estrutura Intro os processa.
Por exemplo, o seguinte URL de introdução:
http://org.eclipse.ui.intro/showMessage?message=Isto+é+uma+mensagem
irá processar o parâmetro de mensagens como "Isto+é+uma+mensagem"
em que
http://org.eclipse.ui.intro/showMessage?message=Isto+é+uma+mensagem&amp;decode=true
irá processar o parâmetro de mensagens como "Isto é uma mensagem".


  • style-id - Uma forma de classificar esta ligação numa determinada categoria, para que se possa aplicar um estilo comum.
  • filteredFrom - um atributo opcional que permite a filtração de um determinado elemento de uma implementação específica. Por exemplo, se um grupo tem filteredFrom = swt, significa que este grupo não irá aparecer como conteúdo na implementação swt.
  • html


    <!ELEMENT html (img | text)>

    <!ATTLIST html

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    type         (inline|embed)

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    encoding     CDATA #IMPLIED

    HTML directo a incluir na página quer incorporando todo o documento ou inserindo um fragmento in loco HTML. Deve definir-se uma imagem ou texto de urgência para a representação da apresentação swt alternativa. Se o conteúdo contiver segmentos de substituição do formato $plugin:plugin_id$, estes serão substituídos pelo caminho absoluto para o plug-in com plugin_id.
    A incorporação permite que um ficheiro html totalmente definido seja incorporado no conteúdo da página dinâmica. É criado um elemento object que referencia o ficheiro html.
    A inclusão permite a inserção de um fragmento html directamente a partir de uma página html dinâmica.


    hr


    <!ELEMENT hr EMPTY>

    <!ATTLIST hr

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    uma regra horizontal.


    title


    <!ELEMENT title EMPTY>

    <!ATTLIST title

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    um fragmento de texto que pode conter opcionalmente códigos de escape HTML. É utilizado apenas como um Título de Página e por isso uma determinada página pode ter um máximo de um elemento title.


    text


    <!ELEMENT text EMPTY>

    <!ATTLIST text

    id           CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    um fragmento de texto que pode conter opcionalmente códigos de escape HTML. Pode incluir códigos b e li. Também pode conter referências a URLs. Caso sejam necessários vários parágrafos, o texto pode ser dividido em várias secções, todas elas começadas e terminadas com o identificador p.


    include


    <!ELEMENT include EMPTY>

    <!ATTLIST include

    configId    CDATA #IMPLIED

    path        CDATA #REQUIRED

    merge-style (true | false) >

    Expande um elemento de destino um de um determinado caminho e atributos configID opcionais. O caminho deve dirigir exclusivamente dentro da configuração especificada. Pode indicar um grupo partilhado definido ao nível da configuração ou qualquer elemento numa página.


    head


    <!ELEMENT head EMPTY>

    <!ATTLIST head

    src CDATA #REQUIRED>

    encoding     CDATA #IMPLIED

    HTML directo a incluir numa área de conteúdo HEAD da página. Permite que seja adicionado html adicional à secção HTML HEAD. Esta capacidade é útil para adicionar scripts Java ou folhas de estilos adicionais. Se o conteúdo contiver segmentos de substituição do formato $plugin:plugin_id$, estes serão substituídos pelo caminho absoluto para o plug-in com plugin_id. Esta marcação deve ser utilizada apenas com uma implementação do componente Intro baseada em HTML. Será simplesmente ignorado no caso de uma implementação de formulários de UI. Uma página pode ter mais do que um elemento head. Uma implementação pode ter apenas um elemento head (uma vez que é partilhado através de todas as páginas).


    img


    <!ELEMENT img EMPTY>

    <!ATTLIST img

    id           CDATA #REQUIRED

    src          CDATA #REQUIRED

    alt          CDATA #IMPLIED

    style-id     CDATA #IMPLIED

    filteredFrom (swt|html) >

    Uma imagem que representa o conteúdo da introdução e não uma apresentação (em oposição a imagens de decoração definidas nos estilos).


    extensionContent


    <!ELEMENT extensionContent (text | group | link | html | include)>

    <!ATTLIST extensionContent

    style     CDATA #IMPLIED

    alt-style CDATA #IMPLIED
    id       CDATA #IMPLIED

    name     CDATA #IMPLIED

    path      CDATA #REQUIRED>

    O conteúdo a ser adicionado à referência de destino. Só é permitido um extensionContent numa configExtension estabelecida, porque se não tiver sido possível processar esta extensão (caso a configuração ou o elemento de âncora destino não tenham sido encontrados), as páginas e/ou grupos da extensão têm de ser ignorados.


    anchor


    <!ELEMENT anchor EMPTY>

    <!ATTLIST anchor

    id CDATA #REQUIRED>

    Uma referência é o elemento utilizado para declarar a extensibilidade. É uma localização na configuração que permite contribuições externas. Apenas as referências são valores de destino válidos para o atributo path no extensionContent


    contentProvider

     

    <!ELEMENT contentProvider (text)>

    <!ATTLIST contentProvider

    id       CDATA #REQUIRED

    pluginId CDATA #IMPLIED

    class    CDATA #REQUIRED>

     

    Um proxy para um fornecedor de conteúdo de introdução, que permite que uma página de introdução extraia dados de modo dinâmico a partir da várias origens (por exemplo, a web, eclipse, etc.) e fornece o conteúdo no ambiente de execução com base nestes dados dinâmicos. Se a classe IIntroContentProvider for especificada no atributo class, não poderá ser transferida, então, em vez disso, será representado o conteúdo do elemento text. Esta é a versão dinâmica do código de introdução html. Enquanto que o código html permite a incorporação ou introdução de um conteúdo html estático na página de introdução html gerada, o código contentProvider permite a criação dinâmica desse conteúdo no tempo da execução. Outra diferença entre os códigos é que o código html é suportado apenas para a apresentação HTML, enquanto que este código contentProvider é suportado para apresentações HTML e SWT. A partir da 3.0.1