Filtros

Se determinadas seções do documento só precisarem aparecer em um contexto específico, você pode utilizar a marcação de filtragem para especificar critérios que devem ser atendidos para que a seção do documento seja exibida. Se os critérios não forem atendidos, a seção do documento não ficará visível ao usuário. Os filtros podem ser especificados em qualquer elemento XML, desde que a marcação continue válida depois do processamento. Se um elemento for filtrado, todos os elementos e texto contidos nesse elemento também serão filtrados.

A tabela a seguir contém uma lista completa de todas as propriedades do filtro e seus valores possíveis.

Propriedade Significado Valores Possíveis
S.O. sistema operacional win32, win32, linux, macosx, aix, solaris, hpux, qnx
ws sistema de janelas win32, motif, gtk, photon, carbon
arch arquitetura do processador x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc
produto identificador de produto do eclipse Qualquer identificador do produto (por exemplo, para o SDK, org.eclipse.sdk.ide)
plug-in presença de plug-in Qualquer identificador de plug-in (por exemplo, org.eclipse.help)
categoria categoria de atividades Qualquer identificador de categoria da atividade (por exemplo, categoria da Equipe org.eclipse.categories.teamCategory)
atividade atividade (recurso) Qualquer identificador de atividade (por exemplo, para atividade de Suporte CVS org.eclipse.team.cvs)

Se o nome não corresponder a nenhuma propriedade predefinida, o sistema de ajuda utilizará a propriedade de sistema da JVM desse nome. Por exemplo, você pode informar qualquer propriedade definida pelo usuário na ativação, como -Dlocation=paris,france e filtrar por essa propriedade.

Há duas formas de especificar filtros em um elemento: utilizando atributos ou elementos.

Atributo de Filtro

A primeira forma é incluir um atributofilter no elemento. A forma geral é:

   <element filter="[name][operator][value]">
      Algum texto.
   </element>

O name é o nome da propriedade, pela qual filtrar, por exemplo, os para o sistema operacional. O operator é = para denotar uma match (correspondência exata, distinção entre maiúsculas e minúsculas) ou != para denotar does not match. O value é ao que a propriedade deve (ou não) corresponder. Por exemplo, para os, um dos valores possíveis é win32 (Windows). Uma lista completa de propriedades do filtro e seus valores está disponível na tabela a seguir.

O exemplo a seguir mostra como exibir um parágrafo de texto em um documento XHTML ao executar no Linux apenas.

   <p filter="os=linux">
      Essa mensagem só será exibida no Linux.
</p>

Neste segundo exemplo, o link só aparecerá quando o plug-in com.my.plugin não estiver instalado:

   <a href="..." filter="plugin!=com.my.plugin">
      Clique aqui para fazer download do plug-in com.my.plugin.
   </a>

Elemento de Filtro

A segunda forma é utilizar um elemento filter como um child do elemento que você deseja filtrar. Essa forma é um pouco maior que a forma do atributo, mas é mais eficiente, porque você pode especificar qualquer número de filtros em um elemento. A forma geral é:

   <element attribute="value">
      <filter name="[name]" value="[modifier][value]"/>
   </element>

Aqui, name e value são iguais ao atributo. No entanto, como estão separados, é necessária outra forma para especificar se ou não devem ser correlatos. Por padrão, se você não fornecer um modifier, será considerada a correlação. Se não não deverem ser correlatos, defina o modificador como "! "

Eis o primeiro exemplo mostrado acima na segunda forma:

      <p>
      <filter name="os" value="linux"/>
      Essa mensagem só será exibida no Linux.
</p>

E o segundo exemplo:

   <a href="...">
      <filter name="plugin" value="!com.my.plugin"/>
      Clique aqui para fazer download do plug-in com.my.plugin.
   </a>

Infocenter

O suporte de filtragem é desativado ao executar a ajuda no modo infocenter, fazendo com que todo conteúdo, inclusive o filtrado, fique visível. Se você planeja hospedar sua documentação nos modos ambiente de trabalho e infocenter, utilize filtros de maneira que faça sentido mesmo com a filtragem desativada.

Onde eu posso utilizar filtros?

A filtragem pode ser utilizada nos seguintes tipos de documento:

* Nota: Há algumas etapas adicionais necessárias para a ativação do conteúdo dinâmico nos documentos XHTML.

Em todos os casos, você não deve colocar filtros em nenhum elemento em que a remoção desse elemento possa resultar em XML inválido. Por exemplo, você não deve colocar um filtro no elemento html do XHTML, porque, sem esse elemento, ele não é mais um XHTML válido.