Met en cache le résultat de l'exécution du contenu de la balise.

La clef de cache est composée à partir de la langue, du user agent courant et des autres paramètres placés sur la balise.

<tal:block change:cache="" name="mymodule_mytemplate_parta" deps="${document/getId},time:3600" someKeyPart="${document/getId}">
  <!-- Some "heavy" content that needs computation here. Will be invalidated when document is updated or after 3600 seconds -->
</tal:block>

Permet de charger un fichier ou des données JavaScript.

Le code suivant charge le fichier 'modules/media/lib/js/jquery-lightbox.js' dans le head de la page :

<script change:javascript="head 'modules.media.lib.js.jquery-lightbox'" />

Attention : le point étant utilisé comme séparateur de dossier, il ne faut pas en utiliser dans les noms des fichiers js.

En supposant image/getDimensions retourne le tableau associatif array('width' ⇒ 640, 'height' ⇒ 480), le code suivant :

<script change:javascript="imgDimensions image/getDimensions" />

Génère le code suivant :

<script type="text/javascript">
var imgDimensions = {"width":640,"height":480};
</script>

change:paginator permet la pagination d'une liste de documents.

Côté PHP : instanciation d'un objet paginator_Paginator à partir d'un tableau de documents

// données
$documents = $someService->findDocuments(...);
$docCountPerPage = 2;
$pageIndex = $request->getParameter(paginator_Paginator::PAGEINDEX_PARAMETER_NAME);
 
// pagination des données puis transmission à la vue
$paginator = new paginator_Paginator("monmodule", $pageIndex, $documents, $docCountPerPage);
$request->setAttribute("documents", $paginator);

Côté gabarit : itération sur l'objet paginator_Paginator et utilisation de change:paginator'

<ol tal:condition="documents">
  <li tal:repeat="document documents">
    <a change:link="document document" tal:content="document/getLabelAsHtml" />
  </li>
</ol>
 
<div change:paginator="documents" />

Donnera quelque chose du type (en assumant que les deux premiers documents aient comme libellé “un document1” et “un document2”) :

Le tableau suivant présente les paramètres supportés par change:paginator :

N.B. : même si charger des documents n'implique pas directement le chargement de l'ensemble des propriétés des documents, le traitement de très gros volumes de données pourra se faire avec des techniques plus élaborées utilisant la pagination côté base de données ou des projections. L'objet paginator_Paginator s'initialise alors différemment.

change:permission permet de conditionner l'affichage de parties de gabarit selon qu'une permission est donnée ou non à l'utilisateur courant (utilisateur front ou back).

<tal:block change:permission="perm website.Display.Page ; nodeId somePage/getId">
  You have access to '${somePage/getLabelAsHtml}'
</tal:block>
<tal:block change:permission="notperm website.Display.Page ; nodeId somePage/getId">
  You do not have access to '${somePage/getLabelAsHtml}'
</tal:block>

Les attributs supportés par change:permission sont résumés dans le tableau suivant :

change:loadhandler permet l'exécution d'un ViewLoadHandler depuis un gabarit.

Exemple : exécution de generic_DocumentLoadHandler, paramétré avec “mydoc, mydocId, mymodule_persistentdocument_mydoc”

<tal:block change:loadhandler="generic_DocumentLoadHandler" args="mydoc, mydocId, mymodule_persistentdocument_mydoc" />

Pour échapper une propriété d'un document de type texte, il suffit d'appeler la méthode get<PropName>AsHtml().

Les autres valeurs de type texte peuvent être échappées depuis le bloc, en appelant f_util_HtmlUtils::textToHtml() ou depuis le gabarit en utilisant le modifier PHPTal escape :

<span>${escape: myParam}</span>
<span tal:content="escape: myParam" />

change:gauge gère l'affichage d'une note sous la forme d'un score représenté par une image.

Le paramètre évalué value correspond à la note, exprimé par un flottant entre 0 et 1. Le score est un entier de 0 à maxScore (par défaut 5), calculé par la formule round(maxScore * value).

Le tableau suivant présente les paramètre supportés par change:gauge :

Exemple : affichage de la note “0.23”, sur une échelle de 0 à 5.

<img change:gauge="value 0.23" />

• Le score (round(5 * 0.23)) vaudra “1”
• L'image le représentant sera : “front/gauge-search-5-1.png”
• La classe de l'image sera : “solrsearch-results-1”
• L'alternative de l'image sera l'évaluation de la clef de localisation “modules.media.frontoffice.Gauge-search-5-1”

Ce qui donnera le résultat suivant :

<img class="solrsearch-results-1" title="Pertinence 1 sur 5" alt="Pertinence 1 sur 5" src="http://.../media/frontoffice/gauge-search-5-1.png">

Cette extension se place sur les balises h1 à h6 et ajoute la classe CSS adaptée au niveau du titre.

Ce mot-clé permet de générer des classes alternées “even” et “odd” pour des items de liste ou des lignes de tableaux. Il prend en paramètre le nom d'une variable qui contiendra le compteur permettant de gérer l'alternance des classes.

Exemple : le code suivant :

<ul>
    <li tal:repeat="..." class="${alternateclass:itemIndex}">...</li>
</ul>

Donnera :

<ul>
    <li class="odd">...</li>
    <li class="even">...</li>
    <li class="odd">...</li>
    ...
</ul>

Lorsqu'on utilise du display: inline-block; pour de la mise en page, en est rapidement confronté à un problème d'espaces parasites entre les éléments. Il existe plusieurs solutions en CSS mais relevant principalement de la bidouille et en tant que tel, comportant en général des effets de bord. La solution la plus sûre reste de ne pas avoir d'espaces entre les balises. Cependant cela implique de figer la mise en page et comporte le risque qu'une autre personne travaillant sur le code le reformate différemment sans soupçonner les conséquences.

Cette extension a pour but résoudre le problème de manière plus sûre et sans contraindre la mise en page du template puisqu'elle se contente de supprimer au rendu les espaces entre les nœuds enfants du nœud sur lequel elle est appliquée.

Exemples :

<h2 change:h="">Cas simple</h2>

<h3 change:h="">Sans change:spaceless</h3>
<div class="normal">
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
</div>

<h3 change:h="">Avec change:spaceless</h3>
<div class="normal" change:spaceless="">
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
</div>

<h2 change:h="">Cas plus complexes</h2>
<h3 change:h="">Imbrication : n'a d'effet que sur les éléments enfants et pas les descendants</h3>
<div class="normal" change:spaceless="">
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">
		<div style="background: green; display: inline-block; width: 25%;">Test</div>
		<div style="background: green; display: inline-block; width: 25%;">Test</div>
		<div style="background: green; display: inline-block; width: 25%;">Test</div>
		<div style="background: green; display: inline-block; width: 25%;">Test</div>
	</div>
	<div style="background: red; display: inline-block; width: 25%;" change:spaceless="">
		<div style="background: green; display: inline-block; width: 25%;">Test</div>
		<div style="background: green; display: inline-block; width: 25%;">Test</div>
		<div style="background: green; display: inline-block; width: 25%;">Test</div>
		<div style="background: green; display: inline-block; width: 25%;">Test</div>
	</div>
</div>

<h3 change:h="">Les noeuds textes non-vides sont préservés tels quels</h3>
<div class="normal" change:spaceless="">
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div> aaa
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
</div>

<h3 change:h="">Quand un enfant est un tal:block</h3>
<div class="normal" change:spaceless="">
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<tal:block>
		<div style="background: red; display: inline-block; width: 25%;">tal:block sans spaceless</div>
	</tal:block>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
</div>
<div class="normal" change:spaceless="">
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<tal:block change:spaceless="">
		<div style="background: red; display: inline-block; width: 25%;">tal:block avec spaceless</div>
	</tal:block>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
	<div style="background: red; display: inline-block; width: 25%;">Test</div>
</div>

Les extensions change:tabs et change:tab permettent la création d'onglets, en utilisant le plugin JavaScript jquery-ui-tabs :

<div change:tabs="id myTabs">
  <!-- hard coded title cases -->
  <div change:tab="name tab1; label Tab1 title">
     ... first tab content
  </div>
  <div change:tab="name tab2" label="Tab2 title">
     ... second tab content
  </div>
  <!-- dynamic title case -->
  <div change:tab="name tab3" label="${title3}"><!-- where title3 is set to "Tab3 title by the block" -->
    ... third tab content
  </div>
  <!-- localized title cases -->
  <div change:tab="name tab4; labeli18n m.mymodule...tab4-title">
    ... fourth tab content
  </div>
  <div change:tab="name tab5" labeli18n="m.mymodule...tab5-title">
    ... fifth tab content
  </div>
</div>

Le code XHTML généré correspond, en structure, à :

<div id="myTabs">
  <div id="myTabs_tab1">
    <h3>Tab1 title</h3>
     ... first tab content
  </div>
  <div id="myTabs_tab2">
    <h3>Tab2 title</h3>
    ... second tab content
  </div>
  <div id="myTabs_tab3">
    <h3>Tab3 title</h3>
    ... third tab content
  </div>
  <div id="myTabs_tab4">
    <h3>Tab4 title</h3>
    ... fourth tab content
  </div>
  <div id="myTabs_tab5">
    <h3>Tab5 title</h3>
    ... fifth tab content
  </div>
</div>

Par défaut, change:tab reprend le libellé en tant que titre de niveau trois. Pour désactiver ce comportement, renseignez le paramètre doTitle à false :

<div change:tabs="id myTabs">
  <div change:tab="name tab1; labeli18n m.mymodule...tab3-title; doTitle false">
    ... third tab content
  </div>
</div>

<div change:tabs="id myTabs">
  <div change:tab="name tab1; label &modules.mymodule...Tab1-title;">
     ... first tab content
  </div>
</div>

Cette syntaxe est toujours supportée en version 3.5 pour compatibilité mais est dépréciée au profit du paramètre labeli18n évoqué plus haut.