7.6. Entidades

Entidades são um mecanismo para atribuir nomes a partes do conteúdo. À medida que um XML parser processa um documento, qualquer entidade encontrada é substituída pelo conteúdo da entidade.

Esta é uma boa maneira de ter pedaços de conteúdo reutilizáveis ​​e facilmente alteráveis ​​em documentos XML. Também é a única maneira de incluir um arquivo markup dentro de outro usando XML.

Existem dois tipos de entidades para duas situações diferentes: entidades gerais e entidades de parâmetros.

7.6.1. Entidades Gerais

Entidades gerais são usadas para atribuir nomes a partes reutilizáveis ​​de texto. Essas entidades só podem ser usadas no documento. Elas não podem ser usadas ​​em um contexto XML.

Para incluir o texto de uma entidade geral no documento, inclua &nome-da-entidade; no texto. Por exemplo, considere uma entidade geral chamada current.version, que se expande para o número da versão atual de um produto. Para usá-la no documento, escreva:

<para>The current version of our product is
  &current.version;.</para>

Quando o número da versão for alterado, edite a definição da entidade geral, substituindo o valor. Em seguida, reprocesse o documento.

Entidades gerais também podem ser usadas para inserir caracteres que não poderiam ser incluídos em um documento XML. Por exemplo, < e & normalmente não podem aparecer em um documento XML. O XML parser vê o símbolo < como o início de uma tag. Da mesma forma, quando o símbolo & é visto, espera-se que o próximo texto seja um nome de entidade.

Esses símbolos podem ser incluídos usando duas entidades gerais predefinidas: &lt; e &amp;.

Entidades gerais só podem ser definidas dentro de um contexto XML. Tais definições geralmente são feitas imediatamente após a declaração DOCTYPE.

Exemplo 7.8. Definindo Entidades Gerais
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY current.version    "3.0-RELEASE">
<!ENTITY last.version       "2.2.7-RELEASE">
]>

A declaração DOCTYPE foi estendida adicionando um colchete no final da primeira linha. As duas entidades são então definidas nas próximas duas linhas, o colchete é fechado e, em seguida, a declaração DOCTYPE é fechada.

Os colchetes são necessários para indicar que o DTD indicado pela declaração DOCTYPE está sendo estendido.


7.6.2. Entidades de Parâmetro

Entidades de parâmetro, como as entidades gerais, são usadas para atribuir nomes a blocos reutilizáveis ​​de texto. Mas as entidades de parâmetro só podem ser usadas dentro de um contexto XML.

As definições de entidade de parâmetro são semelhantes àquelas para entidades gerais. No entanto, entradas de parâmetros são incluídas com %nome-da-entidade;. A definição também inclui o % entre a palavra-chave ENTITY e o nome da entidade.

Para memorizar, lembre que entidade deParâmetro utiliza o símbolo de Porcentagem.

Exemplo 7.9. Definindo Entidades de Parâmetro
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
<!ENTITY % entity "<!ENTITY version '1.0'>">
<!-- use the parameter entity -->
%entity;
]>

À primeira vista, as entidades de parâmetros não parecem muito úteis, mas elas tornam possível incluir outros arquivos em um documento XML.

7.6.3. Para Fazer…

  1. Adicione uma entidade geral ao arquivo example.xml.

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
    <!ENTITY version "1.1">
    ]>
    
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
        <title>An Example XHTML File</title>
      </head>
    
      <!-- There may be some comments in here as well -->
    
      <body>
        <p>This is a paragraph containing some text.</p>
    
        <p>This paragraph contains some more text.</p>
    
        <p align="right">This paragraph might be right-justified.</p>
    
        <p>The current version of this document is: &version;</p>
      </body>
    </html>
  2. Valide o documento usando o xmllint.

  3. Carregue example.xml em um navegador web. Ele pode ter que ser copiado para o example.html antes que o navegador o reconheça como um documento XHTML.

    Navegadores mais antigos com parsers simples podem não renderizar esse arquivo conforme o esperado. A referência de entidade &version; pode não ser substituída pelo número da versão, ou o fechamento de contexto XML ]> pode não ser reconhecido e em vez disso, apresentado literalmente.

  4. A solução é normalizar o documento com um normalizador XML. O normalizador lê um XML válido e grava outro XML igualmente válido. Uma maneira pela qual o normalizador transforma a entrada é expandindo todas as referências de entidade no documento, substituindo as entidades pelo texto que elas representam.

    O xmllint pode ser usado para isso. Ele também tem a opção de remover a seção inicial DTD para que ]> não confunda os navegadores:

    % xmllint --noent --dropdtd example.xml > example.html

    Uma cópia normalizada do documento com entidades expandidas é produzida em example.html, pronta para ser carregada em um navegador web.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.