Acções do Documento
17.
Apêndice C: Referência de Modelos de Página do Zope
Subir um nível
Visão geral da TAL
O padrão Template Attribute Language (TAL) é uma linguagem de atributos usada para criar modelos (templates) dinâmicos. Ele permite substituir, repetir ou omitir elementos de um documento.
As instruções (instruçãos) TAL são atributos XML do espaço de nomes (namespace) TAL.Estes atributos podem ser aplicados a um documento XML ou HTML de forma a fazê-lo agir como um modelo.
Uma TAL instrução (instrução TAL) tem um nome
(o atributo nome)
e um corpo (o valor do atributo). Por exemplo, uma instrução content
será como tal:content="string:Hello". O elemento onde uma
instrução é
definida é um instrução element. A maioria das instruções
TAL
requere expressões, mas a sintaxe e semântica dessas expressões
não são parte
da TAL. TALES é recomendada para este propósito.
Namespace da TAL
O URI e alias recomendado para O espaço de nomes TAL são atualmente
definidos como:
xmlns:tal="http://xml.zope.org/namespaces/tal"
Isso não é uma URL mas meramente um identificador único.
Não espere que um
browser resolva este endereço com sucesso.
Zope não requer uma instrução de espaço de nomes
XML quando cria modelos
com um conteúdo do tipo text/html. Entretanto, requer uma instrução
de espaço
de nomes XML para todos os outros tipos de conteúdo.
Expressões da TAL
Estas são as instruções tal:
- tal:attributes - muda atributos do elemento dinamicamente.
- tal:define - define variáveis.
- tal:condition - testa condições.
- tal:content - altera o conteúdo de um elemento.
- tal:omit-tag - remove um elemento, sdeixando seu conteúdo.
- tal:on-error - manipula erros.
- tal:repeat - repete um elemento.
- tal:replace - altera o conteúdo de um elemento e o remove, deixando
seu conteúdo.
Expressões usadas em instruções podem retornar valores
de qualquer tipo,
embora a maioria das instruções aceitarão apenas strings,
ou converterão
valores para uma representação de string. A linguagem de expressão
deve definir
um valor denominado nothing que não é uma string. Em particular,
este valor é útil
para deletar elementos ou atributos.
Ordem das operações
Quando há apenas uma instrução TAL por elemento, a ordem
na
qual eles são executados é simples. Começando pelo elemento
raiz,
cada instrução de elemento é executada, então cada
um dos seus filhos
é visitado, em ordem, para fazer o mesmo.
Qualquer combinação de instruções podem aparecer
nos mesmos elementos,
excetuando-se content e replace que não podem aparecer juntos.
Quando um elemento tem múltiplas instruções, elas são
executadas na ordem seguinte:
1. 'define'
2. 'condition'
3. 'repeat'
4. content or 'replace'
5. 'attributes'
6. 'omit-tag'
Desde que a instrução on-error é invocada apenas quando
um erro ocorre,
ela não aparece na lista.
O raciocínio por trás desta ordem é o seguinte: você
frequentemente quer
utilizar variáveis em outras instruções, então define
vem antes.
A próxima coisa a fazer é decidir se esse elemnto será
mesmo incluido, então
condition vem a seguir; desde que a condição pode depender de
variáveis
recém declaradas, ela vem após define. É de valor poder
substituir várias partes
de um elemento com diferentes valores em cada iteração de uma
repetição, então
repeat é o próximo. Não faz sentido substituir atributos
e descartá-los, então
attributes vem por último. As instruções restantes conflitam,
porque
substituem ou editam um elemento da instrução.
Veja também
Visão Geral de TALES
Visão Geral de METAL
tal:attributes
tal:define
tal:condition
tal:content
tal:omit-tag
tal:on-error
tal:repeat
tal:replace
attributes: Trocando os atributos de um elemento
Sintaxe
tal:attributes sintax::
argument ::= attribute_instrução [; attribute_instrução]*
attribute_instrução ::= attribute_name expression
attribute_name ::= [namespace ':'] Name
namespace ::= Name
*Nota: A inclusão de ponto e vírgula (;) em um elemento 'expression'
deve ser dobrada (;;).*
Descrição
A instrução tal:attributes substitui o valor de um atributo
(ou cria um atributo) com um valor dinâmico. Você pode qualificar
o
nome de um atributo com um prefixo de espaço de nomes, por exemplo, html:table,
se
você está gerando um documento XML com múltiplos espaços
de nomes. O valor para cada
expressão é convertido para uma string se necessário.
Se uma expressão associada a uma atribuição a um atributo
retorna
nothing, então o atributo é deletado do elemento da instrução.
Se a expressão retorna default, então este atributo não
é modificado.
Cada atribuição é independente, então atributos
podem receber valores
em uma mesma instrução na qual alguns atributos são deletados
e outros não.
Se você usa tal:attributes em um elemento com um comando tal:replace,
a
instrução tal:attributes é ignorada.
Se você usa tal:attributes em um elemento com uma instrução
tal:repeat,
a substituição é feita em cada repetição
do elemento e a expressão de substituição é
calculada novamente para cada repetição.
Exemplos
Substituindo um link::
<a href="/sample/link.html"
tal:attributes="href here/sub/absolute_url">
Substituindo dois atributos::
<textarea rows="80" cols="20"
tal:attributes="rows request/rows;cols request/cols">
condition: Condicionando a inserção ou remoção de um elemento
Sintaxe
tal:condition sintax::
argument ::= expression
Descrição
A instrução tal:condition inclui o elemento no modelo somente
se a condição
é satisfeita e omite caso contrário. Se a expressão retorna
verdadeiro, então o
processamento normal do elemento continua, caso contrário o elemento
é imediatamente
removido do modelo. Por isso, nothing é falso e default é
verdadeiro.
Nota: Zope considera variáveis ausentes, None*, zero, strings vazias
e sequências
vazias como falso; todos os outros valores equivalem a verdadeiro.*
Exemplos
Testar uma variável antes de inserí-la (o primeiro exemplo testa
pela existência
e verdade, enquanto que o segundo testa apenas pela existência)::
<p tal:condition="request/message | nothing"
tal:content="request/message">message goes here</p>
<p tal:condition="exists:request/message"
tal:content="request/message">message goes here</p>
Testar para condições alternativas::
<div tal:repeat="item python:range(10)">
<p tal:condition="repeat/item/even">Even</p>
<p tal:condition="repeat/item/odd">Odd</p>
</div>
content: Trocando o conteúdo de um elemento
Sintaxe
tal:content sintax::
argument ::= (['text'] | structure) expression
Descrição
Ao invés de substituir um elemento por inteiro, você pode inserir
texto ou estrutura
no lugar de seus filhos atrvés de tal:content. O argumento da expressão
é exatamente
igual ao de tal:replace e é interpretado da mesma forma. Se a expressão
retorna nothing,
a instrução é deixada sem filhos. Se a expressão
retorna default, então o conteúdo do
elemento não é modificado.
*Nota: O comportamento de substituição default é text.*
Exemplos
Inserindo o nome do usuário::
<p tal:content="user/getUserName">Fred Farkas</p>
Inserindo HTML/XML::
<p tal:content="structure here/getStory">marked <b>up</b>
content goes here.</p>
Veja também
'tal:replace'
define: Definindo variáreis
Sintaxe
tal:define sintax::
argument ::= define_scope [; define_scope]*
define_scope ::= (['local'] | global) define_var
define_var ::= variable_name expression
variable_name ::= Name
*Nota: A inclusão de ponto e vírgula (;) em um elemento 'expression'
deve ser dobrada (;;).*
Descrição
A instrução tal:define define variáveis. Você
pode definir dois
diferentes tipos de variáveis TAL: local e global. Quando você
define uma local
em um elemento de instrução, você so pode utilizar esta
variável neste elemento e nos
elemntos por ele contidos. Se você redefine uma variável local
em um elemento contido,
a nova definição esconde a anterior dentro do elemento contido.
Quando você define
variáveis globais, você pode utilizá-la em qualquer elemento
que segue a definição.
Se você redefine uma global, sua definição é substituída
para o restante do modelo.
Nota: variáveis locais são o default
Se uma expressão associada a uma variável retorna nothing, então
esta variável tem o
valor nothing, e pode ser usada como tal em expressões seguintes. Da
mesma forma,
se a expressão retorna default, então esta variável tem
o
valor default, e pode ser usada como tal em expressões seguintes.
Exemplos
Definindo uma variável global::
tal:define="global company_name string:Zope Corp, Inc."
Definindo duas variáveis, onde a segunda depende da primeira::
tal:define="mytitle template/title; tlen python:len(mytitle)"
omit-tag: Removendo um elemento, deixando seu conteúdo
Sintaxe
tal:omit-tag sintax::
argument ::= [ expression ]
Descrição
A instrução tal:omit-tag deixa o conteúdo de uma tag
no lugar enquanto omite as
tags de início e fim.
Se a expressão retorna falso, então o processamento normal do
elemento prossegue
e a tag não é omitida. Se retornar verdadeiro ou se não
houver expressão, a instrução
da tag é substituída por seu conteúdo.
Nota: Zope considera variáveis ausentes, None*, zero, strings vazias
e sequências
vazias como falso; todos os outros valores equivalem a verdadeiro.*
Exemplos
Omitindo uma tag incondicionalmente::
<div tal:omit-tag="" comment="This tag will be removed">
<i>...but this text will remain.</i>
</div>
Omitindo uma tag condicionalmente::
<b tal:omit-tag="not:bold">I may be bold.</b>
O exemplo acima omitirá a tag b se avariável bold é
falsa.
Criando tags de dez parágrafos, sem tag de fechamento::
<span tal:repeat="n python:range(10)"
tal:omit-tag="">
<p tal:content="n">1</p>
</span>
on-error: Manipulando erros
Sintaxe
tal:on-error sintax::
argument ::= (['text'] | structure) expression
Descrição
A instrução tal:on-error provê manipulação
de erros para o modelo.
Qual uma expressão TAL produz um erro, seu interpretador busca por uma
instrução tal:on-error no mesmo elemento, no elemento que o
contém e assim
por diante. A primeira tal:on-error encontradaé invocada e tratada
como
uma instrução tal:content.
Uma variável local error é criada. Esta variável tem
os seguintes atributos:
type -- tipo da exceção
value -- a instãncia da exceção
traceback -- o objeto de traceback
O tipo mais simples de instrução tal:on-error possui uma string
literal
de erro ou nothing para uma expressão. Um manipulador mais complexo
pode
chamar um script que examina o erro e emite uma mensagem de erro ou propaga
a exceção a frente.
Exemplos
Mensagem de erro simples::
<b tal:on-error="string: Usuário não definido!"
tal:content="here/getUsername">Ishmael</b>
Remivendo elementos com erros::
<b tal:on-error="nothing"
tal:content="here/getUsername">Ishmael</b>
Chamando um script de manipulação de erro::
<div tal:on-error="structure here/errorScript">
...
</div>
Abaixo como este script ficaria::
## Script (Python) "errHandler"
##bind namespace=_
##
error=_['error']
if error.type==ZeroDivisionError:
return "<p>Não posso dividir por zero.</p>"
else
return """<p>Um erro ocorreu.</p>
<p>Tipo do erro: %s</p>
<p>Valor: %s</p>""" % (error.type, error.value)
Veja também
"Python Tutorial: Errors and
Exceptions":http://www.python.org/doc/current/tut/node10.html
"Python Built-in
Exceptions":http://www.python.org/doc/current/lib/module-exceptions.html
repeat: Repetindo um elemento
Sintaxe
tal:repeat sintax::
argument ::= variable_name expression
variable_name ::= Name
Descrição
A instrução tal:repeat replica uma sub-árvore de seu
documento
uma vez para cada item em uma sequência. A expressão deve retornar
uma sequência. Se a sequência for vazia, então o elemento
é deletado,
caso contrário é repetido para cada valor na sequência.
Se a expressão
for default, então o elemento não é modificado e nenhuma
nova
variável é definida.
A expressão variable_name é usada para definir uma variável
local
e uma de repetição. Para cada repetição, a variável
local recebe o
elemento atual e a de repetição recebe um objeto de iteração.
Variáveis de repetição
Você utiliza variáveis de repetição para acessar
informação sobre
a repetição atual (como o índice de repetição).
A variável de
repetição tem o mesmo nome que a variável local, mas só
é acessível
através da variável embutida denominada repeat.
As informações a seguir são disponibilizadas da variável
de repetição:
o index - número de repetição, começando de zero.
o number - número de repetição, começando de um.
o even - verdadeiro para repetições indexadas por pares (0,
2, 4, ...).
o odd - verdadeiro para repetições indexadas por ímpares
(1, 3, 5, ...).
o start - verdadeiro para a repetição inicial (index 0).
o end - verdadeiro para repetição final.
o first - verdadeiro para o primeiro elemento em um grupo - veja nota abaixo
o last - verdadeiro para o último elemento em um grupo - veja nota
abaixo
o length - tamanho da sequência, que será o número total
de repetições.
o letter - número de repetição como uma letra minúscula:
"a" -
"z", "aa" - "az", "ba" - "bz",
..., "za" - "zz", "aaa" - "aaz",
e assim por diante.
o Letter - versão upper-case de letter.
o roman - número de repetição como numeral romano minúsculo:
"i", "ii", "iii", "iv", "v",
etc.
o Roman - versão upper-case de roman.
Você pode acessar o conteúdo da variável de repetição
usando
expressões de caminho (path expressions) ou expressões Python.
Em expressões de caminho, você escreve um caminho de três
partes
consistindo de do nome repeat, o nome da variável da instrução
e o nome da informação que você deseja, por exemplo, repeat/item/start.
Em expressões Python, você usa a noatação normal
de dicionário para
obter a variável de repetição, então o atributo
para obter a informação,
por exemplo, "python:repeat['item'].start".
Note que first e last são usados em sequências ordenadas.
Eles tentam dividir a sequência em um grupode itens com o mesmo
valor. Se você provê um caminho, então o valor obtido seguindo
este
caminho de um item de sequência é usado para agrupamento, caso
contrário
o valor do item é utilizado. Você pode prover um caminho passando-o
como parâmetro, como em "python:repeat['item'].first(color)",
ou
apendando-o ao caminho da variável de repetição como em
"repeat/item/first/color".
Exemplos
Iterando sobre uma sequência de strings::
<p tal:repeat="txt python:one, two, three">
<span tal:replace="txt" />
</p>
Inserindo uma seuência de linhas de tabela e usando a variável
de repetição para
numerar as linhas::
<table>
<tr tal:repeat="item here/cart">
<td tal:content="repeat/item/number">1</td>
<td tal:content="item/Descrição">Dispositivo</td>
<td tal:content="item/preço">R$1.50</td>
</tr>
</table>
Repeats aninhados::
<table border="1">
<tr tal:repeat="row python:range(10)">
<td tal:repeat="column python:range(10)">
<span tal:define="x repeat/row/number;
y repeat/column/number;
z python:x*y"
tal:replace="string:$x $y = $z">1 1 = 1</span>
</td>
</tr>
</table>
Inserir objetos. Separar grupos de objetos por meta-tipo através de uma
regra entre eles::
<div tal:repeat="object objects">
<h2 tal:condition="repeat/object/first/meta_type"
tal:content="object/meta_type">Meta Tipo</h2>
<p tal:content="object/getId">ID do Objeto</p>
<hr tal:condition="repeat/object/last/meta_type" />
</div>
Note que os objetos no exemplo acima devem já estar ordenados por meta-tipo.
replace: Trocando um elemento
Sintaxe
tal:replace sintax::
argument ::= (['text'] | structure) expression
Descrição
A instrução tal:replace substitui um elemento com conteúdo
dinâmico.
Substitui o elemento com um texto ou uma estrutura (unescaped markup).
O corpo da instrução é uma expressão com um prefixo
de tipo opcional.
O valor da expressão é convertido para uma "escaped string"
se você prefixar
a expressão com text ou omitir o prefixo e é inserido sem modificações
se você prefixar com structure. "Escaping" consiste de converter
"&" para "&amp;", "<" para
"&lt;" e ">" para "&gt;".
Se o valor é nothing, então o elemento é simplesmente
removido. Se o valor é default,
então o elemento não é modificado.
Exemplos
As duas formas de inserir o título de um modelo::
<span tal:replace="template/title">Título</span>
<span tal:replace="text template/title">Título</span>
Inserindo HTML/XML::
<div tal:replace="structure table" />
Inserindo nada::
<div tal:replace="nothing">Este elemento é um comentário.</div>
Veja também
'tal:content'
