Le gabarit du bloc est un fragment d'XHTML, enrichi de certains attributs XML, d'espace de nom tal ou change, permettant des traitements dynamiques comme l'itération sur les tableaux de données, l'affichage conditionnel de sous parties, …

Cette page permet de démarrer avec PHPTal pour RBS Change mais ne se substitue pas à la documentation en ligne de PHPTal. Voyez par ailleurs les extensions PHPTal Change.

Les données transmises au gabarit sont, par ordre de priorité :

1. Les attributs de requête
2. Les attributs de session
3. Les paramètres de requête du bloc

N.B. : cet ordre est important du point de vue sécurité : si l'utilisateur transmet dans la requête un certain paramètre et le bloc définit un attribut du même nom, le gabarit utilisera la valeur du bloc.

Par ailleurs, d'autres données sont systématiquement transmises :

• Une référence à la page en cours sous le nom “website_page” (Cf. classe website_Page)
• Une référence à la configuration du bloc , sous le nom “configuration”

Pour afficher une donnée transmise au gabarit sous le nom varName, on utilise la chaîne ${varName}.

Si la donnée peut contenir des caractères HTML, on utilise le préfixe escape qui permet “d'échapper” la valeur : ${escape: varName}.

Exemple : affichage du paramètre de requête myParam et de l'attribut de requête myAttr. Dans la requête HTTP, l'utilisateur transmet le paramètre myParam : ?mymoduleParam[myParam]=<script>alert('Some ugly string');</script> : on ne maîtrise pas la valeur transmise : il faudra l'échapper.

Dans l'action, on transmet “html characters: <span>&”, sous les noms myAttr (échappé avec f_util_HtmlUtils::textToHtml()) et myAttrUnescaped (non échappé) :

class mymodule_BlockMymoduleAction extends website_BlockAction
{
  public function execute($request, $response)
  {
    $string = "html characters: <span>&";
    $request->setAttribtue("myAttr", f_util_HtmlUtils::textToHtml($string));
    $request->setAttribtue("myAttrUnescaped", $string);
  }
}

Dans le gabarit, on échappe myParam et myAttrUnescaped. myAttr peut lui être affiché tel quel :

<p>
  You transmited "myParam": <strong>${escape: myParam}</strong><br/>.
  The bloc transmited <strong>${myAttr}</strong>, which is the same as <strong>${escape: myAttrUnescaped}
 
</strong>
</p>

Le gabarit affichera alors :

<p>
  You transmited "myParam": <strong>&lt;script&gt;alert('Some ugly string');&lt;/script&gt;</strong><br/>.
  The bloc transmited "myAttr": <strong>html characters: &lt;span&gt;&amp;</strong>, which is the same as 
 
<strong>html characters: &lt;span&gt;&amp;</strong>
</p>

Pour afficher la valeur de la clef myKey d'un tableau transmis sous le nom myArray, on utilise la chaîne ${myArray/myKey}, que la clef soit numérique ou une chaîne de caractère. Si la valeur du tableau peut contenir de l'HTML, on préfixe avec escape: : ${escape: myArray/myKey}.

Exemple : avec myArray valant array(“someKey” ⇒ “someValue”, “otherKey” ⇒ “otherValue”), affichage de la valeur de la clef someKey :

<p>
  "myArray" contains key "someKey", with value : <strong>${myArray/someKey}</strong>
</p>

Ce qui donnera l'HTML suivant :

<p>
  "myArray" contains key "someKey", with value : <strong>otherValue</strong>
</p>

Pour afficher la valeur retournée par la méthode mymethod() d'un objet transmis sous le nom myObject, on utilise la chaîne ${myObject/myMethod}. Si la méthode ne gère pas elle même l'échappement des caractères HTML, on préfixe avec escape: : ${escape: myObject/myMethod}.

Exemple : invocation de la méthode count() sur l'objet myObject :

<p>
  "$myObject->count()" return value is <strong>${myObject/count}</strong>
</p>

Ce qui donnera l'HTML suivant (en supposant que count() retourne “3”) :

<p>
  "$myObject->count()" return value is <strong>3</strong>
</p>

N.B. : cette syntaxe ne permet volontairement pas le passage d'arguments. Dans la mesure du possible, mettez à disposition du gabarit des méthodes simples, sans argument, afin de ne pas alourdir la logique du gabarit. Si cela est nécessaire, utilisez le préfixe ''php:'' de PHPTal.

A chaque propriété de type “Chaîne” des documents RBS Change (String, LongString, XHTMLFragment) correspond une méthode dédiée à l'utilisation dans un gabarit : à la propriété <propName> correspond la méthode get<PropName>AsHtml(). Cette méthode gère elle même l'échappement des caractères HTML : pas besoin donc d'utiliser le préfixe escape.

Exemple : affichage du libellé d'un document transmis sous le nom “mydoc”

<p>${mydoc/getLabelAsHtml}</p>

L'équivalent du foreach de PHP est l'attribut tal:repeat que l'on le place sur l'élément à répéter, en lui indiquant le nom de la variable d'itération puis le nom du tableau à utiliser.

Exemple : construction d'une liste non ordonnée à partir du tableau de documents RBS Change documents :

<ul>
  <li tal:repeat="doc documents">
    ${doc/getLabelAsHtml}
  </li>
</ul>

Plus d'informations sur tal:repeat, dans la documentation en ligne de PHPTal.

L'attribut tal:condition permet l'affichage conditionnel d'une balise et de son contenu en fonction de la valeur de l'attribut. La négation de la valeur transmise se fait avec le préfixe not:.

Exemple : génération d'une liste si le tableau de documents RBS Change documents est transmis, d'un paragraphe sinon.

<ul tal:condition="documents">
  <li tal:repeat="doc documents">
    ${doc/getLabelAsHtml}
  </li>
</ul>
<p tal:condition="not: documents">
  No document were transmited
</p>

Un usage courant de tal:condition est l'affichage conditionné par une valeur de configuration du bloc.

Exemple : affichage d'une liste si le paramètre booléen de configuration showList le permet :

<ul tal:condition="configuration/getShowList">
  ...
</ul>

Plus d'informations sur tal:condition dans la documentation en ligne de PHPTal.