Quelqu’un est venu hier soir sur l’IRC de SPIP pour demander s’il était possible d’écrire une boucle brèves qui cherche (BREVES) {titre LIKE %#TITRE%} OU {texte LIKE %#TITRE%}, le #TITRE étant pris dans une boucle parente (une boucle ARTICLES il me semble, mais cela a peu d’importance...)

Une solution à ce problème est de créer son propre critère, puisque SPIP fait systématiquement des ET entre ses critères (ils sont cumulatifs).

J’annonce tout de suite que créer un critère peut être simple, mais peut aussi être très compliqué ! Par chance la demande ici est simple, et c’est pourquoi elle offre une jolie base pour un exemple.

Nous allons donc imaginer un critère nommé « va_chercher » qui prendra un argument. Son utilisation sera : {va_chercher toto} ou encore {va_chercher #TITRE}

Comme toute nouvelle définition (balise, filtre, critère, boucle), on mettra le code de notre critère dans un fichier de fonctions, par exemple dans squelettes/mes_fonctions.php.

Déclaration de base du critère

Voici une déclaration de la fonction PHP de notre critère. Ici il n’y a que la déclaration et aucune action encore.

Un critère arrive avec trois arguments :

• $idb est le nom de la boucle
• &$boucles est l’arbre de construction de toutes les boucles du squelette en question. $boucle, calculé ensuite, est celui de la boucle que le critère va modifier directement. Le & est important, il signifie en PHP que la variable est passée « par référence », autrement dit que toute modification de cette variable à l’intérieur de la fonction du critère affecte la variable à l’extérieur de l’appel. On peut aussi dire que le & permet de ne pas avoir une copie du contenu de la variable demandée, mais le contenu lui-même.
• $crit est l’arbre de construction du critère, il permet de savoir ce que contient le critère en question (nom, opérateur, négation, arguments...)

Effectuer une action

Nous allons voir comment ajouter un critère de sélection dans la boucle grâce à ce critère. Nous allons ajouter un élément dans le tableau $boucle->where.

Notons déjà, que tous les éléments dans ce tableau where sont enchaînés par des opérateurs AND. Cependant, et c’est ce que nous verrons plus loin, un élément de ce tableau peut contenir des sous-éléments, et pour ceux-là, nous pouvons décrire précisément le type de liaison qui les affecte parmi une panoplie d’opérateurs à disposition (AND, OR, NOT, LIKE, REGEXP, >, <, =, >=, <= et je dois en oublier)

Commençons simplement. D’une part, le $table calculé contient le nom de la table SQL concernant notre boucle. Le tableau $c contient trois éléments : Opérateur, Valeur1, Valeur2. Cela sera traduit ensuite par « Valeur1 Operateur Valeur2 » soit ici : « titre = ’’ ». En fonction des opérateurs, il n’y a pas obligatoirement trois éléments dans le tableau ; ainsi NOT ne compare qu’à une valeur. À la fin, le tableau $c est ajouté à where.

Comme vous le voyez, le contenu du tableau $c possède une drôle d’écriture à base de doubles guillemets tel que "'='". Il faut comprendre, qu’on est à un niveau d’abstraction un peu au dessus de celui des squelettes. On fait écrire, dans le critère, le code PHP que SPIP produira pour calculer la boucle.

On comprendra donc que ces deux lignes ne donnent pas le même résultat

Cela écrira en PHP à peu près :

Puis à l’execution, la rèquete SQL :

La deuxième ligne créerait une erreur MySQL puisque sql_quote('toto') est une fonction PHP pour SPIP et non une fonction d’un gestionnaire de requête SQL.

Cependant la seconde écriture peut être souhaitée si on veut utiliser une fonction SQL, tel que "MIN" ou "MAX", ou je ne sais quoi... Il faut donc bien comprendre ce qui se passe et ce que l’on souhaite obtenir :)

Ajouter la négation

La négation, c’est la présence dans le critère de NOT, représenté par le point d’exclamation (!) comme dans : {!va_chercher toto}.

Prendre en compte la négation consiste —en général [2]— à demander l’inverse du résultat attendu, c’est à dire à encapsuler tout notre tableau $c dans un NOT avant de le donner à manger au where. Pour savoir si notre critère a une négation, on interroge $crit->not.

Comme vous le voyez, $c, lorsqu’il y a une condition NOT devient un tableau d’une profondeur plus importante. C’est grâce à ce principe que nous pourrons faire un OU logique plus loin.

Récupérer un paramètre de critère

Nous allons rechercher le paramètre ’toto’ ou ’#TITRE’ passé à notre critère via {va_chercher toto} ou {va_chercher #TITRE}. Pour cela, nous allons tester la présence de $crit->param[ n ] ou le nombre indique la présence du paramètre n (en comptant de 0), et utiliser la fonction adaptée calculer_liste.

S’il n’y a pas de paramètre 0, nous pourrions mettre une valeur par défaut, mais nous dirons ici que c’est une erreur de squelettes pour forcer à avoir ce paramètre dans le critère. On aurait pu, aussi, en absence de paramètre récupérer automatiquement un paramètre de l’environnement ou le #TITRE de la boucle parente, mais cela n’entre pas dans l’objet de ce tutoriel. Sachez simplement que c’est possible, tout comme réaliser des jointures ou faire des calculs complexes. Vous pouvez en exemple regarder les critères de certains plugins (agenda, organiseur, tradsync, ... ) et de SPIP (ecrire/public/criteres.php)

Ajouter la condition OR

Le dernier élément, le plus simple finalement maintenant que tout est compris, est d’ajouter l’opérateur OR entre deux sélections. Nous l’obtenons avec :

Je n’en dis pas plus. Voici le code complet :