La balise #ENV

Fonctionnement et usage divers et variés

Régulièrement, on lit sur la liste ou sur IRC « la balise #ENV, j’y comprends rien » . Tentons ici une explication sur le pourquoi du comment de cette balise...

13 - ENV, qu’est-ce à dire ?

Si nous lisons la documentation officielle, nous voyons que

[(#ENV{xxxx,zzzz})] permet d’accéder à la variable de nom xxxx passée par la requête HTTP. zzzz est une partie optionnelle qui permet de retourner une valeur même si la variable xxxx n’existe pas.

Ah... mais en fait, c’est plus subtil que cela. En réalité, #ENV permet d’accéder aux variables dites d’environnement d’un squelette.

14 - Qu’es aquò variable d’environnement ?

Un squelette SPIP est appelé dans un certain contexte. Par exemple, si vous appelez http://www.spip.net/spip.php?article1 ou bien http://www.spip.net/spip.php?article2, SPIP utilisera le même squelette , article.html, mais ne lui fournira pas les mêmes variables d’environnement.

15 - Mais quelles variables d’environnement sont passées aux squelettes ?

C’est vrai ça, on sait que le squelette reçoit des variables d’environnement, mais lesquelles ?

En préambule, je vais vous donner un « truc » pour savoir quelles variables
d’environnement sont passées à votre squelette.

Il s’agit d’un mode « debug » de SPIP. À la fin de l’adresse d’une page publique, rajoutez &var_mode=debug... Et là ? Surprise ! vous arrivez sur la page de débogage de squelette.

Sur cette page est listé chaque squelette appelé par la page, avec différents
détails...

Ce qui nous intéresse plus particulièrement, c’est la partie #ENV [1]

Prenons l’exemple du squelette de la dist, appelons la page http://site.tld/spip.php?article2&var_mode=debug, nous obtenons ceci

Et voilà la liste des variables d’environnement, avec leurs valeurs... Ainsi, dans cet exemple, si nous écrivons #ENV{id_article} dans le squelette article.html ; nous obtiendrons 2

Bon, d’accord... maintenant, on connaît ce truc, mais bon ... ce serait mieux si on savait d’avance quelles sont ces fameuses variables.

16 - Cas 1 : le squelette de la page

Sans doute le cas le plus simple. Le squelette qui est appelé « directement » quand on accède à une page reçoit comme variables #ENV l’ensemble des variables fournies par l’URL.

Exemple : http://www.site.tld/?page=xxx&var1=val1&

Passera au squelette xxx, les variables d’environnements suivantes :

VariableValeur
page xxx
var1 val1

17 - Cas 2 : les squelettes inclus

Bon, bon... vous incluez un squelette dans votre squelette...

Si vous faites <INCLURE{fond=yy}{var2=val2}> [2], le squelette yy reçoit les variables d’environnement suivantes :

VariableValeur
fond yy
var2 val2

Signalons, au passage que SPIP transmet par défaut, le contexte de langue au squelette inclus.

Ainsi, si vous incluez votre squelette dans un contexte de langue française, le squelette inclus recevra comme variable #ENV« lang » la valeur « fr ». Cependant, il y a possibilité de forcer la variable lang ainsi passée. Il suffit de faire, par exemple<INCLURE{fond=yy}{var2=val2}{lang=en}>.

Signalons aussi le cas des paramètres sans arguments... du genre <INCLURE{fond=yy}{id_article}. Eh bien, dans ce cas, le squelette inclus recevra la variable #ENV « id_article » dont la valeur sera celle de l’id_article courant.

Enfin, signalons la possibilité de passer à un squelette inclus l’ensemble des variables d’environnement du squelette incluant ! Il suffit pour cela d’ajouter le critère {env} dans l’appel de votre INCLURE... Cependant, il est conseillé d’éviter cela : en effet, rappelons qu’un fichier de cache est généré pour chaque combinaison de variable #ENV.

18 - Cas 3 : les modèles

Depuis SPIP 1.9.1, il est possible d’installer des modèles dans un article.

Pour rappel, la syntaxe générale de l’appel d’un modèle est <modelexxx|align|var1=val1|...|varn=valn>

Un modèle, n’est après tout qu’un squelette. Comme tout squelette, il reçoit des paramètres #ENV.

Prenons un exemple simple <modele1|left|variable=valeur>.

Les variables passées sont :

VariableValeur
id 1
id_modele 1
align left
variable valeur
lang Langue du contexte

Depuis SPIP 3, les modèles reçoivent aussi comme variables d’environnement les variables de la page l’appelant. Cependant les arguments passés explicitement au modèle se retrouvent dans #ENV{args/nomdelargument}.

19 - Cas 4 : les formulaires

Rappelons qu’un formulaire est composé de deux fichiers :
-  un squelette
-  un fichier php, chargé de la prise en charge des données.

C’est le fichier php, qui en appelant le squelette, va lui transmettre un certain nombres de variables #ENV. Il faut donc regarder pour chaque formulaire ce qu’il en est (via le mode debug).

20 - Cas 5 : les pages en « article »,« rubrique » etc

Les pages qui fonctionnent en URL propres fournissent leurs variables #ENV selon des règles spéciales.

Si une page fonctionnant en URL propres est une page de type « article », le squelette recevra comme variable d’environnement id_article de la valeur du numéro de l’article concerné...

Il en est de même pour les pages de types rubriques, mot, etc.

21 - Des variables d’environnement de date

Des variables d’environnement calculées automatiquement [3] sont passées à tout les squelettes calculés (sauf les modèles pour SPIP < 3)

Ces variables sont date et date_redac, qui ont pour valeur la date de calcul de la page... Elles servent au calcul des critères {age} et {age_redac}

22 - Forme abrégée

En dehors de toute boucle, #TOTO est strictement égale à #ENV{toto}. Cependant, sauf cas exceptionnel, on préférera la première syntaxe : en effet, #TOTO appelée dans une boucle possédant la balise #TOTO sera compris dans le contexte de cette boucle.

Exemple :

#ID_ARTICLE #ENV{id_article}
<BOUCLE_article(ARTICLES)>
#ID_ARTICLE #ENV{id_article}
</BOUCLE_article>
  • En dehors de la boucle #ID_ARTICLE et #ENV{id_article} sont équivalents.
  • Dans la boucle, en revanche, ils ne le sont pas.

23 - Quelles utilisations ?

De nombreuses utilisations sont possibles, notamment à l’aide des filtres de comparaisons. Cela pourrait être l’objet d’une documentation à part.

La balise #EXPOSE

Citons cependant le plus souvent demandé : l’utilisation de la balise #EXPOSE.

Dans une boucle (OBJETS), où chaque objet à un identifiant unique de la forme id_objet [4], lorsque cet identifiant est égal à la valeur de la variable d’environnement id_objet, la balise #EXPOSE retourne son premier argument ; sinon, son second argument.

Exemple : Soit la page www.domaine.tld/spip.php?page=toto&id_article=2

Supposons que notre site n’ait que deux articles, les numéros 1 et 2.

Si le squelette toto.html contient la boucle suivante

<BOUCLE_toto(ARTICLES)>
l'article n°#ID_ARTICLE #EXPOSE{"est l'article courant", "n'est pas l'article courant"}
</BOUCLE_toto>

Alors le résultat sera

l’article n°1 n’est pas l’article courant
l’article n°2 est l’article courant

/ !\ La syntaxe SPIP prohibe totalement de mettre des boucles entres {}. Seule des balises et filtres peuvent exister.

24 - Conclusion : encore pas mal de rédaction

Voilà ! Il y a encore pas mal de choses à écrire pour saisir toutes les subtilités des variables d’environnement, mais j’espère que cet article, laborieusement écrit à la sueur des mes doigts vous aura permis de comprendre un peu mieux comment les déterminer.

Notes

[1ben oui quoi, c’est un tuto sur #ENV

[2il semble que ce soit la même chose avec #INCLURE, mais j’avoue ne pas avoir saisi la nuance

[3sauf si on force leurs valeurs lors d’un ou #INCLURE

[4par exemple, dans une boucle (ARTICLES), chaque article à un identifiant id_article

Discussion

Aucune discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom