Les marqueurs de contrôle

Un marqueur de contrôle (control markup en Anglais) est une instruction qui demande au WdPublisher de faire quelque chose. Par exemple pour récupérer l'article « Utiliser WdPublisher » et afficher son contenu on utilisera le marqueur de contrôle wdp:article comme ceci :

<wdp:article select="WdPublisher : Les marqueurs de contrôle">
<h1>{article.contents.entities()}</h1>
</wdp:article>

ce qui donnera après publication :

<h1>WdPublisher : Les marqueurs de contrôle</h1>

Il existe deux types de marqueurs de contrôle : les marqueurs de contrôle natifs et les marqueurs de contrôle de module.

Les marqueurs de contrôle natifs sont définis par WdPbulisher. Leur rôle est essentiellement celui de contrôler le processus de publication : afficher un bloc de texte selon une condition, publier un bloc de texte pour chaque entrée d'un tableau associatif… Dans ce billets nous ne verrons que les marqueurs de contrôle natif, ceux définis par les modules feront l'objet de billets particuliers.

Répétition

<ul>
<wdp:foreach in="articles">
<li>Titre de l'article : {this.title.entities()}</li>
</wdp:foreach>
</ul>

Le gabarit contenu par le marqueur de contrôle wdp:foreach est répété par chaque entrée du tableau associatif spécifié par l'attribut in. Par défaut, l'entrée lue depuis le tableau associatif est placée dans la variable this. Vous pouvez modifier le nom de la variable par celui que vous souhaitez en utilisant l'attribut as. Par exemple, as="article".

Imaginons que la variable article contienne trois articles, après publication, nous pourrions avoir le résultat suivant :

<ul>
<li>The result type should be either...</li>
<li>Le vide qui lie</li>
<li>Portrait d'Aurore</li>
</ul>

Traitement conditionnel

Traitement conditionnel simple

<wdp:if test = expression>
  <!-- Contenu: gabarit -->
</wdp:if>

Le marqueur de contrôle wdp:if possède un attribut test, qui spécifie une expression. Si le résultat de l'évaluation de cette expression est différent de zéro, le gabarit contenu par le marqueur de contrôle est traité. Dans l'exemple suivant, le texte L'article est commenté est affiché si, et seulement si, des commentaires sont associés à l'article.

<wdp:article select="WdPublisher : Les marqueurs de contrôle">
<wdp:comments>
<wdp:if test="{comments.count()}">
L'article est commenté
</wdp:if>
</wdp:comments>
</wdp:article>

Le marqueur de contrôle wdp:if ne propose pas d'alternative à une évaluation vraie. Le gabarit contenu par le marqueur de contrôle disparait si l'évaluation est fausse (égale à zéro). Si l'on souhaite afficher un message alternatif, il convient d'utiliser le traitement conditionnel du marqueur de contrôle wdp:choose.

Traitement conditionnel avec alternatives

<wdp:choose>
    <!-- Contenu: (wdp:when+, wdp:otherwise?) -->
</wdp:choose>

<wdp:when test = expression>
    <!-- Contenu: gabarit -->
</wdp:when>

<wdp:otherwise>
    <!-- Contenu: gabarit -->
</wdp:otherwise>

Le marqueur de contrôle wdp:choose choisi une solution parmi une liste d'alternatives. Il consiste en une séquence de marqueurs de contrôle wdp:when suivis par un marqueur de contrôle optionnel wdp:otherwise. Chaque marqueur de contrôle wdp:when possède un attribut test qui spécifié une expression à évaluer. Le contenu des marqueurs de contrôle wdp:whenet wdp:otherwise est un gabarit.

Lorsqu'un marqueur de contrôle wdp:when est traité, chaque marqueur de contrôle wdp:when est testé à son tour en évaluant leur expression de test. Le contenu du premier marqueur de contrôle wdp:when dont l'évaluation est vrai sera traité. Si aucune des évaluations n'est vraie, le contenu du marqueur de contrôle wdp:ohterwise sera traité. S'il n'y a pas de marqueur de contrôle wdp:otherwise et qu'aucune évaluation n'est vraie, rien n'est affiché.

L'exemple suivant affiche un message différent selon qu'il n'y a pas de commentaire, qu'il y a un commentaire ou plusieurs.

<wdp:article select="WdPublisher : Les marqueurs de contrôle">
<wdp:comments>
<wdp:choose>
<wdp:when test="{comments.count()} == 0">
Il n'y a pas de commentaires
</wdp:when>
<wdp:when test="{comments.count()} == 1">
1 commentaire
</wdp:when>
<wdp:otherwise>
{comments.count()} commentaires
</wdp:otherwise>
</wdp:choose>
</wdp:comments>
</wdp:article>

Notre exemple utilise de nombreuses fois la séquence {comments.count()} qui compte à chaque fois le nombre d'entrées dans le tableau associatif comments. Il serait donc pratique d'ajouter une variable au contexte qui aurait pour valeur le résultat de notre évaluation.

Variables

<wdp:variable  name = variable_name  select = expression>
    <!-- Contenu: gabarit -->
</wdp:variable>

Le marqueur de contrôleur wdp:variable permet d'ajouter une variable au contexte du marqueur de contrôle. La valeur de la variable est le résultat de l'expression spécifiée par l'attribut select. Reprenons l'exemple précédent en utilisant cette fois wdp:variable :

<wdp:article select="WdPublisher : Les marqueurs de contrôle">
<wdp:comments>
<wdp:variable name="count" select="{comments.count()}">
<wdp:choose>
<wdp:when test="{count} == 0">
Il n'y a pas de commentaires
</wdp:when>
<wdp:when test="{count} == 1">
1 commentaire
</wdp:when>
<wdp:otherwise>
{count} commentaires
</wdp:otherwise>
</wdp:choose>
</wdp:variable>
</wdp:comments>
</wdp:article>

Gabarits

Les gabarits sont normalement gérés depuis WdPublisher, nous verrons plus tard qu'il est possible de définir de nouveaux gabarits à l'intérieur d'autres gabarits. Pour le moment nous allons voir comment faire appel à un

Définir un gabarit

<wdp:template name = name>
    <!-- Contenu : gabarit -->
</wdp:template>

Il est possible de créer des gabarits en utilisant le marqueur de contrôle wdp:template. Cela peut s'avérer très utile puisque la récursion des marqueurs de contrôle est interdite. Par exemple, l'utilisation du marqueur de contrôle wdp:template nous permet de faire fonctionner le code fautif suivant :

<wdp:articles limit="5">
<foreach>
<h1>{this.title.entities()}</h1>
    <wdp:comments>
    <foreach>
        <h2>{this.author}</h2>
        <p>{this.contents.entities()}</p>
    </foreach>
    </wdp:comments>
</foreach>
</wdp:articles>

En le modifiant comme cela :

<wdp:template name="print-comments">
    <wdp:comments>
    <foreach>
        <h2>{this.author}</h2>
        <p>{this.contents.entities()}</p>
    </foreach>
    </wdp:comments>
</wdp:template>

<wdp:articles limit="5">
<foreach>
<h1>{this.title.entities()}</h1>
<wdp:call-template name="print-comments" />
</foreach>
</wdp:articles>

Appeler un gabarit

<wdp:call-template name = name />

Le marqueur de contrôle wdp:call-template nous permet d'appeler un gabarit défini depuis le WdPublisher ou par le marqueur de contrôle wdp:template. Pour cela il suffit simplement de fournir son nom.

Laisser un commentaire

Pas de commentaire