Extensions PHPTal

ATTENTION :
Le moteur de rendu PHPTal utilisé par RBSChange demande une syntaxe XML valide, ainsi :

TOUTE BALISE OUVERTE DOIT ÊTRE FERMÉE, ainsi des balises telles que br doivent être écrites <br/> et non <br> (même si HTML5 l'autorise)
Tout attribut doit avoir sa valeur entre guillemets

Par ailleurs si vous utilisez des macros PHPTal, le nom de votre macro ne doit pas comporter de caractère '-'.

Concepts

PHPTal signifie Template Attribute Language for PHP : c'est un moteur de template basé sur les attributs. Les instructions dynamiques prennent la forme d'attributs XML d'un espace de nom particulier (tal:* pour la plupart). RBS Change fournit un certain nombre d'extensions sous l'espace de nom change.

Le gabarit suivant fait usage des extensions PHPTal tal:repeat et tal:content qui permettent respectivement l'itération sur un tableau et le remplacement du contenu d'une balise par la valeur d'une variable ou d'un résultat de méthode :

<ul>
  <li tal:repeat="doc docs" tal:content="doc/getLabelAsHtml">
    This will be replaced by $doc->getLabelAsHtml() result
  </li>
</ul>

Les extensions PHPTal, comme des fonctions, acceptent des paramètres qui déterminent leur fonctionnement. Dans l'exemple précédent, il a été demandé à tal:repeat d'itérer sur le tableau “docs”, avec pour variable d'itération “doc”. La variable “doc” a ensuite été utilisée comme paramètre de tal:content. La notation “doc/getLabelAsHtml” permet deux choses :

Si “doc” est un objet, doc/getLabelAsHtml correspond au résultat de la méthode getLabelAsHtml() sur l'objet “doc”,
Si “doc” est un tableau, “getLabelAsHtml” est la clef de la valeur recherchée dans le tableau “doc”.

Pour plus d'informations sur PHPTal et son utilisation, consultez la documentation de PHPTal.

Paramètres évalués

Dans la suite, un paramètre est dit évalué si la valeur transmise dans le gabarit est une chaine évaluée par le moteur PHPTal.

Supposons l'extension fictive change:uneextension acceptant deux paramètres :

“nonevaluated”, non évalué,
“evaluated”, évalué

Supposons également que dans le bloc on définisse “level” à “4” :

$request->setAttribute('level', '4');

Dans l'exemple suivant, “nonevaluated” vaudra alors “level” et “evaluated” vaudra '4' :

<div change:uneextension="nonevaluated level; evaluated level" />

Pour transmettre une valeur fixe, entourez la valeur de guillements. Dans l'exemple suivant, “evaluated” vaudra 'level' :

<div change:uneextension="nonevaluated level; evaluated 'level'" />

Dans les extensions ci-dessous, certains paramètres sont évalués, d'autres non.

Types d'extensions

Certaines extensions remplacent totalement l'élément XML sur lequel elles sont utilisées, d'autres ne définissent que le contenu. On parle respectivement d'extension de type replace ou surround.

Déclarer une nouvelle extension

change compile-phptal scanne tous les modules, y repère les classes nommées <ModuleName>_PHPTAL_CHANGE et en exécute la méthode statique <ModuleName>_PHPTAL_CHANGE::addAttributes(), permettant ainsi au module d'enregistrer les extensions qu'il fournit.

Exemple: extrait de la classe website_PHPTAL_CHANGE du module website

class website_PHPTAL_CHANGE
{
	/**
	 * @param PHPTAL_Namespace_CHANGE $namespaceCHANGE
	 */
	public static function addAttributes($namespaceCHANGE)
	{
		$namespaceCHANGE->addAttribute(new PHPTAL_NamespaceAttributeReplace('block', 10));
		$namespaceCHANGE->addAttribute(new PHPTAL_NamespaceAttributeSurround('cache', 10));
		$namespaceCHANGE->addAttribute(new PHPTAL_NamespaceAttributeSurround('currentlink', 10));
		$namespaceCHANGE->addAttribute(new PHPTAL_NamespaceAttributeSurround('currentpagelink', 10));
 
		// Forms
		$namespaceCHANGE->addAttribute(new PHPTAL_NamespaceAttributeReplace('submit', 10));
		$namespaceCHANGE->addAttribute(new PHPTAL_NamespaceAttributeReplace('textinput', 10));
		$namespaceCHANGE->addAttribute(new PHPTAL_NamespaceAttributeReplace('hiddeninput', 10));
		$namespaceCHANGE->addAttribute(new PHPTAL_NamespaceAttributeReplace('dateinput', 10));
		$namespaceCHANGE->addAttribute(new PHPTAL_NamespaceAttributeReplace('booleaninput', 10));
                // ...
}