Directives de TAL
-----------------

==============   =============================================
Directives
==============   =============================================
``attributes``   pour changer les attributs de l'élément
``condition``    pour effectuer un test
``content``      pour remplacer le contenu
``omit-tag``     pour supprimer la balise mais pas son contenu
``on-error``     pour gérer les erreurs
``repeat``       pour répéter un élément
``replace``      pour remplacer la balise et son contenu
==============   =============================================


Ordre des opérations
''''''''''''''''''''

Quand un élément comporte plusieurs directives, elles sont exécutées
dans l'ordre suivant :

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

Cet ordre d'opération suit une certaine logique. En effet on définit
des variables avant de les utiliser (donc ``define`` en premier ; ensuite
on détermine si l'élément doit être inclus (donc ``condition``) ; comme
c'est utile de pouvoir remplacer des éléments à chaque itération d'une
boucle, ``repeat`` passe devant ``content`` et ``replace``.

Comme ``replace`` pourrait supprimer l'élément, il n'y a pas de sens à
affecter des attributs à celui-ci, donc ``attributes`` vient à la suite.
``omit-tag`` est dernier.

``on-error`` n'est jamais invoqué qu'en cas d'erreur, il ne fait donc pas
partie de cette liste.

Détails des directives de TAL
'''''''''''''''''''''''''''''

``attributes``
``````````````

``attributes`` sert à modifier (ou ajouter) un ou plusieurs attributs à la
balise où il se trouve. Il ne peut y avoir qu'une seule directive ``attributes``
par élément. On remplace plusieurs attributs non pas en multipliant les
déclarations ``attributes`` mais en séparant les différents attributs par des
points-virgules.

Exemple, ::

	<a href="/" tal:attributes="href '/une-autre-page'">Ailleurs</a>

deviendra ::

	<a href="/une-autre-page">Ailleurs</a>

Et ::

	<textarea tal:attributes="col '20';rows '15'">
	  blah blah
	</textarea>

deviendra: ::

	<textarea col="20" rows="15">
	  blah blah
	</textarea>

``condition``
`````````````

``condition`` permet d'inclure l'élément auquel il se rapporte uniquement
quand la condition est vérifiée.

Exemple: ::

	<p tal:condition="not userToken">
	  Vous n'êtes pas identifié.
	</p>

Ne provoquera l'affichage du paragraphe et de son contenu que quand la
variable ``userToken`` ne sera pas définie.
content

``content`` permet de remplacer le contenu d'un élément par le résultat de
l'expression.

Exemple: ::

	<h1 tal:content="currentObject.label">Titre</h1>

Pourra devenir (suivant la valeur de currentObject.label: ::

	<h1>Liste des nouveautés</h1>

``define``
``````````

``define`` permet de définir des variables.

Exemple : ::

	<div tal:define="titre currentObject.label">
	  <h1 tal:content="titre">Titre</h1>
	</div>

``omit-tag``
````````````

``omit-tag`` permet de supprimer la balise avec laquelle il est associé
une fois les autres directives suivies.

Exemple : ::

	<div tal:omit-tag="" comment="cette balise n'apparaîtra nulle part">
	  <h1>Bonjour</h1>
	</div>

provoquera simplement ::

	<h1>Bonjour</h1>

``on-error``
````````````

``on-error`` permet d'intercepter des erreurs qui se produiraient dans
d'autres directives. Par exemple : ::

	<div tal:on-error="'Une erreur est survenue.'">
	  <p>Un peu de texte. </p>
	  <p tal:content="42/0">sd</p>
	</div>

La division 42/0 va provoquer une erreur et le texte
Une erreur est survenue sera donc affiché.

``repeat``
``````````

``repeat`` permet de répéter un certain nombre de fois un élément. Il
définit une variable qui contiendra au fur et à mesure des itérations
toutes les valeurs de la liste donnée en expression.

Exemple : ::

	<ul>
	  <li tal:repeat="author currentObject.authorsSet">
	     <span tal:replace="author.name">Pol</span> est un des auteurs.
	  </li>
	</ul>

Variable ``repeat`` supplémentaire
``````````````````````````````````

Dans une boucle ``repeat``, une variable supplémentaire existe et a pour
nom ``repeat-`` suivi du nom de la variable d'itération (dans l'exemple
précédent, ``author`` donc ``repeat_author``).

Cette variable contient les attributs :

==========  ============================================
Attributs
==========  ============================================
``index``   index de l'élément dans la liste (début à 0)
``number``  idem (début à 1)
``even``    vrai si l'index est pair
``odd``     vrai si l'index est impair
``start``   vrai pour le premier élément
``end``     vrai pour le dernier élément
``length``  longueur de la liste
``letter``  index sous forme de lettre (a, b, c...)
``Letter``  la même chose en majuscule
``roman``   index sous forme de chiffres romains
``Roman``   la même chose en majuscule
==========  ============================================

Cette variable comporte également deux méthodes, ``first`` et ``last`` qui
peuvent être utilisées dans le cas d'éléments triés pour repérer le
début ou la fin d'un groupe.

Exemple : ::

	<ul>
	  <li tal:repeat="author currentObject.authorsSet">
	     <span tal:replace="repeat_author.roman">i</span>.
	     <span tal:replace="author.name">Pol</span>
	  </li>
	</ul>

provoquera ::

	<ul>
	  <li>i. Emmanuel</li>
	  <li>ii. Frederic</li>
	  <li>iii. Odile</li>
	  <li>iv. Benjamin</li>
	</ul>

``replace``
```````````

``replace`` permet de remplacer une balise et son contenu par le résultat
de l'expression.

Exemple : ::

	<p>
	  Vous êtes sur l'article <span
	  tal:replace="currentObject.label">test</span>.
	</p>


