#ARRAY

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.

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ésValeurs
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}
<BOUCLE(...)>
    #SET{mon_tableau, #GET{mon_tableau}|push{#COMPTEUR_BOUCLE}}
</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}
<BOUCLE_themes(MOTS){id_article}>
  #SET{mots_choisis, #GET{mots_choisis}|push{#ID_MOT}}
</BOUCLE_themes>

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}
<BOUCLE_themes(MOTS) {id_article}>
  [(#SET{mots_choisis,#GET{mots_choisis}|array_merge{#ARRAY{mot#ID_MOT,#TITRE}}})]
</BOUCLE_themes>

[(#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}
<BOUCLE_themes(MOTS) {id_article}>
  [(#SET{mots_choisis,#GET{mots_choisis}|array_merge{#ARRAY{#TITRE,#ID_MOT}}})]
</BOUCLE_themes>

[(#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}
<BOUCLE_themes(MOTS){id_article}>
  #SET{mots_choisis, #GET{mots_choisis}|push{#ID_MOT}}
</BOUCLE_themes>

<BOUCLE_memes_themes(ARTICLES) {id_mot IN #GET{mots_choisis}}>
  #TITRE <br>
</BOUCLE_memes_themes>

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] :

<BOUCLE_tous_les_mots(MOTS){par titre}{", "}>
  <a href="[(#SELF|parametre_url{lolo,#ID_MOT})]">#TITRE</a>
</BOUCLE_tous_les_mots>

#SET{les_mots, #ARRAY}
<BOUCLE_certains_mots(MOTS){id_article}>
  #SET{les_mots, #GET{les_mots}|push{#ID_MOT}}
</BOUCLE_certains_mots>

[<br>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}
<BOUCLE_articles_rubrique(ARTICLES){id_rubrique}>
  #SET{les_articles,#GET{les_articles}|push{#ID_ARTICLE}}
</BOUCLE_articles_rubrique>
<BOUCLE_articles_mot(ARTICLES){id_mot}>
  #SET{les_articles,#GET{les_articles}|push{#ID_ARTICLE}}
</BOUCLE_articles_mot>

<BOUCLE_affiche(ARTICLES){id_article IN #GET{les_articles}}{par date}>
  <br>#TITRE
</BOUCLE_affiche>

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

Notes

[1Voir #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.

[3Voir #SELF et |parametre_url.

Auteur Aurélie, BoOz, denisb Publié le : Mis à jour : 28/07/23

Traductions : عربي, català, English, Español, français, Nederlands