Documentation du code de SPIP

Qu'est-ce qu'un plugin ? Principes et création.

Matthieu Marcillaud — 2012-06-15T10:28:16Z

Un plugin est un ensemble paquetages de fichiers qui servent à apporter des fonctionnalités supplémentaires à l'écureuil SPIP. Tout ce qui peut être mis dans un dossier squelettes/ peut être proposé sous forme de plugin.

Un plugin peut donc fournir des habillages graphiques, des fonctionnalités d'administrations, des filtres, des modèles, de nouvelles boucles ou critères, gérer de nouvelles tables SQL, etc. Les possibilités d'un plugin dépendent juste de l'imagination de son créateur.

Un plugin doit donc permettre de dire à SPIP qu'il possède de nouvelles fonctionnalités, ou que certains points du fonctionnement de SPIP changent si l'on utilise un plugin.

Cette documentation décrit uniquement le fonctionnement pour SPIP 2.0

Nota : D'autres documentations explicatives existent sur spip.net :
Installer un plugin
Réaliser un premier plugin
Etendre SPIP

Créer un plugin

Pour créer un plugin, il suffit simplement de créer un dossier au nom de votre plugin dans le répertoire plugins/ de SPIP. Il vous faut créer ce répertoire s'il n'est pas présent.

Pour que le plugin soit connu de SPIP, il faut que le dossier de votre plugin contiennent un fichier plugin.xml, composé d'un certain contenu, décrit plus loin dans cette documentation.

A partir de là, il y a trois moyens principaux donnés aux plugins pour transmettre des informations à SPIP :

la surcharge et création de fichiers
le contenu du fichier plugin.xml
les points d'entrées de SPIP (appelés pipelines)

Surcharge et création de fichiers

Depuis longtemps, SPIP permet de surcharger ses fichiers et d'en utiliser de nouveaux les installant dans le dossier squelettes/ ou en ajoutant des dossiers dans le chemin (ou path) de SPIP via la globale PHP dossier_squelettes ou par la constante PHP _SPIP_PATH, par exemple avec cette ligne dans le fichier config/mes_options.php :

Lorsque l'on demande un fichier à SPIP (fichier php ou un squelette), SPIP va chercher le fichier dans l'ordre des chemins. S'il ne le trouve pas dans le répertoire
squelettes/, il cherchera dans
mon_dossier/,
dist/,
prive/, puis
ecrire/.

Lorsqu'un plugin est activé, celui-ci s'ajoute automatiquement dans le chemin de SPIP. Ainsi, lorsque SPIP cherche un fichier, il regardera (si l'on reprend l'exemple précédent) dans
squelettes/,
mon_dossier/,
plugins/le_plugin/,
dist/,
prive/, puis dans
ecrire/.

Lorsque plusieurs plugins sont actifs, SPIP cherchera dans les plugins par ordre alphabétique par rapport au nom du dossier. plugins/attributs/ sera traité avant plugins/crayons.

Cependant, les plugins peuvent necessiter ou utiliser d'autres plugins. Par exemple, le plugin Crayons peut être configuré avec le plugin CFG. Pour cela, crayons possède une ligne spéciale indiquant sa dépendance optionnelle à CFG dans le fichier plugin.xml.

Un plugin qui dépend d'un autre passe alors avant lui dans les chemins de SPIP. Cela permet au plugin de surcharger des fichiers du plugin dont il dépend.

Dans l'exemple précédent, l'ordre de lecture des répertoires serait :
squelettes/,
mon_dossier/,
plugins/attributs/,
plugins/crayons/,
plugins/cfg/,
dist/,
prive/,
ecrire/.

Quels répertoires pour les fichiers des plugins ?

Voir aussi :
Etendre SPIP
Les différents points d'insertion d'un plugin

Vous êtes libre de l'organisation du répertoire de votre plugin, cependant, il est préférable d'utiliser les mêmes nommages de répertoires que SPIP, ceci pour faciliter la compréhension et la maintenance du plugin.

Voici quelques répertoires et leurs fonctions (pour les plugins) :
action/ : actions généralement sécurisées modifiant le contenu de la base de données
balise/ : déclaration de balises SPIP dynamiques. La plupart des balises peuvent être déclarées dans le fichier de fonctions du plugin. Les autres balises fournies par SPIP sont déclarées dans public/balises.php.
base/ : déclaration, installation, et mise à jour et désinstallation de la structure de la base de données ; procédures d'installation et de désinstallation du plugin
exec/ : affichage de pages dans l'interface privé,
genie/ : taches périodiques (cron),
inc/ : librairies de fonctions,
javascript
lang/ : fichiers de lang pour le multilinguisme,
public/ : compilateur de SPIP, déclarations d'exceptions sur les champs de tables SQL
req/ : traducteurs des fonctions d'abstractions SQL vers les serveurs de base de donnée (MySQL, PostGres, SQlite)
urls/ : gestion des urls publiques des pages de SPIP
xml/ : interpreteur XML de SPIP

Plugin.xml

Voir aussi : Le fichier plugin.xml

Les plugins ont des possibilités supplémentaires par rapport à un simple dossier squelettes. Ils peuvent utiliser leur propres fichiers de fonctions ou d'options, peuvent exécuter des procédures lors de leur installation, mise à jour ou désinstallation et ils peuvent utiliser des points d'entrées de SPIP.

Tout cela doit être déclaré dans le fichier plugin.xml. C'est le fichier qui décrit le plugin, son nom, sa version, sa description, son auteur, sa licence ainsi que les points d'entrées de SPIP qu'il utilise.

Décrivons la syntaxe, en utilisant le fichier (simplifié) du plugin Crayons (voir le code original) :

Il faut tout s'abord encadrer les paramètres contenus dans plugin.xml par une balise :

Les paramètres sont assez nombreux, on pourra trouver :
nom
auteur
version : la version du plugin
version_base : la version de la structure de la base de donnée du plugin
etat : stable, test ou en dev
lien : vers la documentation
icon
description
licence
fonctions : nom d'un fichier de fonctions chargé au moment des calculs de squelettes
options : nom d'un fichier d'options chargé à chaque hit
necessite : dépendance obligatoire d'un autre plugin (ou d'une version de SPIP)
utilise : dépendance optionnelle
pipeline : déclaration de l'utilisation de points d'entrées de SPIP par le plugin
chemin : '' ou 'ecrire/' charger le plugin systematiquement ou seulement dans l'interface privée

Ce qui donne pour le plugin Crayons un fichier xml de la sorte :

Le plugin déclare utiliser 2 pipelines : affichage_final et header_prive, dont les fonctions sont déclarées dans le fichier tetecrayons.php.

Points d'entrées

Voir aussi :
Se servir des points d'entrées
Les pipelines
Création d'un plugin
Mise en oeuvre de la balise #PIPELINE

Les points d'entrées ou "pipeline" sont des fonctions exécutées par SPIP à certains endroits de son code, dans lesquelles SPIP transmets certains paramètres.

Lorsqu'un plugin a déclaré un pipeline, et que le pipeline en question est appelé, SPIP appelle la fonction du plugin avec les paramètres. La fonction du plugin doit retourner ce qu'elle a reçu, en modifiant (ou non) les paramètres.

Par exemple, le pipeline insert_head permet d'ajouter du contenu dans entre les balises et des pages publiques générées par SPIP. Pour ce pipeline, c'est directement le contenu html ajouté qui est transmis. Un plugin pourra donc l'utiliser de la sorte (en l'ayant déclaré dans le fichier plugin.xml) :

Récapitulatif

denisb — 2010-10-14T14:59:21Z

branche 1.0 (août 2001 - 798 000 o. - 248 fichiers)
— « SPIP är ett ~ publishing system ~ para Internet ~ chì si primureghja particularmente ~ a un funcionamientu en comuña, ~ dessen besondere Stärken Mehrsprachigkeit, ~ et à la facilité d'emploi. »

balise [1]	critère [2]
#COMPTEUR_BOUCLE #FORMULAIRE_FORUM #FORMULAIRE_INSCRIPTION #FORMULAIRE_RECHERCHE #FORMULAIRE_SIGNATURE #INTRODUCTION #LESAUTEURS #LOGO_ARTICLE #LOGO_ARTICLE_NORMAL #LOGO_ARTICLE_RUBRIQUE #LOGO_ARTICLE_SURVOL #LOGO_AUTEUR #LOGO_BREVE #LOGO_RUBRIQUE #NOTES #PARAMETRES_FORUM #TOTAL_BOUCLE #URL_ARTICLE #URL_BREVE #URL_FORUM #URL_MOT #URL_RUBRIQUE	age age_redac annee annee_redac debut... doublons exclus id_enfant inverse meme_parent mois mois_redac par date par hasard par points plat racine recherche tout unique

branche 1.2 (novembre 2001 - 912 000 o. - 278 fichiers)
- Administrateurs restreints
- Messagerie interne
- Nouveau système de cache
- Flux compressé
- Feuilles de style et variables PHP pour modifier un peu plus les squelettes
- Mots-clés sur les brèves
- Moteur de recherche interne
- Syndication RSS
- Critères négatifs dans les boucles des squelettes
- mes_fonctions.php

nouvelle balise	nouveau critère
#LOGO_MOT #URL_SYNDIC

branche 1.3 (janvier 2002 - 986 000 o. - 299 fichiers)
- Refonte système de syndication de sites
- Blocs dépliables
- Date des brèves
- Dates imprécises
- Upload d'images par FTP
- Forum interne des administrateurs
- Nouveau raccourci < cadre >
- Squelettes par rubrique

nouvelle balise	nouveau critère
#FORMULAIRE_SITE #LOGO_SITE	age_relatif par num par titre_mot par type_mot titre_mot type_mot

branche 1.4 (septembre 2002 - 1 407 000 o. - 321 fichiers)
- Refonte graphique de l'espace privé
- Documents joints et documents multimédia
- Multi-base
- Apparition des < INCLURE >
- Vignettes automatiques

nouvelle balise	nouveau critère
#DEBUT_SURLIGNE #EMBED_DOCUMENT [3] #FIN_SURLIGNE #FORMULAIRE_ECRIRE_AUTEUR #HAUTEUR #LARGEUR #LOGIN_PRIVE #LOGIN_PUBLIC #LOGO_DOCUMENT #POPULARITE #POPULARITE_ABSOLUE #POPULARITE_MAX #POPULARITE_SITE #TAILLE #TYPE_DOCUMENT #URL_DOCUMENT	branche extension id_groupe mode

branche 1.5 (janvier 2003 - 1 490 000 o. - 335 fichiers)
- Support LDAP
- Introduction d'un mécanisme de log
- Passage de paramètres multiples dans les filtres
- Apparition de $dossier_squelettes
- Conformité W3C accrue
- Nouveaux filtres typo

nouvelle balise	nouveau critère
#CHARSET #FORMULAIRE_ADMIN #PUCE #URL_LOGOUT

branche 1.6 (juillet 2003 - 6 044 000 o. - 504 fichiers)
- Multilinguisme espace privé, aide en ligne et partie de l'espace public
- Raccourcis clavier dans l'espace privé
- Filtres |sinon, |choixsivide, |choixsiegal
- mes_options.php

nouvelle balise	nouveau critère
#DATE_NOUVEAUTES #RECHERCHE	annee_relatif jour_relatif mois_relatif

branche 1.7 (janvier 2004 - 10 190 000 o. - 673 fichiers)
- Création automatique de vignettes
- Critères optionnels
- Renforcement du multilinguisme
- Gestion iCal

nouvelle balise	nouveau critère
#EXPOSER [4] #EXTRA #LANG #LANG_DIR #LANG_LEFT #LANG_RIGHT	lang_select origine_traduction traduction

branche 1.8 (avril 2005 - 7 987 000 o. - 638 fichiers)
- Nouveau compilateur
- Refonte graphique de l'espace privé
- Correcteur orthographique
- Prévisualisation
- Historique des modifications
- Portfolio
- Filtres graphiques
- Débogueur et var_mode
- et LaTEX
- Documents distants
- Calendrier dans l'espace public
- Squelettes en XHTML 1.0 transitional
- Filtres graphiques

nouvelle balise	nouveau critère
#DATE_MODIF #DOSSIER_SQUELETTE #ENV #ERREUR_AUCUN [5] #MENU_LANG #MENU_LANG_ECRIRE #POINTS #SELF #SPIP_CRON	? IN agenda statut

1.8.2 (août 2005)

nouvelle balise	nouveau critère
#EXPOSE

branche 1.9 (janvier 2006 - 10 225 000 o. - 889 fichiers)
- Nouveaux squelettes, disparition des squelettes.php3
- Apparition de #CACHE
- Apparition de #CHEMIN
- Filtres graphiques
- Ecriture allégée pour les balises : suppression des [( et )]
- Détection automatique de jointures
- Possibilité de surcharge des fichiers standards
- Réorganisation des fichiers et répertoires
- Système de pagination
- Ajax dans l'espace privé
- Système de plugins
- Mutualisation
- Fonctions SQL en critère
- Apparition des modèles
- Balises #SET et #GET
- Nouveaux filtres typo, graphiques...

nouvelle balise	nouveau critère
#ANCRE_PAGINATION #CACHE #CHEMIN #CONFIG #EVAL #GET #GRAND_TOTAL #HTTP_HEADER #INCLUDE #INCLURE #INSERT_HEAD #MODELE #NOM_SITE #PAGINATION #RANG #REM #SET #SPIP_VERSION #SQUELETTE #URL_ECRIRE #URL_PAGE	fragment logo pagination par multi champ secteur_forum

1.9.2 (février 2007)
- Introduction de jQuery
- Réorganisation des fichiers et répertoires
- Validateur XML

nouvelle balise	nouveau critère
#ARRAY #EDIT #PIPELINE #TOTAL_UNIQUE #URL_ACTION_AUTEUR	fusion

branche 2.0 (décembre 2008 - 13 144 000 o. - 1 205 fichiers)
- Nouvelle API urls (urls propres, generer_url_)
- API de modification de contenu
- Gestion des éditions concurrentes
- API sql (accès bases et serveurs multiples, serveur virtuel, profileur)
- Jointure automatique à partir des critères de boucle
- Abandon de l'indexation (recherche)
- Amélioration de la mutualisation
- Réorganisation des fichiers et répertoires
- Nouveaux squelettes 'LayoutGala'
- Personnalisation accrue
- Formulaires CVT
- Possibilité d'installation automatique des plugins
- Nouveaux pipelines
- Ajax dans les INCLURE

nouvelle balise	nouveau critère
#ACTION_FORMULAIRE #AIDER #AUTORISER #CHAMP_SQL #CONNECT #FILTRE #FOREACH #FORMULAIRE_EDITER_ARTICLE #FORMULAIRE_EDITER_AUTEUR #FORMULAIRE_EDITER_BREVE #FORMULAIRE_EDITER_GROUPE_MOT #FORMULAIRE_EDITER_MOT #FORMULAIRE_EDITER_RUBRIQUE #FORMULAIRE_EDITER_SITE #FORMULAIRE_LOGIN #NOOP #PLUGIN #SESSION #SESSION_SET #VAL	collecte

branche 2.1 (avril 2010 - 13 798 000 o. - 1 213 fichiers [6])
- Mise en extensions de fonctionnalités du core
- Utilisation de sha256
- Nouvelle gestion des plugins

nouvelle balise	nouveau critère
#BOUTON_ACTION #CHEMIN_IMAGE #DOUBLONS #INSERT_HEAD_CSS

branche 3 « trunk » (au 26 août 2011 - 10 449 634 o. - 1 253 fichiers [6])
- Poursuite de la mise en extensions de fonctionnalités du core
- Gestion générique des éléments de SPIP (OBJETS)
- Utilisation du format SQLite par défaut (installation, export...)
- Nouvelle gestion des documents
- Mise en squelettes de l'espace privé
- Gestion générique des listes d'objets
- Réforme des pages et formulaires de configuration
- API pour gestion des liens entre objets
- nouveaux jeux d'icones
- Gestion de file d'attente de travaux datés
- Possibilité de boucler sur d'autres objets que des tables sql (intégration de « itérateurs »)
- Nouvelle gestion de la typographie

nouvelle balise	nouveau critère
#CLE #CONFIGURER_METAS #FORMULAIRE_CONFIGURER_ANNONCES #FORMULAIRE_CONFIGURER_ARTICLES #FORMULAIRE_CONFIGURER_AVERTISSEUR #FORMULAIRE_CONFIGURER_FLUX #FORMULAIRE_CONFIGURER_IDENTITE #FORMULAIRE_CONFIGURER_LANGAGE #FORMULAIRE_CONFIGURER_LANGUE #FORMULAIRE_CONFIGURER_LOGOS #FORMULAIRE_CONFIGURER_MODERNISEUR #FORMULAIRE_CONFIGURER_MULTILINGUISME #FORMULAIRE_CONFIGURER_PREFERENCES #FORMULAIRE_CONFIGURER_PREVISUALISEUR #FORMULAIRE_CONFIGURER_REDACTEURS #FORMULAIRE_CONFIGURER_REDUCTEUR #FORMULAIRE_CONFIGURER_RELAYEUR #FORMULAIRE_CONFIGURER_RUBRIQUES #FORMULAIRE_CONFIGURER_TRANSCODEUR #FORMULAIRE_CONFIGURER_VISITEURS #FORMULAIRE_DATER #FORMULAIRE_EDITER_LIENS #FORMULAIRE_EDITER_LOGO #FORMULAIRE_RECHERCHE_ECRIRE #FORMULAIRE_REDIRIGER_ARTICLE #HTML5 #INFO_ #LARGEUR_ECRAN #LISTE #PRODUIRE #PUBLIE #SAUTER #SLOGAN_SITE_SPIP #TRI #VALEUR	datacache datapath feuilles liste noeud offset source tri where

nouvelle balise

nouveau critère

#CLE
#CONFIGURER_METAS
#FORMULAIRE_CONFIGURER_ANNONCES
#FORMULAIRE_CONFIGURER_ARTICLES
#FORMULAIRE_CONFIGURER_AVERTISSEUR
#FORMULAIRE_CONFIGURER_FLUX
#FORMULAIRE_CONFIGURER_IDENTITE
#FORMULAIRE_CONFIGURER_LANGAGE
#FORMULAIRE_CONFIGURER_LANGUE
#FORMULAIRE_CONFIGURER_LOGOS
#FORMULAIRE_CONFIGURER_MODERNISEUR
#FORMULAIRE_CONFIGURER_MULTILINGUISME
#FORMULAIRE_CONFIGURER_PREFERENCES
#FORMULAIRE_CONFIGURER_PREVISUALISEUR
#FORMULAIRE_CONFIGURER_REDACTEURS
#FORMULAIRE_CONFIGURER_REDUCTEUR
#FORMULAIRE_CONFIGURER_RELAYEUR
#FORMULAIRE_CONFIGURER_RUBRIQUES
#FORMULAIRE_CONFIGURER_TRANSCODEUR
#FORMULAIRE_CONFIGURER_VISITEURS
#FORMULAIRE_DATER
#FORMULAIRE_EDITER_LIENS
#FORMULAIRE_EDITER_LOGO
#FORMULAIRE_RECHERCHE_ECRIRE
#FORMULAIRE_REDIRIGER_ARTICLE
#HTML5
#INFO_
#LARGEUR_ECRAN
#LISTE
#PRODUIRE
#PUBLIE
#SAUTER
#SLOGAN_SITE_SPIP
#TRI
#VALEUR

datacache
datapath
feuilles
liste
noeud
offset
source
tri
where

[1] Ne sont recensées ici que les balises dites calculées (qui font autre chose que retourner un enregistrement depuis la base de données).

[2] Ne sont recensées ici que les critères calculés (autres que ceux directement issus de la table sql concernée).

[3] Obsolète à partir de 2.1

[4] Obsolète à partir de 1.8.2 ; remplacée par #EXPOSE

[5] Supprimée en 1.9

[6] les éléments du répertoire extensions/ ne sont pas comptabilisés.

les balises dynamiques de SPIP (liste)

denisb — 2010-10-14T14:56:48Z

À la révision 16017 de SPIP 2.1.2 (3 septembre 2010).

Ne tient pas compte des « extensions/ ».

liste des balises dynamiques
(*qui font « autre chose » que simplement renvoyer une valeur stockée en base*)
nom	surchargeable
#ACTION_FORMULAIRE
#AIDER	oui
#ANCRE_PAGINATION
#ARRAY	oui
#AUTORISER	oui
#BOUTON_ACTION	oui
#CACHE	oui
#CHAMP_SQL	oui
#CHAPO	oui
#CHARSET	oui
#CHEMIN	oui
#CHEMIN_IMAGE	oui
#COMPTEUR_BOUCLE	oui
#CONFIG	oui
#CONNECT	oui
#DATE	oui
#DATE_MODIF	oui
#DATE_NOUVEAUTES	oui
#DATE_REDAC	oui
#DEBUT_SURLIGNE	oui
#DESCRIPTIF_SITE_SPIP	oui
#DOSSIER_SQUELETTE	oui
#DOUBLONS	oui
#EDIT	oui
#EDITABLE
#EMAIL_WEBMASTER	oui
#ENV	oui
#EVAL	oui
#EXPOSE	oui
#FILTRE	oui
#FIN_SURLIGNE	oui
#FOREACH	oui
#FORMULAIRE_	oui
#FORMULAIRE_ADMIN
#FORMULAIRE_ECRIRE_AUTEUR
#FORMULAIRE_FORUM
#FORMULAIRE_INSCRIPTION
#FORMULAIRE_RECHERCHE
#FORMULAIRE_SIGNATURE
#FORMULAIRE_SITE
#GET	oui
#GRAND_TOTAL	oui
#HTTP_HEADER	oui
#INCLUDE	oui
#INCLURE	oui
#INSERT_HEAD	oui
#INSERT_HEAD_CSS	oui
#INTRODUCTION	oui
#LANG_DIR	oui
#LANG_LEFT	oui
#LANG_RIGHT	oui
#LANG	oui
#LESAUTEURS	oui
#LOGIN_PRIVE
#LOGIN_PUBLIC
#LOGO_	oui
#LOGO_ARTICLE
#LOGO_ARTICLE_NORMAL
#LOGO_ARTICLE_SURVOL
#LOGO_ARTICLE_RUBRIQUE
#LOGO_AUTEUR
#LOGO_AUTEUR_NORMAL
#LOGO_AUTEUR_SURVOL
#LOGO_BREVE
#LOGO_BREVE_NORMAL
#LOGO_BREVE_SURVOL
#LOGO_DOCUMENT
#LOGO_MOT
#LOGO_MOT_NORMAL
#LOGO_MOT_SURVOL
#LOGO_RUBRIQUE
#LOGO_RUBRIQUE_NORMAL
#LOGO_RUBRIQUE_SURVOL
#LOGO_SITE
#LOGO_SITE_NORMAL
#LOGO_SITE_SURVOL
#LOGO_SITE_SPIP
#MENU_LANG
#MENU_LANG_ECRIRE
#MODELE	oui
#NOM_SITE	oui
#NOM_SITE_SPIP	oui
#NOOP	oui
#NOTES	oui
#PAGINATION	oui
#PARAMETRES_FORUM	oui
#PETITION	oui
#PIPELINE	oui
#PLUGIN	oui
#POINTS	oui
#POPULARITE	oui
#POPULARITE_ABSOLUE	oui
#POPULARITE_MAX	oui
#POPULARITE_SITE	oui
#PUCE	oui
#RANG	oui
#RECHERCHE	oui
#REM	oui
#SELF	oui
#SESSION	oui
#SESSION_SET	oui
#SET	oui
#SPIP_CRON	oui
#SPIP_VERSION	oui
#SQUELETTE	oui
#TOTAL_BOUCLE	oui
#TOTAL_UNIQUE	oui
#URL_	oui
#URL_AUTEUR
#URL_RUBRIQUE
#URL_ACTION_AUTEUR	oui
#URL_ARTICLE	oui
#URL_DOCUMENT
#URL_ECRIRE	oui
#URL_LOGOUT
#URL_PAGE	oui
#URL_SITE_SPIP	oui
#URL_SITE	oui
#VAL	oui

Les constantes de SPIP

denisb — 2010-10-03T09:23:32Z

À la révision 16017 de SPIP 2.1.2 (3 septembre 2010).

Ne tient pas compte des « extensions/ » ni de la lib. « PclZip ».

liste des constantes
nom	défaut	pourquoi

A
_ACCESS_FILE_NAME	`.htaccess`	chaîne standard (utils.php)
_ACTIVER_PUCE_RAPIDE	`true`	utiliser la puce pour modifier le statut (presentation.php)
_ADMINS_RESTREINTS	`true`	mettre à 'false' pour ignorer la notion d'admin restreint (autoriser.php)
_AGE_CACHE_ATIME	`3600`	si un fichier n'a pas servi (fileatime) depuis plus d'une heure, on se sent en droit de l'éliminer (invalideur.php)
_AJAX		la requete est-elle en ajax ? (utils.php)
AUTEURS_DEFAUT	`''`	affichage par défaut des 'auteurs'. si la valeur est ' !' ce seront les visiteurs qui s'afficheront (auteurs.php)
AUTEURS_MIN_REDAC	`0minirezo,1comite,5poubelle`	les auteurs à afficher par défaut (auteurs.php)
_AUTH_USER_FILE	`.htpasswd`	chaîne standard (utils.php)

B
BALISE_ALT_BOUCLE		pour reconnaître la fin de la partie alternative des boucles (phraser.php)
BALISE_BOUCLE		pour reconnaître le début de la partie principale des boucles (phraser.php)
BALISE_FIN_BOUCLE		pour reconnaître la fin de la partie principale des boucles (phraser.php)
BALISE_IDIOMES		regexp pour reconnaître les chaînes de langue (phraser_html.php)
BALISE_INCLURE		regexp pour reconnaître les INCLURE dynammiques (phraser_html.php)
BALISE_POLYGLOTTE		regexp pour reconnaître les champs multi (phraser_html.php)
BALISE_POST_BOUCLE		pour reconnaître la fin de la partie optionnelle des boucles (phraser.php)
BALISE_PRE_BOUCLE		pour reconnaître le début de la partie optionnelle des boucles (phraser.php)
_BALISES_BLOCS	`div, pre, ul, ol, li, blockquote etc`	tous les éléments dont on souhaite qu'ils provoquent un saut de paragraphe (texte.php)
_BOUTON_MODE_IMAGE	`true`	pour afficher la boite d'upload des images (legender.php)

C
_CACHE_CHEMIN	`tmp/cache/chemin.txt`	si le visiteur est admin, on ne recharge pas le cache pour forcer sa mise à jour ; le cache de chemin n'est utilisé que dans le public (utils.php)
_CACHE_CONTEXTES_AJAX
_CACHE_PIPELINES	`tmp/cache/charger_pipelines.php`	(utils.php)
_CACHE_PLUGINS_FCT	`tmp/cache/charger_plugins_fonctions.php`	(utils.php)
_CACHE_PLUGINS_OPT	`tmp/cache/charger_plugins_options.php`	(utils.php)
_CACHE_PLUGINS_PATH
_CACHE_PLUGINS_VERIF	`tmp/cache/verifier_plugins.txt`	(utils.php)
_CACHE_RUBRIQUES	`tmp/menu-rubriques-cache.txt`	chaîne standard (utils.php)
_CACHE_RUBRIQUES_MAX	`500`	limiter le nombre de rubriques affichées (utils.php)
CHAMP_ETENDU		reconnaître les [()] imbriqués (phraser_html.php)
CHAMP_SQL_PLUS_FONC		(phraser_html.php)
CHARSET_JOINT	`iso-8859-1`	charset probable des documents joints non utf-8 (documents.php)
_CNIL_PERIODE
CODE_COMMENTE
CODE_CORPS_BOUCLE
CODE_EXECUTER_BALISE
CODE_INCLURE_BALISE
CODE_INCLURE_SCRIPT
CODE_MONOTONE		repérer un code ne calculant rien, même avec commentaire (compiler.php)
CODE_PAGINATION
_CODE_QUOTE
CODE_RECUPERER_FOND
CONFIRMER_MODIFIER_URL	`false`	verifier qu'on veut effectivment modifier une adresse existante (arbo.php et propres.php)
_CONSERVER_IMAGES_TEMPORAIRES
_CONTEXTE_IGNORE_VARIABLES	`/(^var_\|^PHPSESSID$)/`	sécurité pour le calcul du contexte (assembler.php)
_CONVERT_COMMAND	`convert`	pour utilisation de imagemagick (tourner.php et filtres_images_mini.php)
_COOKIE_DOMAIN
_COOKIE_PATH
_COPIE_LOCALE_MAX_SIZE	`16777216`	poids maximal en octets pour copie locale (utils.php)
_CREER_DIR_PLAT	`false`	ne pas créer de faux sous-répertoire sous la forme fichier.plat (flock.php)
_CRON_DELAI
_CRON_DELAI_GOURMAND
_CRON_LOT_FICHIERS_VISITE	`100`	nombre de sessions de moins de 30 minutes à traiter par le cron (visites.php)

D
_DEBUG_AUTORISER
_DEBUG_CONVERT
_DEBUG_IMPORT
_DEBUG_MAX_SQUELETTE_ERREURS
_debut_urls_arbo
_debut_urls_page
_debut_urls_propres
_DEFAULT_CHARSET
_DEFAULT_DB
_DEFAULT_LOCKTIME
DEFAUT_D_ECHELLE
DEFAUT_PARTIE
DEFAUT_PARTIE_M
DEFAUT_PARTIE_R
DEFAUT_PARTIE_S
DEFAUT_PARTIE_T
_DEFINIR_CONTEXTE_TYPE
_DELAI_CACHE_resultats
_DIRECT_CRON_FORCE
_DIRECT_CRON_INHIBE
_DIR_AIDE
_DIR_CACHE
_DIR_CACHE_XML
_DIR_CHMOD
_DIR_CONNECT
_DIR_DB
_DIR_DOC
_DIR_DUMP
_DIR_ETC
_DIR_EXTENSIONS
_DIR_IMG
_DIR_IMG_ICONES
_DIR_IMG_ICONES_DIST
_DIR_IMG_PACK
_DIR_JAVASCRIPT
_DIR_LANG
_DIR_LOG
_DIR_LOGOS
_DIR_PLUGINS
_DIR_PLUGINS_AUTO
_DIR_PLUGINS_SUPPL
_DIR_PLUGIN_CFG
_DIR_RACINE
_DIR_RESTREINT
_DIR_RESTREINT_ABS
_DIR_SESSIONS
_DIR_SKELS
_DIR_TMP
_DIR_TRANSFERT
_DIR_VAR
_DOCTYPE_AIDE
_DOCTYPE_ECRIRE
_DOCTYPE_RSS
_DOC_MAX_SIZE
_DUREE_CACHE_DEFAUT

E
E_DEPRECATED
_ECRAN_SECURITE
_ECRIRE_INC_AUXBASE
_ECRIRE_INC_SERIALBASE
_ECRIRE_INC_TYPEBASE
_ECRIRE_INC_VERSION
_ECRIRE_INSTALL
_ESPACE_PRIVE
_EXPORT_TRANCHES_LIMITE
_EXTENSION_PARTIES
_EXTENSION_PHP
_EXTENSION_SQUELETTES
_EXTRAIRE_DOMAINE
_EXTRAIRE_LIEN
_EXTRAIRE_LIENS
_EXTRAIRE_MULTI

F
_FEED_GLOBALS
_FILE_CHMOD
_FILE_CHMOD_INS
_FILE_CHMOD_TMP
_FILE_CONNECT
_FILE_CONNECT_INS
_FILE_CONNECT_TMP
_FILE_LDAP
_FILE_LOG	`spip`	nom du fichier de log (utils.php)
_FILE_LOG_SUFFIX
_FILE_META
_FILE_OPTIONS
_FILE_PLUGIN_CONFIG
_FILE_TMP
_FILE_TMP_SUFFIX
FILE_UPLOAD
_FORUM_LONGUEUR_MAXI
_FUNCTION_ENVOYER_MAIL

G
_GENIE_SYNDIC
_GENIE_SYNDIC_NOW

H
_HEADER_COMPOSED_BY
_HELP_PANNEAU
_HELP_PLACE_IMG

I
_ID_WEBMESTRES
_IMG_GD_MAX_PIXELS
_IMG_GD_QUALITE
_IMG_MAX_HEIGHT
_IMG_MAX_SIZE
_IMG_MAX_WIDTH
_INC_DISTANT_CONTENT_ENCODING
_INC_DISTANT_USER_AGENT
_INC_DISTANT_VERSION_HTTP
_INSTALL_BASE_LDAP
_INSTALL_HOST_DB
_INSTALL_HOST_LDAP
_INSTALL_NAME_DB
_INSTALL_PASS_DB
_INSTALL_PASS_LDAP
_INSTALL_PORT_LDAP
_INSTALL_PROTOCOLE_LDAP
_INSTALL_SERVER_DB
_INSTALL_STATUT_LDAP
_INSTALL_TABLE_PREFIX
_INSTALL_TLS_LDAP
_INSTALL_USER_DB
_INSTALL_USER_LDAP
_INTERDIRE_COMPACTE_HEAD_ECRIRE	false	interdire le compactage des scripts js et css dans le privé
_INTERFACE_DOCUMENTS
_INTERFACE_ONGLETS
_INTERVALLE_REVISIONS
_INTRODUCTION_SUITE
_IS_BOT

J
_JAVASCRIPT
_JS_ADMIN_IE6

K

L
_LARGEUR_ICONES_BANDEAU
_LARGEUR_MODE_IMAGE
_LOCK_TIME
_LOGIN_TROP_COURT
_LOGO_MAX_HEIGHT
_LOGO_MAX_SIZE
_LOGO_MAX_WIDTH

M
MARQUEUR_FSURLIGNE
MARQUEUR_SURLIGNE
_MARQUEUR_URL
_MAX_ART_AFFICHES
MAX_AUTEURS_PAR_PAGE
_MAX_COUPE_URL
_MAX_DEBUG_AFF
_MAX_LOG
_MAX_LONG_URL
_MAX_MOTS_LISTE
_MEMORY_LIMIT_MIN
_MESSAGE_DOCTYPE
_META_CACHE_TIME
MHASH_SHA256
_MYSQL_SET_SQL_MODE
_MYSQL_SQL_MODE_TEXT_NOT_NULL

N
_NAME_LOCK
_NANO_SHA2_UPPER
_NOM_CONFIG
NOM_DE_BOUCLE
NOM_DE_CHAMP
_NOM_IMG_PACK
_NOM_PERMANENTS_ACCESSIBLES
_NOM_PERMANENTS_INACCESSIBLES
_NOM_TEMPORAIRES_ACCESSIBLES
_NOM_TEMPORAIRES_INACCESSIBLES
_NO_CACHE
_NO_HASH_DEFINED

O
_OS_SERVEUR
_OUTILS_DEVELOPPEURS

P
_PERIODE_SYNDICATION
_PERIODE_SYNDICATION_SUSPENDUE
_PNMSCALE_COMMAND
_PROTEGE_BLOCS
_PROTEGE_JS_MODELES
_PROTEGE_PHP_MODELES

Q

R
_RACCOURCI_ANCRE
_RACCOURCI_ATTRIBUTS
_RACCOURCI_BALISE
_RACCOURCI_CHAPO
_RACCOURCI_GLOSES
_RACCOURCI_GLOSSAIRE
_RACCOURCI_LIEN
_RACCOURCI_MODELE
_RACCOURCI_MODELE_ALL
_RACCOURCI_MODELE_DEBUT
_RACCOURCI_NOTES
_RACCOURCI_PROTECTEUR
_RACCOURCI_PROTEGER
_RACCOURCI_TH_SPAN
_RACCOURCI_URL
_REGEXP_CONCAT_NON_VIDE
_REGEXP_COND_NONVIDE_VIDE
_REGEXP_COND_VIDE_NONVIDE
_REGEXP_DOCTYPE
_REGEXP_ENTITY_DECL
_REGEXP_ENTITY_DEF
_REGEXP_ENTITY_USE
_REGEXP_ID
_REGEXP_INCLUDE_USE
_REGEXP_TYPE_XML
_REGEXP_XML
_RENOUVELLE_ALEA
_REPLACE_IMG_PACK
_RESIZE_COMMAND
_ROOT_CWD
_ROOT_EXTENSIONS
_ROOT_IMG_ICONES_DIST
_ROOT_IMG_PACK
_ROOT_PLUGINS
_ROOT_RACINE
_ROOT_RESTREINT
_ROTATE_COMMAND

S
_SAUVER_CHEMIN
_SECTIONS_AIDE
_separateur_urls_page
_SERVER_APACHE
_SET_HTML_BASE
_SIGNALER_ECHOS
SPEC_BOUCLE
_SPIP_AJAX
SPIP_ASSOC
SPIP_BOTH
_SPIP_CHMOD
_SPIP_DUMP
_SPIP_ECRIRE_SCRIPT
SPIP_ERREUR_REPORT
spip_interdire_cache
_SPIP_LOCK_MODE
SPIP_NUM
_SPIP_PAGE
_SPIP_PATH
_SPIP_SCRIPT
_SPIP_SELECT_MAX_AUTEURS
_SPIP_SELECT_MIN_AUTEURS
_SPIP_SELECT_RUBRIQUES
SPIP_SQLITE2_ASSOC
SPIP_SQLITE2_BOTH
SPIP_SQLITE2_NUM
SPIP_SQLITE3_ASSOC
SPIP_SQLITE3_BOTH
SPIP_SQLITE3_NUM
_SPIP_XML_TAG_SPLIT
sql_ABSTRACT_VERSION
SQL_ARGS
_SQL_PREFIXE_TABLE
_SQLITE_CHMOD
_STATUT_AUTEUR_CREATION
_STATUT_AUTEUR_RUBRIQUE
_SUB_REGEXP_SYMBOL
_SYNDICATION_CORRECTION
_SYNDICATION_DEREFERENCER_URL
_SYNDICATION_URL_UNIQUE

T
_TAILLE_MOYENNE_FICHIER_CACHE
_terminaison_urls_arbo
_terminaison_urls_page
_terminaison_urls_propres
_TESTER_NOSCRIPT
_TEST_DIRS
_TEST_EMAIL_DEST
_TEST_FILE_EXISTS
_tmp_dir
_TOURNER_SELON_EXIF
_TRACER_ERREUR_FORUM
_TRAITEMENT_RACCOURCIS
_TRAITEMENT_TYPO
_TRANCHES
_TRANSLITTERER_URL
_TRI_ARTICLES_RUBRIQUE
_TRI_GROUPES_MOTS
TYPE_RECURSIF
_TYPO_BALISE
_TYPO_PROTECTEUR
_TYPO_PROTEGER

U
_UPGRADE_TIME_OUT
_url_arbo_minuscules
_url_arbo_sep_id
_url_minuscules
_url_propres_sep_id
URLS_ARBO_EXEMPLE
_URLS_ARBO_MAX
_URLS_ARBO_MIN
URLS_HTML_EXEMPLE
URLS_LIBRES_EXEMPLE
URLS_PAGE_EXEMPLE
URLS_PROPRES_EXEMPLE
_URLS_PROPRES_MAX
_URLS_PROPRES_MIN
URLS_PROPRES2_EXEMPLE
URLS_PROPRES_QS_EXEMPLE
URLS_STANDARD_EXEMPLE

V
_VERSION_ARCHIVE
_VERSIONS_LISTE
_VERSIONS_SERVEUR

W

X

Y

Z

Balises dynamiques, trucage d'arguments et découpage de l'AST de SPIP

denisb, Thomas Sutton — 2009-11-12T01:03:58Z

Cet article est la traduction libre d'un article de Thomas Sutton publié sur son blog passingcuriosity en mars 2009 (article original).

Attention : depuis la publication de cet article, le code de SPIP a intégré la solution proposée par T. Sutton. Se reporter à la note en fin d'article.

Il arrive parfois que les possibilités offertes par les balises dynamiques ne permettent pas de pallier un petit défaut. C'est le cas lorsque vous avez besoin d'accéder à des détails de l'AST -peut-être le nom du fichier de squelette, peut-être quelque chose d'autre- pour générer votre contenu.

Dans cet article je vais décrire l'évidente (mais mauvaise) méthode de transmission des valeurs dans une balise dynamique et une autre technique qui, elle, fonctionne réellement.

Contrairement aux balises statiques -qui sont mises en œuvre par une seule fonction- les balises dynamiques sont composées d'un ensemble de trois fonctions appelées, si nécessaire, par le moteur de SPIP.

La première de ces trois fonctions (identique à la fonction unique des balises statiques) est appelée balise_TRUC() et a pour but d'appeler les deux autres : balise_TRUC_stat() -qui effectue les calculs statiques nécessaires- et balise_TRUC_dyn() qui effectue les calculs dynamiques et renvoie le contenu final.

Exemple :
Supposons que je crée une balise #HITS, pour afficher le nombre de visites d'un article.
Ma fonction balise_HITS préparera SPIP à appeler les fonctions balise_HITS_xxxxx de la façon suivante :

appel de balise_HITS_stat pour déterminer les paramètres statiques de la balise (par exemple : "id_article = 36").
appel de balise_HITS_dyn en lui passant les paramètres statiques tels que déterminés par balise_HITS_stat
utilisation par balise_HITS_dyn des paramètres statiques pour interroger la base de données, etc et produire la sortie appropriée.

Le code à mettre en œuvre pour la balise #HITS pourrait ressembler à :
function balise_HITS ($p, $nom = 'HITS') { $args = array('id_article'); return calculer_balise_dynamique($p ,$nom ,$args); } function balise_HITS_stat($args, $filtres) { return array($args[0]); } function balise_HITS_dyn($id_article) { $maintenant = date ('c'); return "L'article $id_article a reçu 1 000 000 visites à la date du $maintenant !"; } ?>

Mais ceci ne fonctionnera plus si je veux, par exemple, associer des détails de mon squelette aux paramètres statiques : à l'instant où je détermine les paramètres, je n'ai plus accès au nœud de l'arbre de syntaxe abstraite passé à balise_BIDULE ; tout ce que j'ai reçu à ce moment là, est un tableau d'arguments à passer à la balise et un tableau de filtres à lui appliquer. [1]

La solution évidente (mais fausse)

La solution évidente serait d'ajouter ces valeurs au tableau $args que je passe à calculer_balise_dynamique().
Hélas, cela ne fonctionnera pas parce que $args n'est pas (en dépit de son nom) un tableau d'arguments. C'est, en fait, un tableau des noms des arguments que SPIP est en train de récupérer automatiquement avant de les passer lors de l'appel de balise_xxxxx_stat().

Ajouter le nom du fichier squelette ("squelettes/truc.html" par exemple) à $args demanderait à SPIP de rechercher une variable appelée squelettes/truc.html dans le contexte à l'intérieur duquel la balise est utilisée et de la transmettre à la fonction suivante...
Inutile de dire que cela ne fonctionne pas.

La bonne solution

La bonne solution à ce problème est de prendre des dispositions pour que SPIP ajoute les valeurs que vous voulez au tableau $arguments (ou peut-être au tableau $filtres, mais ce n'est pas forcément une bonne idée).
Ce tableau contient les valeurs que j'ai demandées dans l'appel à calculer_balise_dynamique en plus des valeurs des paramètres passés dans la balise dans le squelette.

« Si je ne peux pas utiliser la route principale, alors je prendrais un chemin de traverse » - j'ai besoin d'ajouter un autre paramètre « truqué » au nœud de l'AST avant d'appeler calculer_balise_dynamique (Oui, je suis d'accord : il s'agit d'une drôle de façon d'arriver à ses fins, mais ça se passe comme çà chez SPIP-land).

Il y a deux parties dans l'AST de SPIP qui sont pertinentes ici : le nœud « Champ » qui représente les balises, et le nœud « Texte » qui représente les chaines (entre autres).
Le $p qui est passé à mes fonctions balise_xxxxx est une instance de la class « Champ » et je vais ajouter une nouvelle instance à la class « Texte » qui sera mon nouveau paramètre « truqué ».

Créer le nouvel objet est assez simple, il suffit de le construire et de définir ses attributs type et texte. L'exemple suivant ajoute ainsi un nouveau paramètre contenant le nom du fichier squelette :
function balise_TEMPLATE ($p, $nom = 'TEMPLATE') { $file = $p->descr['sourcefile']; // Créer le nouvel objet $t = new Texte; $t->type = 'texte'; // (pas vraiment utile : 'texte' est le type par défaut-ndt) $t->texte = $file; // S'assurer que $p-param est un tableau // (aux bonnes dimensions) if (!is_array($p->param)) { $p->param = array(array(0=>NULL)); } // Ajouter l'objet aux paramètres de la balise $p->param[0][] = array($t); // Appel de la balise dynamique $args = array(); return calculer_balise_dynamique($p, $nom, $args); } ?>

En premier lieu, ce code récupère le nom du fichier squelette depuis le nœud de l'AST pour la balise en cours de traitement.
Puis il crée un nouvel objet « Texte » avec ce nom de fichier comme valeur. Il veille à ce que l'attribut $p->param de l'objet « Champ » soit un tableau (et oui, il semble bien qu'il commence avec un NULL de sorte que nous pouvons prétendre que les tableaux démarrent à l'index 1), puis lui ajoute le nouvel objet.
Il ne reste plus qu'à appeler calculer_balise_dynamique comme d'habitude.

Ceci fait, la valeur du nouveau paramètre truqué sera évaluée et transmise, dans le tableau $args, lors de l'appel de balise_TEMPLATE_stat() puis (si c'est mon choix) lors de l'appel de balise_TEMPLATE_dyn().

Conclusion

Cette technique me semble encore un peu bizarre, mais c'est la seule façon que je vois de mettre en œuvre cet effet sans introduire de variables globales.

À mon avis, calculer_balise_dynamique devraient pouvoir prendre un tableau de valeurs comme quatrième argument facultatif, mais le besoin de faire ce genre de chose est probablement assez rare (bien que je l'ai vu dans le code pour une ou deux balises). [1]

Mais si cette technique était la « Right Way™ » pour passer des valeurs supplémentaires, alors il serait vraiment nécessaire d'avoir une fonction auxiliaire comme interprete_argument_balise plutôt que de pourrir l'AST pour chaque balise qui en a besoin.

[1] Important
note du traducteur :

Depuis la publication de cet article, les balises dynamiques peuvent utiliser désormais un second argument : un tableau de valeurs qui leur permet , si besoin est, de manipuler à l'exécution des valeurs qui ne sont connues que durant la compilation.
Ce tableau est composé d'abord de cinq valeurs issues du contexte de compilation (nom du squelette, nom du fichier compilé, nom de la boucle éventuelle où figure la balise, numéro de ligne, langue) suivies éventuellement des éléments du tableau optionnel fourni comme quatrième argument à la fonction calculer_balise_dynamique().
(voir cette fonction...)

Créer des balises personnalisées pour SPIP - Les balises dynamiques

denisb, Thomas Sutton — 2009-11-12T00:47:39Z

Cet article est la traduction libre d'un article de Thomas Sutton publié sur son blog passingcuriosity en mars 2009 (article original).

La plupart des sites web modernes propose aujourd'hui du contenu dynamique : depuis les listes d'utilisateur « actuellement en ligne » à la publicité ciblée, en passant par les widgets de données temps réel, le dynamisme est bien le slogan d'accroche du Web 2.0.

Pour ajouter des éléments dynamiques de ce genre à votre site SPIP, vous n'aurez qu'à user de sa capacité d'utilisation des balises dynamiques (ou à ajouter des rustines en PHP, mais alors quel est l'intérêt d'un squelette ?).
Dans cet article je vais décrire les balises dynamiques de SPIP et expliquer comment en créer des personnelles.

Les balises dynamiques de SPIP

SPIP est assez complexe et sa conception et mise en œuvre rendent très coûteuse la génération des pages.
Pour que le coût de cette génération ne le rende pas complètement inutilisable, SPIP intègre un mécanisme de cache pour servir plus rapidement les demandes. Si ce processus, qui permet de générer et d'afficher une page, est un peu plus complexe dans SPIP que dans la plupart des systèmes, heureusement il ne l'est pas trop :

Brièvement, et en simplifiant, ce processus se présente comme suit :

Parser le squelette à travers un arbre de syntaxe abstraite (AST)
Évaluer la partie statique de l'AST
Générer le code PHP pour le calcul des parties dynamiques au moment de l'exécution
Mettre en cache ce code pour les requêtes futures
Évaluer ce code et envoyer [1] le source HTML au client.

// traitement de la balise #EXEMPLE_DYNAMIQUE. function balise_EXEMPLE_DYNAMIQUE ($p) { $args = array(); return calculer_balise_dynamique ( $p, // le nœud AST pour la balise 'EXEMPLE_DYNAMIQUE', // le nom de la balise $args // les éléments utilisables de ); // l'environnement } // déterminer les paramètres de la balise statique #EXEMPLE_DYNAMIQUE. // les arguments de la balise et les filtres appliqués à celle-ci // sont transmis en tant qu'arguments de cette fonction. function balise_EXEMPLE_DYNAMIQUE_stat ($args, $filtres) { // calcul de la date et l'heure ... $maintenant = date ('Y-m-d H:i:s'); // retourne les arguments à passer aux appels dynamiques... return array($maintenant); } // calcul des valeurs dynamiques à retourner. // le tableau des valeurs retourné par balise_EXEMPLE_DYNAMIQUE_stat // est passé dans les arguments. function balise_EXEMPLE_DYNAMIQUE_dyn ($autrefois) { // Déterminer l'heure actuelle. $maintenant = date('Y-m-d H:i:s'); // Retourner un message contenant la valeur de balise_EXEMPLE_DYNAMIQUE_stat // et la valeur que nous venons de générer. $s = "Page générée le : $autrefois Maintenant : $maintenant"; return $s; } ?>

Explications :
lorsque nous utilisons #EXEMPLE_DYNAMIQUE dans un squelette, SPIP rassemble toutes les valeurs que nous avons demandées dans $args (rien dans l'exemple ci-dessus), et les transmet à balise_EXEMPLE_DYNAMIQUE_stat ; puis, à partir du tableau retourné par cet appel, une portion de code est générée (par exemple : "balise_EXEMPLE_DYNAMIQUE_dyn('2008-12-01 22:22:22')" qui s'insére dans le code PHP généré par l'AST.

Ajout d'une interface utilisateur

Étant donné le mal que ses développeurs se sont donné pour permettre à SPIP d'être si facile à personnaliser, il serait ridicule que les retours des balises dynamiques soient limités à l'affichage d'une chaîne de caractères.
Heureusement, ils ne le sont pas.

Les balises dynamiques peuvent aussi renvoyer un tableau de données utilisables pour trouver, analyser et retourner un squelette avec du contenu dynamique.
Plutôt que de modifier le code qui implémente une balise, les web-masters peuvent simplement créer un nouveau squelette dans leur dossier squelettes/ qui surchargera celui par défaut, produisant ainsi les résultats qu'ils désirent.

Lors de l'utilisation de cette fonctionnalité, la fonction balise_xxxxx_dyn() retourne un tableau contenant trois éléments :

le nom du squelette à évaluer ;
le temps durant lequel le résultat peut être mis en cache [2] ;
le tableau des données de l'environnement (#ENV) à passer au squelette.

L'exemple précédent, modifié pour être utilisé dans un squelette, peut alors ressembler à ceci :
function balise_EXEMPLE_DYNAMIQUE_dyn($then) { $now = date('Y-m-d H:i:s'); $env = array( 'autrefois' => $autrefois, 'maintenant' => $maintenant ); return array('formulaires/dynamic_exemple', 0, $env); } ?>

Avec un modèle nommé squelettes/formulaires/dynamic_exemple.html rédigé ainsi :

Page générée le : #ENV(autrefois) 


Maintenant : #ENV(maintenant)

[1] SPIP a également fait une deuxième mise en cache ici, mais nous allons l'ignorer pour le moment...

[2] Ceci est pour la deuxième mise en cache (voir note 1)

voir aussi Créer des balises personnalisées pour SPIP - Les balises statiques

Créer des balises personnalisées pour SPIP - Les balises statiques

denisb, Thomas Sutton — 2009-11-12T00:32:54Z

Cet article est la traduction libre d'un article de Thomas Sutton publié sur son blog passingcuriosity en novembre 2008 (article original).

Intéressons-nous à deux des types d'éléments offerts par le language utilisé dans les squelettes de SPIP :

les boucles (qui déterminent les objets desquels seront extraites les données)
les balises (qui retournent les données particulières).

La syntaxe extrêmement simple de ces balises, pour la plupart notées #BALISE, masque leur puissance, leur flexibilité et la simplicité avec laquelle il est possible de les utiliser pour étendre SPIP en lui ajoutant de nouvelle fonctionnalités ou en l'interfaçant avec d'autres applications PHP.

Dans cet article, nous allons décrire comment créer nos propres balises statiques SPIP.
Avant de lire cet article, vous devez être familier avec SPIP, ses squelettes et la programmation en PHP.

Une balise SPIP est utilisée pour retourner une valeur.

La plupart des balises tirent cette valeur du contexte dans lequel elles sont appelées : le titre de l'article « courant », ou le logo de la brève « courante » par exemple.
Certaines retournent des valeurs globales comme le nom du site, ou la version du logiciel.
D'autres encore permettent aux utilisateurs d'interagir avec le site (par exemple #LOGIN_PUBLIC qui affiche un formulaire de connexion et en lance le processus).
Quelques-unes enfin (comme #SET et #GET) offrent les possibilités d'un langage de programmation et l'on pourrait ne voir leur capacité à afficher des valeurs que comme un effet secondaire.

Toutes ces possibilité sont offertes en utilisant une même syntaxe, relativement simple, et un même mécanisme.

Les balises peuvent être rangées dans deux groupes en fonction de leur comportement :

les balises statiques sont celles qui retournent une valeur statique, qui ne changera pas d'une évaluation à l'autre. Le titre d'un article, par exemple, n'a pas nécessairement besoin d'être différent d'une page à l'autre ; il peut l'être, certes, mais pas nécessairement.
Les balises dynamiques sont celles qui génèrent des valeurs dynamiques qui, elles, doivent nécessairement changer entre les différents appels ; la date et l'heure, par exemple.

les balises statiques

Les balises statiques génèrent un contenu « statique » ; c'est à dire une valeur qui ne devrait pas changer sur une période donnée.
Cela signifie que SPIP peut évaluer une balise statique une fois, en cacher le résultat et le réutiliser plus tard à l'occasion de demandes ultérieures.

Une balise (désormais dans cet article nous utiliserons « balise » pour « balise statique ») renvoie à une fonction [1] portant un nom particulier : le nom de la balise accolé au préfixe « balise_ ».
Par exemple, une balise nommée #TRUC sera exécutée par une fonction appelée function balise_TRUC().
Ces fonctions, comme un grand nombre de celles utilisées par SPIP, peuvent être surchargées par des plugins, ou d'autres fichiers spécifiques au site. En effet, quand il voit une balise #TRUC, SPIP va d'abord rechercher la fonction balise_TRUC puis, s'il ne la trouve pas, la fonction balise_TRUC_dist puis, enfin, considèrera que la dite balise n'existe pas.

Mais commençons par un exemple trivial : la balise #BONJOUR_VOUS.
Cette balise affichera tout simplement la phrase : « Bonjour tout le monde ! » (Pour utiliser ce code, il suffit de copier la fonction dans votre fichier mes_fonctions.php de votre installation SPIP) :
function balise_BONJOUR_VOUS ($p) { $p->code = "'Bonjour tout le monde !'"; return $p; } ?>

Comme vous pouvez le voir il y a quelques détails en plus du nom ; à savoir : ce $p quelque chose.
Ce paramètre $p de la fonction qui met en œuvre la balise est une référence au nœud de l'arbre de syntaxe abstraite correspondant pour cette balise. Ce paramètre $p contient toutes les informations que SPIP possède sur la balise : les filtres qui lui sont passés, les parenthèses qui l'entourent, le contexte, etc. Tout ce qui manque, c'est la valeur elle-même, et c'est là que notre fonction entre en scène.
Une fois que SPIP a analysé les squelettes et manipulé tout ce qu'il peut, il appelle donc la fonction associée à chaque balise pour remplir les trous.

Il y a un grand nombre de champs dans l'objet Champ (la classe est définie dans ecrire/public/interfaces.php mais sa lecture n'est pas particulièrement édifiante), et la plupart sont peu documentés :

type	la chaîne de caractères décrivant le type de nœud AST. Devrait être « champ » pour les balises.
nom_champ	le nom de la balise sans le « # »
nom_boucle	le nom de la boucle. Les balises n'étant pas des boucles, il sera donc vide dans notre exemple.
avant	la liste des nœuds précédents qui sont subordonnés à celui-ci.
apres	la liste des nœuds suivants subordonnés à celui-ci.
etoile	la balise appelée par « #BONJOUR_VOUS* » renverrait un résultat brut, sa valeur n'étant pas sécurisée pour un affichage HTML.
param	la liste des paramètres et des filtres associés à l'appel de la balise. C'est un peu compliqué.
fonctions	semblable à param mais structuré différemment.
id_boucle	le nom de la boucle au sein de laquelle apparait la balise.
boucles	le tableau des nœuds AST pour les boucles du squelette.
type_requete	aucune idée. [2]
code	le code PHP, qui, lors de eval()d, génère la valeur de la balise.
interdire_scripts	autorise ou non l'interprétation de "scripts". [3]
descr	le tableau des valeurs décrivant le nœud AST, le fichier dont il est issu, etc.
ligne	le numéro de la ligne d'où la balise est appelée dans le squelette.

Exemple :
si l'on remplaçait le contenu de squelettes-dist/sommaire.html par :
[d'abord (#BONJOUR_VOUS{arg1}|strtoupper) ensuite]
cela devrait se traduire par l'AST suivant, transmis donc à la fonction balise_BONJOUR_VOUS :

type	=>	"champ"
nom_champ	=>	"BONJOUR_VOUS"
avant	=>	le (ou les) nœud pour "d'abord", ...
apres	=>	le (ou les) nœud pour "ensuite", ...
etoile	=>
param	=>	[ 0 => "arg1" est là, ... 1 => "strtoupper" est là, ... ]
fonctions	=>	[ 0 => arg1" est aussi ici, ... 1 => strtoupper" est aussi ici, ... ]

Heureusement, vous pouvez ignorer la quasi-totalité de ceci.

La fonction interprete_argument_balise

Cette fonction (détaillée ici) est particulièrement utile :
interprete_argument_balise(1, $p) retourne le premier argument du nœud AST $p.

Avec ce que nous avons décrit jusqu'ici, nous en savons assez pour écrire notre balise #BONJOUR qui affichera le message « Bonjour nom » s'il y a un nom (#BONJOUR{Marcel}) et « Bonjour le monde ! » sinon (code à placer dans mes_fonctions.php ) :
function balise_BONJOUR ($p) { $name = interprete_argument_balise (1, $p); if (!$name) { $name = "le monde !"; } $p->code = "'Bonjour '.$name "; return $p; } ?>

Comme il y a bien des raisons d'écrire ses propres balises statiques, il faut être assuré (comme pour tout le reste, d'ailleurs) qu'elles prendront bien en charge les traductions, surtout si vous envisagez de distribuer votre travail.

Cela est relativement facile à l'aide de la fonction _T (voir le détail ici) et des fichiers de langue.
Tout comme il est aisé d'obtenir des données à partir d'une boucle (titres d'article, identifiants de rubriques, etc) avec la fonction champ_sql (voir le détail ici).

Pour encore plus d'exemples, n'hésitez pas à jeter un œil sur le code de certaines des balises de SPIP dans le fichier ecrire/public/balises.php.
Et si vous regardez attentivement le code source de SPIP, vous verrez que beaucoup de balises ne tirent pas leur résultat du mécanisme détaillé ci-dessus, mais l'extraient des colonnes de même nom de la base de données.
Si vous modifiez ou complétez votre base de données vous pourrez ainsi en tirer parti.

[1] En un sens, ce n'est pas tout à fait vrai : la fonction, pour cette balise, ne fait qu'utiliser un nœud de l'arbre de syntaxe abstraite (AST), dont les éléments seront ensuite traités par SPIP pour générer la balise.

[2] pour une balise, contient le plus souvent le nom de la table sur laquelle porte la boucle englobant cette balise ; pour une boucle : le nom de la table [ajout du traducteur].

[3] en désactivant les fonctions de désinfection de spip appliquées sur le contenu de la balise [ajout du traducteur].

voir aussi Créer des balises personnalisées pour SPIP - Les balises dynamiques

API-autoriser_*

Teddy Payet — 2009-09-03T22:39:19Z

Les fonctions de l'API autoriser_*

Fonction	Paramêtres	Lien doc	Lien code	Lien fichier
autoriser_article_modifier_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_auteur_modifier_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_auteur_previsualiser_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_breve_modifier_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_chargerftp_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_configurer_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_debug_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_defaut_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_detruire_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_dist	$faire $type='' $id=0 $qui = NULL $opt = NULL	doc	code	autoriser.php
autoriser_document_modifier_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_document_voir_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_ecrire_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_exception	$faire $type $id $autoriser=true	doc	code	autoriser.php
autoriser_groupemots_creer_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_groupemots_modifier_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_joindredocument_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_modifierurl_dist	$faire $quoi $id $qui $opt	doc	code	autoriser.php
autoriser_mot_modifier_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_niet_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_ok_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_previsualiser_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_rubrique_creerarticledans_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_rubrique_creerbrevedans_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_rubrique_creerrubriquedans_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_rubrique_creersitedans_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_rubrique_modifier_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_rubrique_publierdans_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_sans_cookie	$nom	doc	code	utils.php
autoriser_sauvegarder_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_site_modifier_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_site_voir_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_voir_dist	$faire $type $id $qui $opt	doc	code	autoriser.php
autoriser_webmestre_dist	$faire $type $id $qui $opt	doc	code	autoriser.php

API-format_*

Teddy Payet — 2009-07-29T16:05:05Z

Les fonctions de l'API format_*

Fonction	Paramêtres	Lien doc	Lien code	Lien fichier
format_mysql_date	$annee=0 $mois=0 $jour=0 $h=0 $m=0 $s=0	doc	code	date.php

API-f_*

Teddy Payet — 2009-07-29T16:03:08Z

Les fonctions de l'API f_*

Fonction	Paramêtres	Lien doc	Lien code	Lien fichier
f_admin	$texte	doc	code	assembler.php
f_boite_infos	$flux	doc	code	presentation.php
f_insert_head	$texte	doc	code	assembler.php
f_jQuery	$texte	doc	code	filtres.php
f_surligne	$texte	doc	code	assembler.php
f_tidy	$texte	doc	code	assembler.php