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.
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>
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>
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.
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.