1.4. 1. TAL – Declaracões

Tema Plone – Referencia – Índice

Zope Page Template – índice

Estas são as declaracões TAL:

• tal:attributes → muda atributos do elemento (tag) dinamicamente.
• tal:define → define variáveis.
• tal:condition → testa condições
• tal:content → substitui o conteúdo de um elemento (tag).
• tal:omit-tag → remove um elemento, deixando o conteúdo do elemento
• tal:on-error → trata os erros.
• tal:repeat → repete um elemento.
• tal:replace → substitui o conteúdo da tag e remove a tag.

Expressões usadas nas declaracões podem retornar valores de algum tipo, embora a maioria das declaracões aceitarem apenas strings, ou converter-los para uma representação string.

Ordem dos elementos (tags)

Quando existe apenas uma declaração TAL por tag, a ordem na qual eles são executadas é simples. Começando com a tag principal, cada declaração das tags filhas é executada, em ordem.

Algumas combinações de declaracões podem aparecer na mesma tag, exceto as declaracões content e replace que não podem aparecer juntos.

Devido ao fato de que TAL olha as declaracões como atributos XML, mesmo em documentos HTML, ele não pode usar a ordem em que as declaracões são escritas na tag para determinar a ordem em que elas são executadas. O TAL deve também proibir múltiplas declaracões do mesmo tipo em um único elemento, então isto e’ o suficiente para organizar os tipos de declaracões em uma lista de prioridade.

Quando um elemento tem múltiplas declaracões, eles são executadas na seguinte ordem:

1. define
2. condition
3. repeat
4. content or replace
5. attributes
6. omit-tag

Como a declaração on-error é apenas invocada quando um erro ocorre, ele não aparece na lista.

Pode não ser aparente que existe necessidades para se ter uma ordem. A razão de dever existir um é que a linguagem de atributos TAL é baseado no XML.

Introdução a sintaxe de comandos TAL

1.1. tal:define: Definindo Variáveis

A declaração tal:define permite a criação e a e reutilização de variáveis dentro dos templates.

Por exemplo:

<p tal:define=”container_title here/title_or_id”>

…

<i tal:content=”container_title”>The title</i>

…

</p>

Neste exemplo, o título da variável é criado e determinado pelo resultado de here/title_or_id; depois a variável container_title é usada na declaração tal:content.

Por padrão a variável é criada localmente dentro do namespace do elemento atual. Assim, no exemplo anterior, só elementos dentro da tag parágrafo <p> podem usar a variável container_title. Você pode redefinir a variável em qualquer lugar dentro da declaração ou reutilizá-la em outros elementos quantas vezes forem necessárias.

Para criar uma variável para ser usada globalmente, você pode usar o prefixo global. Isto permitirá acesso para a variável de qualquer lugar dentro do template, não apenas definindo dentro do elemento.

Por exemplo:

<p tal:define=”global title_exemple string:Foo bar”>

… <i tal:content=”title_exemple”> The titl e</i> …

</p>

<i tal:content=”title”>We still have a title</i>

1.2. tal:condition: Avaliando Condições

A declaração tal:condition permite que a condição seja testada antes de exibir o elemento. Por exemplo:

<p tal:condition=”request/message”>

Minha menssagem

</p>

<p tal:condition=”not: request/message”>

Nenhuma menssagem

</p>

O parágrafo com o texto para mensagem será mostrado somente se a variável request conter um atributo (solucionado como true). O prefixo not: inverte a declaração, assim not: request/message resulta em true se a mensagem da variável pedida resulta false.

Em TAL, os seguintes resultados resultam em false:

• O número zero
• Qualquer float ou complex que resultam em zero (por exemplo, 0.0)
• Strings com zero caracteres de tamanho (por exemplo, “”)
• Uma lista ou tupla vazia
• Um dicionário Python vazio
• Valor Python None
• Valor TALES nothing

Os seguinte resultados resultam em true:

• O valor padrão
• Qualquer número diferente de zero
• Strings que não estão vazias
• Strings que são apenas espaços (por exemplo, ” “)
• Qualquer outra coisa

1.3. tal:content: Substituindo Texto

A declaração tal:content é geralmente a declaração mais usada em um page template. Esta declaração é também uma das mais simples, substituindo o conteúdo de um elemento com o valor especificado.

Exemplo:

<i tal:content=”context/title_or_id”>Some title</i>

A saída:

<i>The title</i>

Isto substituirá o texto Some title com o valor da expressão context/title_or_id. Se o texto a ser colocado possuir elementos HTML, aqueles elementos serão retirados.

Por padrão, o texto a ser substituído é não HTML (ou seja, escaped); o prefixo structure permitirá o HTML ser incorporado sem os elementos que estão sendo suprimidos. Por exemplo:

<i tal:content=”structure here/title_or_id”>Do not escape HTML</i>

Saída:

<i><b>The title<b></i>

1.4. tal:replace: Adicionando Texto

A declaração tal:replace é similar para tal:content com uma diferença, esta remove a tag inteira.

Exemplo:

<p tal:replace=”context/title_or_id”>Some title</p>

Isto fará o resultado da expressão context/title_or_id mas removerá do resultado as tags do parágrafo. Isto é o equivalente a:

<p

tal:content=”here/title_or_id”

tal:omit-tag=”">Some title

</p>

Se a declaração tal:replace contém outros elemento, então todos os elementos serão substituídos. Você não pode usar a declaração tal:replace com tal:attributes ou tal:content; eles são mutuamente exclusivos, e um erro será mostrado se você coloca-los no mesmo elemento.

1.5. tal:omit-tag: Removendo elementos

O tal:omit-tag é bastante incomum, ele permite a remoção de uma tag. O sistema Zope Page Templates requer o uso de tags HTML, páginas complexas podem precisar freqüentemente de muitos elementos e podem resultar em tags extras. Para está declaração, a tag é removida, deixando apenas o conteúdo das tags.

Por exemplo:

<p tal:omit-tag=”">This is some text</p>

A saída é como a seguinte:

This is some text

Neste exemplo, o texto This is some text será passado; porém, a tag não será passada. Opcionalmente, a declaração tal:omit-tag pode receber uma expressão como um argumento. Se a expressão for avaliada false, então a tal:omit-tag não ocorre.

Exemplo:

<p tal:omit-tag=”nothing”>This is some text</p>

1.6. tal:attributes: Mudando os Atributos de um Elemento

O tal:attributes permite que você substitua um ou mais atributos de um elemento. Uma declaração contém o atributo para ser mudado, separado por um espaço da declaração.

Exemplo:

<a href=”#”

tal:attributes=”href context/absolute_url”>

Clique aqui

</a>

Isto mudará o atributo href do link para o resultado da expressão here/absolute_url. O atributo href já foi definido neste elemento, então se um designer abrir a página, o designer irá ver um elemento válido (embora o link não faça sentido até que a página seja processada pelo servidor). Segue exemplo de uma saída depois de processada:

<a href=”http://plone.org/”>Clique aqui</a>

Sabendo que cada elemento possa ter múltiplos atributos, tal:attributes permite que você altere um ou mais atributos simultaneamente tendo declarações múltiplas. Para mudar múltiplos atributos de uma vez, separe as declarações com ponto-e-vírgula (;). Se o atributo ou a declaração conter ponto-e-vírgula, você pode deverá digitar outro ponto-e-vírgula (;;).

Por exemplo, para mudar ambos os elementos href e title, faça o seguinte:

<a href=”#”

tal:attributes=”href context/absolute_url; title context/title_or_id”>

Link

</a>

A saída será:

<a href=”http://plone.org/”>Plone Org</a>

1.7. tal:on-error: Executando a Manipulação de Erro

A declaração tal:on-error fornece um método para manipular erros. Funciona com o comando tal:content que promove a substituição do conteúdo da tag, mas somente quando ocorre um erro.

<p tal:content=”request/message”

tal:on-error=”string: No message”>

Message

</p>

Se houver um erro na avaliação da expressão request/message, então o atributo on-error será ativado. Isto faz com que o conteúdo da tag seja substituído com o texto No message.

Infelizmente, a declaração on-error é bastante limitada. A tag não consegue distinguir entre os diferentes tipo de erro e permite apenas que uma expressão seja avaliada e usada. Está limitação é de projeto assim a tag não pode ter um uso excessivo. A manipulação de erro deve realmente ser segurada na lógica de sua aplicação.

Felizmente, para todas as expressões, você pode fornecer alternativas na declaração se a primeira parte da declaração resultar algo diferente de true ou false (em outras palavras, se um erro é mostrado). Cada alternativa é separada por um caractere pipe (|), e múltiplas alternativas podem aparecer em uma declaração. Se você está apoiado nas variáveis da requisição que chega, então sempre adicione um |nothing no final para assegurar que o erro atribuído não seja mostrado.

Por exemplo:

<p tal:content=”request/message”

tal:condition=”request/message | nothing”>

There’s a message

</p>

<p tal:condition=”not: request/message | nothing”>

No message

</p>

Este segundo exemplo é mais trabalhoso, porém mais desejável por um par de razões:

• O programador pode ver a condição positiva e negativa.
• Você pode controlar uma condição de erro mais complicada do que apenas através da impressão de uma string.

~ por Fernando Felix do N. Junior em 27/07/2010.