SPIP

La boucle DATA

BoOz — 2018-03-06T21:51:46Z

La boucle DATA est capable d'itérer sur un jeu de données d'un certain format.

Sa syntaxe est la suivante :

 [(#CLE)] - [(#VALEUR|print)]

Le critère {source format, données} définit les données sur lesquelles la boucle va itérer.

— Les données peuvent être de plusieurs natures, en fonction du format :
- un tableau PHP
- le chemin d'un fichier ou d'un dossier sur le disque dur
- l'URL d'un fichier ou d'un webservice (API)
- ou encore, une chaîne quelconque que le format saura transformer en tableau de données, ex : "select * from flickr.photos.search where text='spip'"

Les critères suivants permettent de filtrer les tableaux affichés par les boucles DATA.
- {valeur=x} ; les opérateurs disponibles sont =, >, <, >=, <=, ==(expression rationnelle) et LIKE.
- {cle=x} : idem, pour tester la clé
- {par xx} et {!par xx}
- {a,b} et {pagination ...}
- {fusion /x/y}
- {datapath chemin/vers/ma/donnee}

Un chapitre complet détaille l'usage des boucles DATA, propose des exemples d'usage et présente la manière de déclarer de nouvelles boucles DATA.

Lire la suite : Les itérateurs de SPIP - la boucle (DATA).
Voir Exemples de `BOUCLE(DATA)`

{critère IN valeur1, valeur2[, valeur3,..., valeurN]}

BoOz — 2009-08-24T15:02:10Z

{... IN ...} limite l'affichage aux résultats ayant un critère appartenant à un ensemble fini.

Sommaire

{xxxx IN a,b,c,d} limite l'affichage aux résultats ayant le critère xxxx égal à a, b, c ou d.

Les résultats sont triés dans l'ordre indiqué (sauf demande explicite d'un autre critère de tri). Il est aussi possible de sélectionner des chaînes de caractères, par exemple avec {titre IN 'Chine', 'Japon'}

Passer en argument un tableau

C'est possible et c'est aussi le seul moyen de passer dynamiquement une liste de valeur avec le critère IN.

Exemple

#SET{mes_rubriques, #LISTE{1,2,3}}  #TITRE

Il peut s'agir d'un tableau défini par les balises

ou bien d'un tableau provenant d'une balise #GET ou #ENV**{mon_post}.

Si #ENV{mon_post} est un tableau (venant par exemple de saisies de formulaire dont l'attribut name se termine par []), et si les filtres d'analyse ont été désactivés en suffixant cette balise par une double étoile, alors chaque élément du tableau sera considéré comme argument de IN, SPIP appliquant les filtres de sécurité sur chacun d'eux [1].

Le squelette standard fourni dans plugins-dist/forum/formulaires/inc-forum_previsu.html fournit un exemple d'utilisation avec une boucle MOTS ayant le critère {id_mot IN #ENV**{ajouter_mot}} :
cette boucle sélectionne seulement les mots-clés appartenant à un ensemble indiqué dynamiquement. Ici, cet ensemble aura été construit par le formulaire du squelette standard « choix_mots », qui utilise l'attribut name=ajouter_mot[].

Négation de l'opérateur IN en critère de boucle

… n'affichera que les articles dont l'id n'est pas dans la liste IN (voir critère !opérateur valeur).

Utilisation conditionnelle de l'opérateur IN dans un critère de boucle

Exemple

Si #ID_ARTICLE est présent dans l'environnement :

- ... n'affichera que les articles dont l'id est dans la liste IN.

- ... n'affichera que les articles dont l'id n'est pas dans la liste IN.

Si par contre, #ID_ARTICLE n'est pas présent dans l'environnement, ces critères conditionnels ne s'appliquent pas, et donc ces 2 boucles afficheront tous les articles, quelques soient leur id.

Voir aussi

Critères conditionnels

Opérateurs logiques

Opérateurs

critère LIKE valeur

[1] voir aussi la page de la balise # ENV

#ARRAY

Aurélie, BoOz, denisb — 2009-06-16T06:52:27Z

La balise #ARRAY peut contenir un tableau PHP, c'est-à-dire un ensemble de paires clé/valeur, que l'on veut stocker pour les réutiliser dans la suite du squelette.

Le tableau doit être déclaré par la balise #SET et peut ensuite être récupéré par la balise #GET [1].

Il peut être utilisé ensuite, entre autres, associé au critère IN d'une boucle.

Sommaire

Déclarer un tableau et récupérer des valeurs

- #SET{mon_tableau, #ARRAY{cle1,valeur1,cle2,valeur2}}
crée la variable mon_tableau et lui affecte un tableau PHP comme valeur, qui pourrait être représenté comme suit :

Clés	Valeurs
cle1	valeur1
cle2	valeur2

Il n'est pas nécessaire d'entourer les chaines de caractères avec des guillemets simple ou double, sauf pour spécifier une chaine vide qui s'écrira ''

- À des fins de test, on peut afficher le tableau grâce au filtre |foreach (déprécié depuis SPIP 4)

- La valeur associée à une clé donnée peut être récupérée en utilisant le filtre |table_valeur :

[(#GET{mon_tableau}|table_valeur{cle1})] retourne valeur1.

Depuis SPIP 3.0, on peut simplifier sous la forme suivante [(#GET{mon_tableau/cle1})].

- Vérifier la présence d'une valeur dans le tableau avec le filtre |find [2] :

[(#GET{mon_tableau}|find{valeur2}|oui) Ceci s'affiche si la valeur est dans le tableau. ]

Remplir un tableau dynamiquement

Un intérêt des tableaux est de les remplir dynamiquement, par les résultats d'une ou plusieurs boucle(s).

Le tableau doit alors être déclaré par un #SET avant la boucle : #SET{mon_tableau,#ARRAY}

Dans la boucle, un nouveau #SET redéfinit mon_tableau à chaque itération : on le récupère par #GET et on y ajoute une nouvelle valeur grâce aux filtres |push ou |array_merge.

#SET{mon_tableau,#ARRAY}  #SET{mon_tableau, #GET{mon_tableau}|push{#COMPTEUR_BOUCLE}}

L'ordre des valeurs du tableau dépend des critères de tri de la boucle.

- |push ajoute simplement une valeur à la fin du tableau. La clé est indexée automatiquement : elle est incrémentée de 1 à chaque itération de la boucle et ce, à partir de 0 (la première clé est 0, puis 1, 2, 3,...).

Exemple : créer un tableau mots_choisis contenant les #ID_MOT de tous les mots-clés liés à un article.

#SET{mots_choisis, #ARRAY}  #SET{mots_choisis, #GET{mots_choisis}|push{#ID_MOT}}

Si les mots liés à cet article portent les numéros 4, 9 et 18, [(#GET{mots_choisis}|foreach)] retourne :

0=>4
1=>9
2=>18

Notez bien que [(#GET{mots_choisis}|table_valeur{2})] retourne 18, la valeur associée à la clé 2, donc la troisième valeur du tableau.

- |array_merge ajoute une paire clé/valeur à la fin du tableau. Cela permet donc de forcer le "nom" des clés.

Attention (1) : si une clé apparaît plusieurs fois, seule la dernière valeur pour cette clé sera retenue.

Attention (2) : la clé que l'on veut forcer ne peut pas être de type numérique. En effet, la documentation de array_merge précise :

Si vous passez un seul tableau à cette fonction et qu'il a des index numériques, les clés seront réindexées normalement.

Il existe deux solutions à cette limitation :

- préfixer cette clé avec une valeur alphabétique :

#SET{mots_choisis, #ARRAY}  [(#SET{mots_choisis,#GET{mots_choisis}|array_merge{#ARRAY{mot#ID_MOT,#TITRE}}})]

[(#GET{mots_choisis}|foreach)] retourne :

mot4=>Pomme
mot9=>Banane
mot18=>Carotte

- inverser clé et valeur, à condition que valeur ne soit pas elle aussi numérique :

#SET{mots_choisis, #ARRAY}  [(#SET{mots_choisis,#GET{mots_choisis}|array_merge{#ARRAY{#TITRE,#ID_MOT}}})]

[(#GET{mots_choisis}|foreach)] retourne :

Pomme=>4
Banane=>9
Carotte=>18

Dans ce cas, on pourra appliquer la fonction PHP |array_flip comme filtre sur le tableau final (après la boucle) :

[(#SET{mots_choisis, #GET{mots_choisis}|array_flip})]

[(#GET{mots_choisis}|foreach)] retourne alors :

4=>Pomme
9=>Banane
18=>Carotte

Dans certains cas, on pourra utiliser la balise #LISTE qui permet de saisir des tableaux sous forme simplifiée

Utiliser le tableau dans une boucle avec l'opérateur IN

Reprenons le tableau mots_choisis contenant des #ID_MOT, on peut sélectionner ensuite les articles liés aux mêmes mots-clés que notre article initial grâce au critère IN.

#SET{mots_choisis, #ARRAY}  #SET{mots_choisis, #GET{mots_choisis}|push{#ID_MOT}}   #TITRE

Cette utilisation connaît de multiples usages, notamment lorsque l'on veut sélectionner des objets à l'aide de plusieurs critères qui ne peuvent faire partie de la même boucle, puis les mélanger entre eux avec un critère de tri unique.

Exemples d'utilisation des tableaux

- Affichage conditionnel en fonction de la page (valeur de #ENV{page}) :

[(#ENV{page}|in_array{#ARRAY{0,article,1,rubrique,2,site}}|oui) Affichage conditionnel: la page est celle d'un article, d'une rubrique ou d'un site. ]

- Affichage conditionnel en fonction d'une variable passée dans l'URL [3] :

 #TITRE  #SET{les_mots, #ARRAY}  #SET{les_mots, #GET{les_mots}|push{#ID_MOT}}  [
Ceci s'affichera si la valeur de la variable 'lolo' passée dans l'url est présente dans un tableau 'les_mots' déclaré et rempli précédemment. (#ENV{lolo}|in_any{#GET{les_mots}}|oui)]

- Sélectionner les articles d'une rubrique et ceux associés par ailleurs à un mot-clé puis lister tous ces articles par date.

#SET{les_articles,#ARRAY}  #SET{les_articles,#GET{les_articles}|push{#ID_ARTICLE}}   #SET{les_articles,#GET{les_articles}|push{#ID_ARTICLE}}   
#TITRE

Boucler sur n'importe quel tableau

On pourra utiliser la boucle DATA pour boucler arbitrairement sur un tableau.

Tester si un tableau est vide

1er cas
Si #GET{mon_tableau} est un tableau vide

/* je déclare un tableau vide */ [(#SET{mon_tableau, #ARRAY})] /* alors le test suivant est suffisant : */ [(#GET{mon_tableau}|non) … ]

2e cas
Dans le cas d'entrées vides dans le tableau tel que :

[(#SET{mon_tableau, #ARRAY{0,'',1,0}})]

…on pourra utiliser la fonction PHP array_filter() qui enlèvera du tableau toute valeur équivalente à false du tableau.

[(#GET{mon_tableau}|array_filter|non) ... ]

Voir aussi

#LISTE : balise pratique pour déclarer de simples tableaux indexés
La boucle DATA : pour utiliser des tableaux complexes

[1] Voir #SET et #GET pour plus de détails.

[2] |find correspond à la fonction PHP in_array, à la différence que ce filtre ne produit pas le message d'erreur "Warning : in_array() [function.in-array] : Wrong datatype for second argument." si la variable n'est finalement pas un tableau. En effet, lorsqu'une variable est générée dynamiquement, on ne sait pas toujours si elle existera et s'il s'agira bien d'un tableau.

[3] Voir #SELF et |parametre_url.

Principe général

BoOz, cent20, cerdic, dani, Maïeul, mortimer — 2007-05-20T10:22:28Z

Sommaire

Tout le contenu d'un site géré sous SPIP est installé dans une base de données MySQL. Pour présenter ces informations aux visiteurs du site, il faut donc réaliser l'opération qui consiste à lire les informations, à les organiser et à les mettre en page, afin d'afficher une page HTML dans le navigateur Web.

A moins d'utiliser un gestionnaire de contenu avancé comme SPIP, cette opération est assez fastidieuse :
- il faut connaître la programmation PHP et MySQL, et écrire des « routines » relativement complexes ;
- l'intégration de telles routines dans une mise en page HTML élaborée est assez pénible ;
- il faut développer toute une interface pour que les utilisateurs autorisés modifient le contenu de la base de données ;
- il faut prendre en compte des problèmes de performances : le recours systématique à du code MySQL et PHP est gourmand en ressources, ralentit la visite et, dans des cas extrêmes, provoque des plantages du serveur Web.

SPIP propose une solution complète pour contourner ces difficultés :
- la mise en page du site est effectuée au moyen de gabarits au format HTML nommés squelettes, contenant des instructions simplifiées permettant d'indiquer où et comment se placent les informations tirées de la base de données dans la page ;
- un système de cache permet de stocker chaque page et ainsi d'éviter de provoquer des appels à la base de données à chaque visite. Non seulement la charge sur le serveur est réduite, la vitesse très largement accélérée, de plus un site sous SPIP reste consultable même lorsque la base MySQL est plantée ;
- un « espace privé » permettant aux administrateurs et aux rédacteurs de gérer l'ensemble des données du site.

Pour chaque type de page, un squelette

L'intérêt (et la limite) d'un système de publication automatisé, est de définir un gabarit pour, par exemple, tous les articles. On indique dans ce gabarit (le squelette) où viendront se placer, par exemple, le titre, le texte, les liens de navigation... de l'article, et le système fabriquera chaque page individuelle d'article en plaçant automatiquement ces éléments tirés de la base de données, dans la mise en page conçue par la/le webmestre.

Ce système automatisé permet donc une présentation cohérente à l'intérieur d'un site... Et c'est aussi sa limite : il ne permet pas de définir une interface différente pour chaque page isolée (on verra plus loin que SPIP autorise cependant une certaine souplesse).

Lorsque vous installez SPIP, un jeu de squelettes est proposé par défaut. Il se trouve dans le répertoire squelettes-dist/, à la racine de votre site. Dès que vous modifiez ces fichiers pour les adapter à vos besoins, ou si vous voulez installer un autre jeu de squelettes, il convient de créer un répertoire nommé squelettes/ au même niveau. Pour plus de détails sur cette question, lire l'article Où placer ses squelettes .

Lorsqu'un visiteur demande la page http://exemple.org/spip.php?article3437, SPIP va chercher un squelette nommé « article.html ». SPIP se base donc sur l'adresse URL de la page pour déterminer le squelette à utiliser :

L'URL	appellera le squelette
`spip.php?article3437`	`article.html`
`spip.php?rubrique143`	`rubrique.html`
`spip.php?mot12`	`mot.html`
`spip.php?auteur5`	`auteur.html`
`spip.php?site364`	`site.html`

Avec deux cas particuliers :

- L'URL spip.php appelle le squelette sommaire.html. Il s'agit de la page d'accueil du site.
- L'URL spip.php?page=abcd appelle le squelette abcd.html. En d'autres termes, vous pouvez créer des squelettes qui ne sont pas prévus par le système et les nommer comme vous le souhaitez.

Cette syntaxe sert également pour les pages telles que le plan du site ou les résultats de recherche par exemple : spip.php?page=plan, spip.php?page=recherche&recherche=ecureuil.

Lorsque SPIP appelle un squelette, il lui passe un contexte

Par ailleurs, vous aurez constaté que l'URL fournit d'autres éléments que le nom du squelette. Par exemple, dans spip.php?article3437, le numéro de l'article demandé (3437) ; dans spip.php?page=recherche&recherche=ecureuil, le mot recherché (ecureuil).

Il s'agit d'un « contexte », c'est-à-dire, une ou plusieurs « variables d'environnement », que SPIP va fournir au squelette pour qu'elles puissent être utilisées dans la composition de la page. En effet, le squelette article.html a besoin de connaître le numéro de l'article demandé pour rechercher son titre, son texte,... dans la base de données. De même, le squelette recherche.html doit connaitre les mots recherchés par le visiteur pour trouver les enregistrements de la base de données qui contiennent ces termes.

Dans toute URL, les variables d'environnement apparaissent après le « ? ». Lorsqu'il y en a plusieurs, elles sont séparées par des « & ».

Dans l'URL spip.php?page=recherche&recherche=ecureuil, on a donc deux variables : page et recherche, auxquelles on attribue les valeurs respectives « recherche » et « écureuil ».

Dans le cas de spip.php?article3437, SPIP a simplifié l'URL qui correspond en fait à : spip.php?page=article&id_article=3437 (si si, vous pouvez essayer !). On a donc ici aussi deux variables : page a la valeur "article" et id_article a la valeur "3437". Ces variables permettent à SPIP d'utiliser les données de l'article 3437 dans le squelette article.html.

Le principe de fonctionnement du cache, de manière simplifiée

Schéma simplifié du système de cache

SPIP regarde si une page correspondante à l'URL demandée se situe dans le CACHE

Si la page existe, SPIP vérifie qu'elle n'est pas trop ancienne.
1. Si la page est trop ancienne, SPIP la recalcule à partir du squelette et de la base MySQL, puis la stocke dans le CACHE, avant de l'envoyer à l'utilisateur.
2. Si la page est assez récente, SPIP la retourne à l'utilisateur.
Si la page n'existe pas, SPIP la calcule à partir du squelette et de la base MySQL, puis la stocke dans le CACHE, avant de l'envoyer à l'utilisateur.

Lors d'une visite suivante, si le délai entre les deux visites est suffisamment court, c'est donc cette nouvelle page stockée dans /tmp/cache qui est retournée, sans avoir à faire un nouveau calcul à partir de la base de données. En cas de plantage de la base de données, c'est forcément la page en cache qui est retournée, même si elle est « trop âgée ».

Remarque. On voit ici que chaque page du site est mise en cache individuellement, et chaque recalcul est provoqué par les visites du site. Il n'y a pas, en particulier, un recalcul de toutes les pages du site d'un seul coup à échéance régulière (ce genre de « grosse manœuvres » ayant le bon goût de surcharger le serveur et de le faire parfois planter).

Par défaut, si aucune balise #CACHE n'est utilisée en début de squelette, une page est considérée comme trop vieille au bout de 24 heures. [1]

Le fichier .html

Dans SPIP, nous appelons les fichiers .html les squelettes. Ce sont eux qui décrivent l'interface graphique de vos pages.

Ces fichiers sont rédigés directement en HTML, auquel on ajoute des instructions permettant d'indiquer à SPIP où il devra placer les éléments tirés de la base de données (du genre : « placer le titre ici », « indiquer à cet endroit la liste des articles portant sur le même thème »...).

Les instructions de placement des éléments sont rédigées dans un langage spécifique, qui fait l'objet du présent manuel d'utilisation. Ce langage constitue par ailleurs la seule difficulté de SPIP.

« Encore un langage ? » Hé oui, il va vous falloir apprendre un nouveau langage. Il n'est cependant pas très compliqué, et il permet de créer des interfaces complexes très rapidement. Par rapport au couple PHP/MySQL, vous verrez qu'il vous fait gagner un temps fou (surtout : il est beaucoup plus simple). C'est un markup language, c'est-à-dire un langage utilisant des balises similaires à celles du HTML.

Que peut-on mettre dans un fichier .html

Les fichiers .html sont essentiellement des fichiers « texte », complétés d'instructions de placement des éléments de la base de données.

SPIP analyse uniquement les instructions de placement des éléments de la base de données (codées selon le langage spécifique de SPIP) ; il se contrefiche de ce qui est placé dans ce fichier et qui ne correspond pas à ces instructions.

Leur contenu essentiel est donc du HTML. Vous déterminez la mise en page, la version du HTML désiré, etc. Vous pouvez évidemment y inclure des feuilles de style (CSS), mais également du JavaScript, du Flash... en gros : tout ce qu'on place habituellement dans une page Web.

Mais vous pouvez également (tout cela n'est jamais que du texte) créer du XML (par exemple, « backend.html » génère du XML).

Plus original : toutes les pages retournées au visiteur sont tirées du CACHE par une page écrite en PHP. Vous pouvez donc inclure dans vos squelettes des instructions en PHP, elles seront exécutées lors de la visite. Utilisée de manière assez fine, cette possibilité apporte une grande souplesse à SPIP, que vous pouvez ainsi compléter (par exemple ajouter un compteur, etc.), ou même faire évoluer certains éléments de mise en page en fonction des informations tirées de la base de données.

[1] Une fois que vous aurez compris le langage SPIP, vous pourrez modifier ce délai en vous servant de la balise #CACHE.