SPIP

SPIP 3.0

cerdic, tetue — 2012-05-19T11:00:00Z

SPIP 3 : une nouvelle version marquée par la réécriture complète de l'espace privé en squelettes, une forte modularisation et une boucle DATA révolutionnaire.

SPIP 2.0 avait apporté les fonctionnalités permettant de l'utiliser comme un « framework » pour le développement d'applications Web, au-delà de sa vocation initiale de simple outil de publication.

SPIP 3 pousse la logique du « framework » jusqu'à se l'appliquer à lui-même : l'ensemble de l'espace privé de SPIP a été recodé en squelettes, sur la base des outils et fonctions proposés par le langage de squelettes de SPIP.

Cette remise à plat de l'espace privé a été l'occasion de repenser le fonctionnement des objets éditoriaux et de normaliser leur usage pour le rendre le plus générique possible : la plupart des particularités historiques de chaque objet (et les exceptions de traitement associées dans le code de SPIP) ont été gommées pour être ramenées à une simple déclaration.

La création de nouveaux objets éditoriaux et la personnalisation des objets existants deviennent ainsi beaucoup plus faciles et plus rapides.

SPIP 3 achève également la découpe du logiciel en plugins comme SPIP 2 l'avait amorcé : l'ensemble des fonctionnalités proposées par SPIP 2 repose dorénavant sur un noyau SPIP 3 accompagné de 23 plugins.

La découpe complète du noyau a permis de compléter ses API et points d'entrée pour les développeurs de plugins.

SPIP 3 se nourrit fortement des développements de la communauté SPIP-Zone, et marque une forte inversion : ce n'est plus le noyau qui tire les développements des plugins, mais les développements de plugins qui nourrissent l'avancée de SPIP par leurs expérimentations [1].

Parmi de nombreuses autres nouveautés fonctionnelles, SPIP 3 introduit une nouvelle boucle DATA qui permet enfin de boucler sur tout type de données et plus seulement sur les tables SQL. Il devient ainsi possible de parcourir soit une énumération, soit un fichier CSV, XML, YAML... Plus fort encore, la boucle DATA permet directement de boucler sur une URL : il devient possible de parcourir directement une feuille de calcul Google Spreadsheet, un calendrier en ligne, une liste de vidéos sur Youtube, des photos sur Flickr… le Web devient votre base de données !

Prérequis :
SPIP 3.0 requiert désormais au minimum une version 5.1.0 de PHP pour pouvoir fonctionner correctement.

Un nouvel espace privé [2]

Visuellement, l'espace privé demeure dans la continuité des versions précédentes, complétée de nouvelles icônes, avec :

pour les icônes principales de navigation, un jeu spécifique réalisé pour SPIP par Sébastien Desbenoît,
pour le reste de la page, l'adoption d'un jeu dérivé de FatCow.

La refonte de l'interface est essentiellement technique, même si elle a également permis de résoudre un certain nombre de défauts ergonomiques historiques.

La navigation principale est repensée et réorganisée. Le menu déroulant, désormais entièrement navigable au clavier, intègre aussi des temporisations pour faciliter son utilisation à la souris et être plus robuste aux mouvements mal contrôlés.

L'ensemble de l'espace privé est donc réécrit sous forme de squelettes rangés dans le répertoire prive/squelettes organisés par sous-dossiers correspondants à un découpage de la page en blocs. Ce découpage est utilisé notamment pour le rafraîchissement des morceaux de page en Ajax, évitant le rechargement complet des pages et fluidifiant les interactions [3].

De nombreux points d'entrée (utilisés en premier lieu par les plugins du noyau) sont disponibles sous forme de pipeline pour permettre aux plugins d'étendre les fonctionnalités de l'espace privé.

Les pages de l'espace privé sont réorganisées et renommées. En particulier toutes les pages d'objets éditoriaux utilisent un nommage cohérent fondé sur le nom de l'objet.

La réécriture a également permis de remettre à niveau la structure complète du HTML et son accessibilité. Un référentiel a été mis en place pour que les développeurs de plugins puissent réutiliser les mêmes structures, et que les ajouts d'interface restent homogènes avec le noyau.

Toutes les listes d'objet sont des squelettes qu'il devient facile de personnaliser. Elles bénéficient toutes du tri par colonne et de pagination ajax.

Un système d'échafaudage des pages d'objet permet de construire automatiquement une interface minimale pour les nouveaux objets déclarés par les plugins. Chaque élément de cette interface par défaut peut ensuite être personnalisé en fonction des particularités de chaque objet : [4].

Tous les formulaires interactifs sont écrits sous forme de formulaires CVT, ce qui permet d'assurer des interactions de qualité avec gestion systématique des messages d'erreur, vérification de saisie, ajax robuste à volonté, saisie multipage si nécessaire… Ils sont ainsi tous facilement extensibles par les plugins.

Autre nouveauté, en mode édition SPIP 3 prend en compte le retour à la ligne simple (il n'est désormais plus nécessaire d'utiliser « _ »).

Enfin, l'espace privé intègre un mécanisme technique de thèmes qui permet de personnaliser les feuilles de style ou tout ou partie des icônes. Ce mécanisme pourra être utilisé par un plugin proposant des variantes activables par chaque utilisateur en fonction de ses préférences.

Modularisation en plugins

SPIP 3 achève donc la découpe du logiciel en plugins. Son noyau conserve la gestion des articles, rubriques et auteurs ; le langage de squelettes et l'ossature de l'espace privé. Toutes les autres fonctionnalités sont externalisées dans des plugins, automatiquement installés dans la distribution par défaut de SPIP 3. Ces plugins fournis par défaut sont désormais placés dans un dossier plugins-dist/ [5]

Cette découpe du noyau a permis de compléter un certain nombre d'API implicites, maintenant à disposition des développeurs de plugins qui peuvent ainsi ajouter des fonctionnalités sans limite, en prenant modèle sur les plugins natifs de SPIP.

Dans le domaine des plugins, SPIP 3 amène également une refonte importante du formalisme de déclaration XML. Outre une lisibilité améliorée, cette évolution intègre la question des traductions de plugins, ainsi que les outils d'alimentation automatique d'un annuaire des plugins de SPIP et un outil de chargement.

Par ailleurs, les plugins peuvent bénéficier des fonctions de mise à jour de base de données du core (avec reprise sur timeout) par simple déclaration de la procédure.

Les plugins distribués par défaut avec SPIP sont :

Brèves s'occupe de l'objet éditorial Brèves.
Compagnon propose l'affichage de textes pédagogiques d'information et d'accompagnement lors des premiers accès à l'espace privé.
Compresseur déjà présent dans SPIP 2.1, prend en charge l'optimisation des performances du site en compressant et concaténant les feuilles de style CSS et les fichiers JavaScript embarqués dans la page. Cette version du plugin améliore des feuilles par média. Utilisation de @media pour concaténer tous les médias en un seul fichier sans en modifier l'ordre de chargement. Gestion des urls absolues sans protocole pour que les feuilles de style compressées fonctionnent sur http et https.
Dump assure la gestion des sauvegardes et restaurations. La fonctionnalité a été complètement ré-écrite pour assurer une sauvegarde complète et fiable. Le format de sauvegarde est maintenant SQLite et toutes les tables sont systématiquement conservées.
Forum gère l'objet éditorial forum, tant pour le site public que pour les interactions éditoriales dans l'espace privé. Outre une interface de modération repensée, les forums sont maintenant utilisables sur tous les objets éditoriaux de SPIP (natifs ou ajoutés par des plugins).
Images, déjà dans SPIP 2.1, prend en charge tous les filtres d'images et de couleurs dans les squelettes.
jQuery UI implémente dans SPIP la librairie complémentaire. jQuery UI facilite la création de composants graphiques dynamiques : onglets, drag & drop, barres de progression, widgets, effets…
Mediabox intègre dans SPIP par défaut une boîte pop-in pour visualiser les médias ou proposer des interactions [6].
Medias [7] prend en charge la gestion des documents et images. Il propose une refonte de l'interface et rend les documents utilisables sur n'importe quel objet éditorial.
Mots apporte la gestion des mots-clés et groupes de mots. Les mots-clés sont maintenant utilisables sur tous les objets éditoriaux.
Organiseur assure les fonctions de messagerie et calendrier interne de l'espace privé. L'interface est complètement refondue. La messagerie interne bénéficie de notification par email, et le calendrier repose sur la librairie FullCalendar qui permet une navigation fluide.
Pétitions gère les pétitions sur articles et propose une interface de modération repensée.
Porte plume, déjà dans SPIP 2.1, assure l'aide à la saisie.
Révisions assure le versionage utilisable sur tous les objets éditoriaux de SPIP. L'interface de gestion des révisions est modernisée.
SafeHTML, déjà dans SPIP 2.1, prend en charge la sécurisation des contenus externes potentiellement dangereux.
Sites assure le fonctionnement de l'objet éditorial « Site syndiqué » ainsi que des articles syndiqués. Une interface de modération des articles syndiqués est proposée.
Squelettes par rubriques assure le fonctionnement des squelettes suffixés (article-2.html pour les articles de la rubrique 2).
Statistiques assure le calcul des statistiques du site et des articles, et propose un affichage complètement refondu.
Support vieux navigateur, déjà dans SPIP 2.1, propose des fonctions JavaScript activables pour permettre aux vieilles versions de navigateurs d'afficher correctement votre site.
Svp permet la gestion complète des plugins : installation, activation, mise à jour, recherche…
Textwheel est un moteur typographique qui supporte intégralement les raccourcis de SPIP, décrits désormais dans un fichier de règles au format YAML. Ce moteur permet une nette accélération du traitement des raccourcis (jusqu'à 2 fois plus rapide sur certains contenus), et facilite l'évolution et la personnalisation des raccourcis.
Urls Étendues supporte les URLs propres ou arborescentes, et propose une interface de configuration ainsi qu'une interface de gestion avancée optionnelle pour gérer finement les URLs de chaque page.
Vertèbres, déjà dans SPIP 2.1, permet au webmestre d'afficher le contenu d'une table SQL de SPIP au moyen d'un squelette généré automatiquement d'après la structure SQL de la table. Cet affichage se fait maintenant dans l'espace privé.

Un nouveau jeu de squelettes par défaut

Pour marquer le coup, les squelettes par défaut ont été révisés. Par la répartition en plusieurs feuilles de styles ré-utilisables indépendamment (méthode Daisy, cf. Un, deux, trois… feuilles CSS !), ils constituent désormais un cadre de travail HTML/CSS modulaire, immédiatement utilisable pour démarrer un site. Ils proposent notamment un traitement typographique complet et harmonieux, inspiré du framework Blueprint. L'historique spip_style.css disparaît au profit de spip.css, qui peut être utilisée en complément de votre framework habituel.

Les squelettes adoptent une nouvelle structure HTML de base qui anticipe le HTML5, "responsive" par défaut, et embarque des sélecteurs conditionnels pour plus de souplesse CSS.

De nouvelles fonctionnalités

Le support de SQLite a été nettement amélioré, et c'est le format de base de données proposé par défaut lors d'une nouvelle installation (quand il est supporté par le serveur), compte tenu de sa simplicité de mise en œuvre [8].

La gestion des objets éditoriaux est généralisée. Par suite, les auteurs, documents, mots-clés, forums, révisions et logos sont utilisables sur n'importe quel objet (tous ceux de SPIP mais aussi tout objet éditorial ajouté par un plugin avec la nouvelle API de déclaration).
La gestion du statut, de la date de publication, de la langue et de la traduction est également généralisée et utilisable sur tout objet par simple déclaration.
Lorsque le signalement de l'édition concourante est activé, tout objet édité est désormais pris en compte dans le signalement.

L'identité du site est complétée d'un slogan du site, entre titre et descriptif long, utilisable avec la balise #SLOGAN_SITE_SPIP.

L'écran de sécurité est intégré en standard.

Les logs (fichiers de trace) bénéficient d'une gestion par niveau d'importance. Par défaut, les logs sont beaucoup moins verbeux en production et ne signalent que les anomalies ou informations importantes. Le niveau de log peut être ajusté pour le debug ou le développement, permettant ainsi d'avoir toutes les informations nécessaires.

Le cron périodique qui reposait sur des fichiers a été supprimé au profit d'une file de tâches en attente (qui gère aussi les tâches périodiques). Cette file de tâches permet de programmer des actions asynchrones [9] et propose une API simple d'utilisation pour les développeurs de plugin.

L'ajax des squelettes ({ajax} sur les INCLURE) bénéficie d'une prise en charge des attributs ARIA pour améliorer son accessibilité. De plus, l'historique de navigation est aussi automatiquement pris en charge grâce à l'API « History » de HTML5 [10]. L'URL du navigateur est donc mise à jour automatiquement sur les liens ajax, et permet les retours en arrière sans soucis.

Les modèles utilisés dans du texte éditorial reçoivent automatiquement l'environnement du squelette dans lequel est affiché le texte [11].

Les formulaires des l'espace privé utilisent les possibilités de HTML5 avec par exemple les attributs required ou placeholder.

Les squelettes peuvent maintenant échapper les caractères # [ ] ( ) { } < > en utilisant une barre oblique \. Il devient possible d'écrire des conditions par exemple sur une case à cocher de formulaire de manière bien plus élégante, sans que les crochets de l'attribut name n'interfèrent avec les crochets de la balise englobante :

[(#ENV{param}|oui)
Avec tendresse ?
]

Raccourcis

Un raccourci pour les abréviations a été introduit nativement : [SNCF|Société Nationale des Chemins de fer Français] (ou [CMS|Content Management System{en}]) pour indiquer une langue différente du texte principal) génère une balise abbr [12].

Les modèles de document peuvent prendre en argument la largeur ou la hauteur pour réduire leur dimension : .

Les tableaux à 2 entrées (horizontale et verticale) sont désormais gérés correctement.

Il n'est désormais plus nécessaire d'utiliser le raccourci « _ » pour produire un retour ligne simple.
Pour retrouver le fonctionnement antérieur, ce nouveau comportement est débrayable en utilisant un define('_AUTOBR', ''); dans son fichier mes_options.php.

Boucles

Le système de boucles de SPIP a été généralisé pour s'appliquer non plus directement sur une table SQL mais sur un itérateur. Un itérateur SQL assure le fonctionnement historique des boucles sur les tables SQL, mais il devient possible de boucler sur toute donnée itérable : Les itérateurs de SPIP

Premier exemple de nouvelle application : la boucle DATA étend le fonctionnement des boucles à toute information structurée sous forme de tableau. Il devient possible de boucler sur un fichier CSV, sur une url distante qui renvoie une information en JSON... :

Pour assurer la migration facile des squelettes qui utilisaient des boucles POUR et CONDITION, celles-ci sont également supportées comme cas particuliers de la boucle DATA, dans la même syntaxe que celle qui existait.

Critères

{si ...} : permet de conditionner l'exécution d'une boucle à la condition exprimée dans le critère, qui ne dépend pas des données en base mais du contexte du squelette.

{tri ...} : associé à la balise #TRI pour des tris faciles.

{feuille} : permet de sélectionner les rubriques sans enfants (celles tout en bas de la hiérarchie).

{noeud} : permet de sélectionner les rubriques qui ont des enfants.

{!racine} : exclut les rubriques de la racine.

{profondeur=3} : permet de sélectionner les rubriques du 3e niveau (la racine est le niveau 0, les rubriques secteurs sont le niveau 1, puis les rubriques du dessous le niveau 2 etc ...).

Balises

Les modèles peuvent avoir un cache s'ils contiennent une balise #CACHE (mais par défaut ils n'en ont pas, comme auparavant).

Dans l'espace privé, les squelettes n'ont pas de cache non plus, sauf si une balise #CACHE est présente.

#LOGO_DOCUMENT peut prendre en argument le mode d'affichage du logo :

auto (par défaut, et c'est le fonctionnement historique) affiche automatiquement la vignette du document si existante, sinon un aperçu ; et sinon l'icône correspondant au type de document.
icone indique que c'est l'icône correspondant au type du fichier qui doit être affichée
apercu affiche un aperçu de l'image exclusivement, même si une vignette existe.
vignette affiche la vignette du document si elle existe, ou sinon rien.

La balise #SPIP_CRON disparaît et n'a plus d'effet dans les squelettes où elle serait encore utilisée.

#BOUTON_ACTION{libellé, url, classe, confirm, title, callback} génère un mini formulaire HTML avec un seul bouton qui affiche « libellé » et déclenche au clic un POST vers « url ». Cette balise est à utiliser de préférence à un lien quand la page « url » modifie la base de données. Si la « classe » contient la valeur « ajax » le bouton déclenchera un rechargement du bloc ajax qui l'inclue. « confirm » permet d'indiquer un message pour faire confirmer l'action par l'utilisateur, « title » le contenu de l'attribut homonyme sur le bouton, et « callback » une fonction javascript à appeler lors du clic sur le bouton.

#INFO_XXX{article, 13} : permet de retrouver le #XXX sans faire une boucle ARTICLES sur l'article 13 (utilisable pour toute boucle et tout champ de la boucle : #INFO_TITRE{article,13}, #INFO_NOM{auteur,2}...)

#CONFIG{nom} permet d'afficher la valeur de la meta de configuration nom.
Si la meta est un tableau, il est possible d'accéder directement à des sous valeurs avec la syntaxe #CONFIG{nom/sousvaleur} qui renverra la sousvaleur de la meta nom.
Pour accéder à la meta d'une table spécifique à un plugin, il faut utiliser la syntaxe #CONFIG{/metamonplugin/nom} : en commençant par un /, on indique que l'on veut la meta nom de la table spip_metamonplugin au lieu de la table spip_meta de SPIP.
Dans tous les cas, il est possible d'indiquer en second argument la valeur par défaut qui doit être utilisée si la meta n'existe pas encore : #CONFIG{nom,valeurpardefaut}

À l'instar de #CONFIG{nom/sousvaleur} les balises #ENV, #GET, #SESSION permettent d'utiliser des barres obliques pour obtenir des sous valeurs de tableau tel que :#ENV{nom/sousvaleur}, #GET{tableau/cle/souscle}, #SESSION{prefs/couleur}.

#PUBLIE : pour tester l'état (publié ou non) d'un objet. S'utilise dans une boucle, porte implicitement sur l'objet en cours ou avec des arguments explicites : [(#PUBLIE{article, 3}|oui) ... ], sur tout autre objet.

#CLE et #VALEUR sont les deux balises qui permettent d'afficher la clé et la valeur dans une boucle DATA
#VALEUR{x} permet d'afficher la sous valeur de x si #VALEUR est un tableau (équivalent à [(#VALEUR|table_valeur{x})]). On peut enchaîner plusieurs sous index #VALEUR{x/y/z} pour afficher une valeur dans un sous-niveau du tableau.

#PRODUIRE : renvoie le nom d'un fichier statique produit à partir d'un squelette. Utile pour une feuille de style calculée ou un fichier javascript calculé. La syntaxe est la même que pour la balise #INCLURE : #PRODUIRE{fond=mafeuille.css,couleur=ffffff} pour utiliser le squelette mafeuille.css.html

#LISTE{a,b,c} renvoie simplement un tableau contenant les valeurs a,b et c. C'est une écriture simplifiée de #ARRAY{0,a,1,b,2,c}.

#TOTAL_UNIQUE renvoie le nombre d'éléments affichés par l'intermédiaire du filtre |unique. Si on utilise |unique{nom}, il faut faire référence au même nom dans la balise : #TOTAL_UNIQUE{nom}

Dans l'espace privé :

#AIDER{surtitre} permet d'afficher un lien vers la section surtitre de l'aide de SPIP.

#BOITE_OUVRIR, #BOITE_PIED et #BOITE_FERMER permettent d'utiliser les boites stylées de l'espace privé :

#BOITE_OUVRIR{titre,classe} ouvre une boîte. le titre peut être omis. Les classes stylées dans l'espace privé sont : simple, info, note, raccourcis et important ;
le HTML qui suit est inclus dans la boîte ;
#BOITE_PIED permet de passer au pied de la boîte quand un pied est nécessaire.
#BOITE_FERMER ferme la boîte.

Pour de nombreux exemples, voir la page de l'espace privé ecrire/?exec=charte_boites proposée par le plugin http://plugins.spip.net/dev

#FORMULAIRE_RECHERCHE_ECRIRE affiche le formulaire de recherche de l'espace privé. On peut lui indiquer en premier argument l'url vers laquelle il doit pointer, et une classe en second argument. En présence de javascript le formulaire se comporte comme un lien vers url avec le paramètre recherche fourni par la saisie. Si on indique la classe ajax en second argument, le formulaire provoque le rechargement du bloc ajax incluant, comme un lien ajax donc : #FORMULAIRE_RECHERCHE_ECRIRE{#SELF, ajax}

#CHEMIN_IMAGE{article-24.png} renvoie le chemin vers l'icône article-24.png du thème de l'espace privé en cours d'utilisation par l'auteur connecté.

Filtres

|lien_ou_expose permet de construire simplement un menu de plusieurs liens en exposant celui qui est sélectionné par un et en gardant un lien sinon. Exemple : [(#URL_PAGE{mapage}|lien_ou_expose{libelle, #ENV{page}|=={mapage}, classe, title, rel})]

|singulier_ou_pluriel affiche une chaîne ou une autre en fonction du nombre sur lequel il est appliqué : [(#TOTAL_BOUCLE|singulier_ou_pluriel{1_article,nb_articles})]. 1_article et nb_articles sont des chaînes de langue qui reçoivent le nombre en argument @nb@. Si le nombre est zéro, le filtre n'affiche rien.

|balise_img permet de construire rapidement une balise HTML à partir d'un nom de fichier en renseignant systématiquement le width et le height pour accélérer le rendu de la page : [(#CHEMIN{monimage.png}|balise_img{alt,class})]

|affdate_debut_fin affiche sous forme sympathique un intervalle de temps entre une date de début et une date de fin, en prenant en compte le fait que la date de début et la date de fin sont ou non le même jour, le même mois, la même année, et en prenant en compte l'affichage de l'heure ou non (second argument, oui ou non. Exemple :
[(#DATE_DEBUT|affdate_debut_fin{#DATE_FIN,horaireouinon})]

|timestamp ajoute au nom d'un fichier un horodatage sous la forme ?1234567890 ou le nombre représente la date du fichier compté en secondes depuis le 1er janvier 1970. Ce filtre est utile pour référencer par exemple des feuilles de styles en s'assurant que le navigateur les rechargera quand leur url change :
[]

|objet_icone renvoie l'icône standard d'un objet de SPIP. Par défaut, la taille 24px est renvoyée sauf si la taille 16 ou 32 est demandée en argument : [(#OBJET|objet_icone{16})]

|objet_info renvoie une propriété d'un objet de SPIP telle que déclarée (ou automatiquement renseignée par SPIP) via l'API declarer_tables_objets_sql

|objet_afficher_nb affiche le nombre d'objets en prenant en compte le nombre auquel le filtre s'applique et les chaînes de langue déclarées pour l'objet : [(#TOTAL_BOUCLE|objet_afficher_nb{auteur})] affichera par exemple 1 auteur ou 23 auteurs.

|wrap encadre un texte d'une balise html : [(#TITRE|wrap{
})] produit le même résultat que [(#TITRE) ]

|generer_info_entite affiche le champ d'un objet SPIP : [(#ID_ARTICLE|generer_info_entite{article,titre})] renvoie le titre mis en forme de l'article #ID_ARTICLE. C'est équivalent ici à [(#INFO_TITREarticle,#ID_ARTICLE)]

Dans l'espace privé :

|icone_horizontale affiche une icône de l'espace privé au format horizontal. La syntaxe est : [(#URL|icone_horizontale{libelle,icone,fonction})]. icone peut être désigné en abrégé (article) et sera alors au format 24px ou explicitement (article-24.png). Le 3ème argument fonction précise une famille d'action associée à l'icône et peut être au choix add, del, edit, new, ou omis. Exemple [(#URL_ECRIRE{auteur_edit,new=oui}|icone_horizontale{<:icone_creer_nouvel_auteur:>,auteur,new})]

|icone_verticale affiche une icône de l'espace privé au format vertical. La syntaxe est la même que pour |icone_horizontale

|bouton_action_horizontal utilise la même syntaxe que |icone_horizontale et affichera un résultat visuellement semblable. Cependant le markup HTML sera du même type que celui de #BOUTON_ACTION pour déclencher un POST vers l'url et est donc utile quand l'url modifie la base de données.

|sinon_interdire_acces placé à n'importe quel endroit de la page permet de bloquer l'accès à celle-ci quand l'expression à laquelle il s'applique est fausse. Dans ce cas une page d'erreur est affichée, sauf si une url de redirection est fournie en argument (on peut aussi alors fournir un status http de redirection en second argument). On l'utilise généralement sur une vérification d'autorisation [(#AUTORISER{modifier,article,#ID_ARTICLE}|sinon_interdire_acces)]

JavaScript

SPIP 3 utilise la version v1.7.2 de jQuery et intègre désormais jQuery UI en version 1.8.20. Il devient possible d'utiliser une version différente de jQuery dans le site public en surchargeant simplement javascript/jquery.js dans le dossier squelettes/ sans risquer de casser l'espace privé.

Liens ajax :
Les liens .ajax ne cassent plus l'historique de navigation sur les navigateurs qui supportent l'API HTML5 History (Firefox, Safari, Chrome à la date de cet article). C'est-à-dire que lorsqu'on clique sur un lien ajax de SPIP qui recharge une partie de la page, l'URL est mise à jour dans le navigateur et le visiteur peut cliquer sur Précédent pour revenir en arrière.

Classes spéciales sur les liens ajax :

.nohistory indique que le lien n'affecte pas l'historique de navigation lorsqu'il est cliqué ;
.preload indique à SPIP que le contenu du lien ajax doit être préchargé au moment où la page est chargée. Ainsi le clic sur le lien produira une mise à jour immédiate ;
.nocache indique à SPIP que le contenu du lien ajax ne doit pas être mis en cache. Ainsi plusieurs clics sur le même lien provoqueront autant de chargements depuis le serveur (par défaut, seul le premier chargement à lieu pour une url donnée et le contenu est ensuite mémorisé par le navigateur).

Rechargement télécommandé de blocs ajax :
Les liens .ajax permettent par défaut le rechargement du bloc ajax qui les contient, mais il est parfois nécessaire de provoquer le rechargement d'un autre bloc ajax de la page.

Pour cela, il devient possible de nommer les blocs ajax au moment de leur inclusion :
. Le bloc ajax ainsi nommé peut ensuite être rechargé via l'appel de ajaxReload('nomdubloc');. Il est possible de passer en second argument une liste d'options contenant :

callback : fonction callback qui doit être appelée après le chargement ajax du bloc
args : liste d'argument qui seront passés à l'url lors du chargement du bloc (permet de modifier le #ENV du bloc mis à jour) ;
history : indique si le rechargement affecte ou non l'historique de navigation (faux par défaut). Exemple :
ajaxReload('nomdubloc', {

callback:function(){alert('fini');},

args:{id_article:3},

history:false

});

ajaxReload peut être utilisé également sur un sélecteur jQuery auquel cas il provoquera le rechargement du plus petit bloc ajax qui contient l'élément ciblé. Il ne prend alors qu'un argument possible (le tableau d'options) : $('#contenu').ajaxReload({args:{id_article:3}})

Animations javascript :
Lors des interactions déclenchées par l'utilisateur, il est possible de déclencher plusieurs animations type qui s'appliquent toutes sur un sélecteur jQuery :

jQuery('#monid').animateLoading() déclenche l'animation de chargement sur #monid (automatiquement déclenchée lors des rechargements ajax)
jQuery('#monid').endLoading() arrête l'animation de chargement sur #monid (automatiquement déclenchée lors des rechargements ajax)
jQuery('#monid').animateAppend() anime le bloc #monid pour montrer qu'il vient d'être ajouté par l'interaction
jQuery('#monid').animateRemove() anime le bloc #monid pour montrer qu'il est supprimé par l'interaction

Fonctions utilitaires :
parametre_url() s'utilise comme sa version PHP de parametre_url pour ajouter, supprimer, récupérer des arguments d'une URL :

parametre_url(url,arg,value) ajoute arg=value à url et retourne l'url modifiée ;
parametre_url(url,arg,'') supprime la valeur de arg dans url et retourne l'url modifiée ;
parametre_url(url,arg) retourne la valeur de arg dans url
$('a').followLink() suit le lien en simulant un clic dessus (prend en compte le fait que le lien est ou non un lien ajax). Popin dans l'espace privé : Un lien vers une page de l'espace privé avec une classe .popin provoque l'ouverture d'une popin qui contient le coeur de la page pointée (bloc contenu/). Le lien conserve sa capacité à être ouvert dans un autre onglet via clic droit et la page complète est affichée dans ce cas. API SPIP 3 introduit plusieurs API génériques dans la gestion des objets éditoriaux : une gestion générique des tables de liens d'un objet avec n'importe quel autre objet : c'est l'API editer_liens La création de nouveaux objets éditoriaux est simplifiée par une API déclarative une gestion générique des fonctions d'insertion, modification ou publication des objets éditoriaux : l'API editer_objet objet_test_si_publie($objet, $id_objet) permet de tester facilement si un objet est publié ou non en fonction de son statut tel que déclaré (et en fonction d'une éventuelle post-publication) generer_url_ecrire_objet($objet,$id_objet,$args, $ancre) renvoie l'url vers la page de l'objet dans l'espace privé. $args et $ancre sont optionnels. le pipeline optimiser_base_disparus est appelé lors du nettoyage en base des objets à la poubelles et des liens morts qui en résultent SPIP 3 dispose également d'une gestion de file de tâches qui permet de programmer l'exécution future ou simplement asynchone (ASAP mais sans faire attendre l'utilisateur) de fonctions. La mise en place de configuration des plugins est simplifiée par la prise en charge automatisée des formulaires #FORMULAIRE_CONFIGURER_XXX et par l'utilisation des fonctions lire_config, ecrire_config, effacer_config (voir Configurer une fonctionnalité de votre site, ou un plugin). Les formulaires CVT permettent facilement de faire des formulaires en plusieurs pages, et supportent également la sauvegarde automatique de la saisie par simple déclaration. Un pipeline formulaire_fond permet de personnaliser le fond des formulaires (pour modifier le HTML du formulaire) [13] Dans l'API SQL : la fonction sql_skip est ajoutée et permet de sauter un certain nombre de résultats. Les valeurs null dans sql_updateq et sql_insertq sont traduites en NULL SQL et ne sont plus assimilées à une chaîne vide. les fonctions sql_demarrer_transaction et sql_terminer_transaction permettent respectivement comme leur nom le suggère de démarrer ou de clôturer une transaction SQL [14]. Introduction d'un point d'entrée bac-à-sable, (public/sandbox.php) pour la compilation des squelettes, permet à un plugin de gérer la compilation des squelettes dans un ensemble de filtres et fonctions en liste blanche ou liste noire, et d'interdire le PHP dans les squelettes. Spécialisation des critères : Il est possible de préfixer par le nom du serveur et/ou le nom de la table le nom de la fonction critère. La recherche se fait dans l'ordre : critere_serveur_TABLE_moncritere_dist, critere_serveur_TABLE_moncritere, critere_serveur_moncritere_dist, critere_serveur_moncritere, critere_TABLE_moncritere_dist, critere_TABLE_moncritere, critere_moncritere_dist, critere_moncritere Dans le fichier options.php d'un plugin ou dans le fichier mes_options.php, $GLOBALS['marqueur_skel'] .= ":prefixe" permet de différencier le cache des squelettes compilés comme $GLOBALS['marqueur'] .= ":prefixe" permettait déjà de différencier le cache des squelettes.

[1] Outre le Porte-plume déjà intégré dans SPIP 2 et qui initiait ce mouvement, on peut citer notamment les plugins Afficher_objets, Base CSS, Navigation du privé, CVT multi-étapes, Forum, Job-queue, Mediabox, Médiathèque, TextWheel, URLs éditables, Comments, qui ont, pour certains, inspiré fortement le développement de SPIP lui-même ; pour d'autres été intégrés, avec quelquefois certaines évolutions. [2] Ce chantier avait été amorcé depuis quelque temps sur la Zone, et ceux qui d'entre vous utilisaient déjà le plugin Navigation du privé ou la médiathèque retrouveront vite leurs marques. [3] Par exemple, le passage en édition sur un article devient instantané grâce au pré-chargement Ajax. [4] http://core.spip.org/projects/spip/repository/revisions/17650 [5] en SPIP 2.1 ils étaient placés dans le dossier extensions/ désormais inutile. [6] C'est une alternative aux plugin Thickbox, LightBox... qui repose sur la librairie Colorbox [7] Connu pour SPIP 2 sous le nom "Médiathèque" [8] en revanche le support de PostGreSQL doit être considéré comme expérimental et incomplet pour un usage en production [9] Par exemple, pour l'envoi d'un mail "dès que possible" qui permet de rendre la main à l'utilisateur immédiatement sans devoir attendre que le mail soit effectivement envoyé [10] dans tous les navigateurs modernes à l'exception de Internet Explorer qui ne la supporte pas encore [11] Voir Utiliser les modèles [12] La balise n'est plus utilisée en HTML5. [13] http://core.spip.org/projects/spip/repository/revisions/18754 [14] Est ajouté de manière expérimentale également sql_preferer_transaction présent plutôt pour contourner un problème de lenteur sur des insertions multiples avec SQLite, qui sont exécutées plus rapidement en mode transactionnel. Cette fonction renvoie true uniquement en SQLite

API de gestion de la file des travaux cerdic — 2012-05-19T09:50:41Z SPIP 3.0 intègre nativement une interface de programmation (ou API) de gestion de file de travaux. Elle permet de programmer des tâches à exécuter dans le futur, ou simplement le plus tôt possible mais sans faire attendre l'utilisateur [1]. Les travaux programmés sont à tout moment visualisables dans l'espace d'administration via le menu Maintenance > Liste des travaux. La page de suivi permet de forcer l'exécution immédiate d'une tâche, ou de supprimer certaines tâches. Ajouter un travail dans la file $id_job = job_queue_add($function, $description, $arguments = array(), $file = '', $no_duplicate = FALSE, $time=0, $priority=0) Avec les arguments : $function : le nom de la fonction PHP qui doit être appelée $description : une description humainement compréhensible de ce que fait la tache (essentiellement pour l'affichage dans la page de suivi de l'espace privé) $arguments (facultatif, vide par défaut) : les arguments qui seront passés à la fonction, sous forme de tableau PHP $file (facultatif, vide par défaut) : nom du fichier à inclure. Si le nom finit par un / alors on considère que c'est un répertoire et SPIP fera un charger_fonction($function,$file) $no_duplicate (facultatif, false par défaut) si vaut true la tâche ne sera pas ajoutée si elle existe déjà en file d'attente avec la même fonction et les mêmes arguments. si vaut 'function_only' la tâche ne sera pas ajoutée si elle existe déjà en file d'attente avec la même fonction indépendamment de ses arguments $time (facultatif, 0 par défaut) indique la date sous forme de timestamp à laquelle la tâche doit être programmée. Si 0 ou une date passée, la tâche sera exécutée aussitôt que possible (en général en fin hit, en asynchrone). $priority (facultatif, 0 par défaut) indique un niveau de priorité entre -10 et +10. Les tâches sont exécutées par ordre de priorité décroissante, une fois leur date d'exécution passée. La priorité est surtout utilisée quand une tâche cron indique qu'elle n'a pas fini et doit être relancée : dans ce cas SPIP réduit sa priorité pour être sûr que celle tâche ne monopolise pas la file d'attente. La fonction renvoie le numéro de travail ajouté ou 0 si aucun travail n'a été ajouté. Supprimer un travail de la file job_queue_remove($id_job) $id_job est le numéro du travail en attente, tel que retourné par la fonction job_queue_add La fonction retourne true si le travail a bien été trouvé et supprimé, false sinon. Associer un travail à un objet éditorial job_queue_link($id_job,$objets) Avec les arguments : $id_job : le numéro de travail en attente, tel que retourné par la fonction job_queue_add $objets une liste d'objets sous la forme d'un tableau d'objets array(array('objet'=>'article','id_objet'=>23),...) Lorsque des travaux sont associés à un objet, ils apparaissent sur la page de l'espace privé de cet objet, et les auteurs qui ont le droit de modifier l'objet peuvent aussi supprimer le travail avant son exécution. [1] Ces fonctionnalités étaient disponibles pour SPIP 2.1 dans le plugin job_queue API « editer_objet » cerdic — 2012-05-19T09:49:54Z L'ajout, la modification et la publication des instances d'objets éditoriaux sont simplifiés par une interface de programmation (ou API) constituée de 3 fonctions génériques qui peuvent servir pour manipuler tous les objets de SPIP. Insérer Une nouvelle instance d'un objet éditorial est créée en base par include_spip('action/editer_objet'); $id_objet = objet_inserer($objet, $id_parent); Télécharger objet_inserer prend 2 arguments : $objet est le nom de l'objet inséré (article, breve,...) $id_parent (facultatif) est l'id du parent de l'objet (id_rubrique pour un article ou une breve, id_groupe pour un mot...) Les pipelines pre_insertion et post_insertion sont appelés automatiquement par la fonction. Si, pour l'objet demandé, une fonction spécifique xxx_inserer existe dans action/editer_xxx, elle sera automatiquement appelée par objet_inserer à la place du traitement générique. La fonction retourne l'id de l'enregistrement ajouté en base, ou 0 en cas d'échec. Modifier Pour modifier une instance d'un objet en base, on utilise la fonction : objet_modifier include_spip('action/editer_objet'); objet_modifier($objet, $id_objet, $set); Télécharger Les 3 arguments : $objet indique le nom de l'objet modifié $id_objet donne l'id de l'objet modifié $set est un tableau associatif champ=>valeur des champs modifiés La fonction appelle automatiquement les pipelines pre_edition et post_edition. Si pour l'objet demandé, une fonction spécifique xxx_modifier existe dans action/editer_xxx, elle sera automatiquement appelée par objet_modifier à la place du traitement générique. La fonction retourne une chaîne vide si tout s'est bien passé ou l'erreur en cas d'échec. La fonction objet_modifier vérifie les droits de l'auteur de la session en cours à faire l'action, via un appel à autoriser('modifier', $objet, $id_objet). Si elle est appelée par une tâche anonyme, il sera nécessaire d'accorder une autorisation exceptionnelle comme indiquée dans API « autoriser ». Publier Pour la publication d'un objet (modification du statut ou de la date), il convient d'appeler la même fonction objet_modifier de la même façon que pour la modification. Cette fonction délègue à objet_instituer la mise à jour des champs qui concernent le statut de l'objet. Il est ainsi possible de modifier le contenu d'un objet et de le publier en un seul appel. Si une fonction xxx_instituer existe dans action/editer_xxx elle sera automatiquement appelée par objet_instituer à la place du traitement générique. La fonction objet_instituer vérifie les droits de l'auteur de la session en cours à faire l'action, via un appel à autoriser('instituer', $objet, $id_objet). Si elle est appelée par une tâche anonyme, il sera nécessaire d'accorder une autorisation exceptionnelle comme indiquée dans API « autoriser ». API « autoriser » cerdic — 2012-05-19T09:49:00Z L'interface de programmation (API) « autoriser » introduite dans SPIP 2.0 permet de gérer finement les autorisations données à un auteur d'effectuer une action sur un objet. Vérifier une autorisation La vérification d'une autorisation se fait par un appel de la forme : include_spip('inc/autoriser'); if (autoriser('modifier', 'article', $id_article)) { ... } Télécharger La fonction autoriser($faire, $type, $id, $qui, $opt) accepte 5 arguments dont seul le premier est obligatoire : $faire est une chaîne qui désigne l'action soumise à autorisation. C'est en règle générale un verbe simple (modifier, creer, supprimer, voir, configurer...), parfois associé à un contexte (les mots sont alors collés : changerlangue, publierdans...). Il y a quelques exceptions où le $faire n'est pas un verbe et s'utilise sans aucun autre argument (autoriser('webmestre') par exemple, ou autoriser('ecrire') —qui désigne ici l'espace d'administration et non l'action—). $type est une chaîne qui désigne sur quoi porte l'action. C'est en général le type d'un objet éditorial (article, rubrique, mot, groupe-mots, ...). $id désigne l'id (la clé primaire) de l'objet sur lequel porte l'action. $id est en général un nombre entier, mais peut être une chaîne si cela correspond à la clé primaire de la table SQL concernée. $qui désigne l'auteur (au sens SPIP) qui va faire l'action. Si il n'est pas fourni (ou null dans l'appel de la fonction autoriser, c'est implicitement l'auteur connecté qui est pris en compte. Sinon $qui peut être l'id_auteur d'un auteur dont on veut vérifier les droits, ou un tableau associatif qui décrit l'auteur (tableau qui contient alors les champs de la table spip_auteurs pour l'auteur concerné) $opt est un tableau associatif de données supplémentaires contextuelles concernant l'action qui sont parfois utilisées par l'autorisation. Par exemple lorsqu'on veut modifier/publier un article, on appellera autoriser('instituer', 'article', $id_article, null, array('statut' => 'publie')) La fonction autoriser retourne « true » ou « false » en fonction des droits de l'auteur à faire l'action demandée. Dans un squelette, la vérification d'une autorisation se fait par la balise #AUTORISER. Donner une autorisation exceptionnelle Il arrive qu'on ait besoin de faire une action qui sera soumise à autorisation pour un auteur qui normalement n'en a pas le droit. Cela peut se produire, par exemple, dans le cas d'une action programmée qui sera alors exécutée anonymement. Dans ce cas, il existe un mécanisme via la fonction autoriser_exception qui donne une autorisation exceptionnelle, le temps de réaliser l'action concernée. include_spip('inc/autoriser'); // donner une autorisation exceptionnelle temporaire autoriser_exception('modifier', 'article', $id_article); // réaliser l'action désirée include_spip('action/editer_objet'); objet_modifier('article', $id_article, array('titre' => 'Nouveau titre')); // retirer l'autorisation exceptionnelle autoriser_exception('modifier', 'article', $id_article, false); Télécharger La fonction autoriser_exception($faire, $type, $id, $autoriser) prend 4 arguments : $faire avec la même signification que pour autoriser() $type avec la même signification que pour autoriser() $id avec la même signification que pour autoriser() $autoriser qui est un booléen et indique si l'autorisation exceptionnelle est accordée ou non : Lorsque $autoriser vaut « true » ou n'est pas fourni, on accorde une autorisation exceptionnelle : tous les appels suivant à autoriser() avec les mêmes arguments $faire, $type et $id renverront true Lorsque $autoriser vaut « false » cela signifie que l'autorisation revient sous le régime normal et sera vérifiée selon la règle en vigueur (elle peut donc être encore autorisée ou effectivement interdite). Le false n'indique donc pas ici qu'on interdit l'action, mais simplement qu'il n'y a plus d'exception. Déclarer une nouvelle autorisation Lorsque la fonction générique autoriser() est appelée, elle cherche une fonction nommée à laquelle déléguer la vérification. Si aucun $type n'est fourni dans l'appel à autoriser(), la recherche de la fonction se fait dans l'ordre suivant : autoriser_$faire autoriser_$faire_dist autoriser_defaut autoriser_defaut_dist Si un $type est fourni dans l'appel à autoriser(), la recherche se fait dans l'ordre suivant : autoriser_$type_$faire autoriser_$type_$faire_dist autoriser_$type autoriser_$type_dist autoriser_$faire autoriser_$faire_dist autoriser_defaut autoriser_defaut_dist Dans les deux cas, la recherche va du plus précis vers le plus général. Cela permet de définir des familles d'autorisation avec une règle générale (pour une action par exemple), que l'on précise ensuite pour certains objets qui suivent une règle différente. Pour définir une autorisation, il suffit donc de créer une fonction avec l'un des noms de la liste ci-dessus. La fonction recevra en arguments ceux envoyés à la fonction autoriser() et doit renvoyer « true » ou « false ». On peut définir une autorisation générique. Lorsque c'est une autorisation qui n'est pas encore définie, on la suffixe en général par un _dist qui permet toujours à un webmestre de la surcharger dans son fichier mes_options.php (en déclarant la fonction de même nom, mais sans son suffixe _dist). Attention : on voit que dans le nom de la fonction, l'ordre de $faire et $type est inversé par rapport à celui de l'appel à autoriser(). À noter également qu'à partir de SPIP 3.0 le $type est présumé correspondre à un objet, et est normalisé lors de l'appel : vérification qu'il correspond bien à un type d'objet et sinon suppression du « s » final. Cela permet d'assurer qu'on appellera bien la bonne fonction d'autorisation même si on utilise un synonyme du $type (syndic au lieu de site par exemple, ou groupes_mot au lieu de groupe_mots qui est une exception de nommage). Il est cependant possible d'échapper à cette normalisation en préfixant le $type par un '_' (underscore) dans l'appel à autoriser(). Dans tous les cas, tous les autres caractères '_' sont retirés du $type Ainsi un appel à autoriser('modifier', 'groupes_mots', $id_groupe) délèguera à la fonction autoriser_groupemots_modifier() (ou l'une des variantes selon la règle ci-dessus si cette fonction précise n'existe pas). Dans les versions antérieures à SPIP 3.0 il convient de toujours faire très attention à bien utiliser le nom de l'objet sans erreur, car sinon l'autorisation par défaut sera appelée ce qui peut conduire à une erreur d'autorisation plus ou moins grave selon le cas. Exemple de fonction d'autorisation : /** * Autoriser a creer un article : * Il faut qu'une rubrique existe et qu'on ait le statut necessaire pour creer * * @return bool */ function autoriser_article_creer_dist($faire, $type, $id, $qui, $opt) { return (sql_countsel('spip_rubriques')>0 AND in_array($qui['statut'], array('0minirezo', '1comite'))); } Télécharger Aide au développement Lors du développement d'un plugin, il peut être utile de comprendre comment sont appelées les autorisations et dans quel ordre d'enchaînement. Pour cela il suffit d'ajouter la ligne suivante dans le fichier mes_options.php : define('_DEBUG_AUTORISER', true); Chaque appel à autoriser() sera alors tracé dans le fichier spip.log avec le nom de la fonction appelée et le résultat qu'elle a retourné. #HTML5 davux — 2012-05-19T09:31:16Z Permet de tester si le site est en HTML5. Il arrive souvent que SPIP, ainsi que les plugins, génèrent des bouts de code HTML sur le site public. Avec l'arrivée du HTML5, on a désormais la possibilité de produire du HTML plus sémantique, que ce soit par les nouvelles balises, les nouveaux éléments de formulaire, etc. Cependant, sil l'on souhaite continuer à avoir un site valide au sens du W3C (organisme de standardisation du langage HTML entre autres), il est nécessaire que l'utilisation de code HTML5 soit accompagnée de la déclaration du doctype suivant : Cela signifie donc que SPIP et les plugins ne peuvent pas utiliser aveuglément des éléments de HTML5 : il leur faut une indication de la part de la (ou du) webmestre pour savoir quel est le niveau de compatibilité HTML souhaité. Cela est possible depuis SPIP 3.0 par l'apparition d'une nouvelle option de configuration. Configuration HTML5 Zone de configuration dans SPIP pour autoriser ou non l'utilisation de HTML5. La balise #HTML5 permet de tenir compte de ce choix : Si le HTML5 est autorisé, la balise renvoie un résultat non-vide (espace) Si la configuration reste sur HTML4 (valeur par défaut), la balise renvoie un résultat vide. Sur les versions de SPIP inférieures à SPIP 3.0, la balise est inconnue, et renverra donc également un résultat vide. Il est donc possible de l'utiliser n'importe où, quelle que soit la version de SPIP visée : les sites sous SPIP avant 2.2 seront juste considérés comme étant en HTML4. Exemples d'utilisation Par exemple, un plugin ou un squelette qui génère une zone de recherche dans un formulaire pourra utiliser la balise de la manière suivante : type="[(#HTML5|?{search,text})] ... /> Ce code génèrera, si le HTML5 est activé dans la configuration : type="search" ... /> et dans le cas contraire : type="text" ... /> Autre exemple : définition d'une zone de saisie de formulaire comme obligatoire : type="text" [(#HTML5)required="required"] ... /> Le résultat sera donc l'un ou l'autre de ceux-ci suivant la configuration : type="text" required="required" ... /> type="text" ... /> Support par les navigateurs Bien sûr, comme toujours en développement web, n'oubliez pas de vérifier quel est le comportement des navigateurs qui ne connaissent pas les balises HTML et attributs que vous souhaitez utiliser. Formulaires CVT en plusieurs pages JLuc — 2012-05-19T09:31:09Z Les formulaires multi-étapes (ou multi-pages) sont une variation des formulaires CVT qui permet d'enchainer plusieurs pages de saisies, avec une validation (vérification) intermédiaire de chacune de ces pages et un traitement final qui permet de prendre en compte toutes les valeurs saisies en une seule fois. Il est nécessaire d'être déjà familier avec les formulaires CVT pour créer un formulaire CVT en plusieurs pages. Nous allons voir comment construire facilement un formulaire d'inscription en 3 pages distinctes, SPIP prenant en charge la partie compliquée qui consiste à mémoriser les données déja saisies pour le traitement final, et à permettre la navigation entre les pages. Les squelettes de chaque page Chaque page du formulaire se présente comme un formulaire complet (avec un bouton de validation qui sert à passer à l'étape suivante). Chacune des étape est numérotée, à partir de 1, et décrite par un fichier squelette indépendant qui implémente un formulaire autonome pour les saisies de cette page. Pour l'étape 1, le squelette est formulaires/inscription.html. Pour l'étape 2, le squelette est formulaires/inscription_2.html. Pour l'étape 3, le squelette est formulaires/inscription_3.html. Voici par exemple à quoi ressemble la première page de notre formulaire : [(#ENV*{message_ok}) ] [(#ENV*{message_erreur}) ] [(#ENV{editable}) [(#REM) les hidden qui declencheront le service du formulaire parametre : url d'action ] #ACTION_FORMULAIRE{#ENV{action},#FORM} Votre email <:pass_ok:>" /> ] Télécharger À l'intérieur de chaque squelette, #ENV{_etape} renvoie le n° de l'étape, et #ENV{_etapes} renvoie le nombre total d'étapes de saisie. Cela permet par exemple d'afficher un état de l'avancement de la saisie par rapport au nombre total de pages de saisies : #FORM formulaire_#FORM_#ENV{_etape}"> Inscription #ENV{_etape} / #ENV{_etapes} : indiquez votre email ... Télécharger A chaque page, #ENV contient toutes les valeurs déjà saisies lors des étapes précédentes. Ainsi, si vous voulez proposer une valeur par défaut qui dépend d'une saisie précédente, il suffit d'utiliser celle-ci pour pré-remplir votre saisie. Sur chaque page, il est aussi possible de proposer un bouton qui renvoie vers une autre étape (par exemple pour faire un bouton de retour à l'étape précédente). Il suffit pour cela de donner au bouton l'attribut name avec la valeur _retour_etape_n, n désignant le numéro de l'étape visée : <p class="boutons"> <input type="submit" class="submit" name="_retour_etape_2" value="<:retour:>" /> </p> Il est possible que cette étape soit une étape en avant, mais attention : dans tous les cas l'utilisateur ne pourra passer à une étape n que si la saisie des étapes précédentes est correcte et sans erreur ! Dans le cas contraire, c'est la première page avec des erreurs qui lui sera présentée. Charger et déclarer les étapes de saisie La déclaration des étapes ou pages de saisies se fait dans la fonction charger() de votre formulaire CVT. La fonction charger() est identique à celle d'un formulaire CVT conventionnel : elle doit retourner un tableau de tous les champs qui seront saisis dans l'ensemble du formulaire (donc toutes étapes confondues, comme si il n'y avait qu'une seule page de saisie). Mais en plus, elle doit déclarer que le formulaire comporte plusieurs pages. Cela se fait en renvoyant en plus une valeur '_etapes' qui désigne le nombre d'étapes de saisies. Dans notre exemple : function formulaires_inscription_charger_dist() { return array ( 'email' => '', // etape 1 'nom' => '', // etape 2 'prenom' => '', 'semaine' => 0, // étape 3 '_etapes' => 3); } Télécharger C'est cette valeur _etapes qui va déclencher la prise en charge par SPIP des différentes pages préparées ci-dessus. Vérifier la saisie à chaque étape La vérification de la saisie présente ici une particularité. Au lieu d'avoir une seule fonction verifier() comme dans un formulaire CVT conventionnel, il va falloir fournir ici une fonction verifier() par page de saisie. Celles-ci sont numérotées à partir de 1 comme pour les squelettes des différentes pages. formulaires_inscription_verifier_1_dist vérifie les saisies de l'étape 1 uniquement. formulaires_inscription_verifier_2_dist vérifie les saisies de l'étape 2. formulaires_inscription_verifier_3_dist vérifie les saisies de l'étape 3. etc. A l'intérieur de ces fonctions, l'appel à _request permet d'accéder aux valeurs saisies depuis l'étape 1 jusqu'à l'étape courante. Le numéro d'étape courante et le nombre totale d'étapes sont également accessible par request('_etape') et par request('_etapes'), si nécessaire, pour mutualiser du code par exemple. Après chaque page n, SPIP appelle les fonctions de vérification des étapes 1 à n pour vérifier l'absence de régression dans la validation (qui pourrait être due à une erreur ou à une tentative de fraude par l'utilisateur). En cas d'erreur, l'utilisateur est automatiquement renvoyé sur la première page dont la saisie n'est pas correcte. En cas de succès, SPIP passe à l'étape suivante, sauf si l'utilisateur est arrivé à la dernière page, auquel cas SPIP appelle la fonction traiter(). Traiter la saisie La fonction de traitement des saisies du formulaire n'est appelée que lorsque toutes les pages ont été saisies sans erreur. Elle peut accéder à l'ensemble des saisies avec la fonction _request comme si le formulaire avait été saisi en une seule fois. La fonction de traitement est donc tout à fait identique à celle d'un formulaire en une page et se nomme classiquement (ici formulaires_inscription_traiter_dist()). Sans oublier... - Ce formulaire ainsi construit bénéficie de tous les avantages des formulaires CVT. Il suffit donc de l'encapsuler dans une pour qu'il soit automatiqent pris en charge et permette la saisie multi-page en ajax. - Il est possible d'appeler le formulaire en commençant directement à l'étape 5, par exemple. Pour cela, il suffit de passer le paramètre "_etape=5" dans l'environnement (dans l'url par exemple). Dans ce cas, les vérifications des 4 pages précédentes sont effectuées et en cas de validation, l'étape 5 est affichée. Sinon c'est la première étape qui présente une erreur qui est affichée. [1] Cette fonctionnalité est également accessible pour SPIP 2 mais nécessite l'activation du plugin cvt-multi-etapes Formulaire CVT avec sauvegarde automatique cerdic — 2012-05-19T09:31:05Z Pour éviter que les utilisateurs ne perdent le bénéfice de leur saisie en cas de perte de connexion ou de fausse manipulation, il est possible d'activer une fonction de sauvegarde automatisée dans les formulaires CVT. Activer la fonction Pour activer la prise en charge, il suffit que la fonction charger() du formulaire renvoie un identifiant unique qui désigne le formulaire. Il y aura une sauvegarde différente par identifiant unique (et par formulaire), celui-ci doit donc dépendre du contexte de la saisie. Par exemple sur un formulaire de forum en réponse à un article on choisira de passer comme identifiant l'id_article de l'article auquel on répond. Cet identifiant peut être un entier, une chaine ou un tableau, et doit être envoyé dans le champ '_autosave_id' : function formulaires_repondre_article_charger_dist($id_article){ ... return array( ..., '_autosave_id' => $id_article ); } Télécharger Ou sont sauvegardées les données ? Lorsqu'on active cette fonction, le formulaire va envoyer à chaque modification de saisie une requête à SPIP avec la liste de tous les champs saisis. SPIP va alors stocker cette information dans la session de l'utilisateur, sur le serveur. Lorsque la saisie est complète et que l'utilisateur valide le formulaire, SPIP va alors vider cette sauvegarde (lors du traitement du formulaire). Mais si l'utilisateur rencontre une erreur ou un problème et oublie de valider le formulaire, la sauvegarde est conservée 72H. Si l'utilisateur revient sur le même formulaire, il va retrouver le formulaire pré-rempli avec toutes les informations qu'il avait saisi auparavant. De la vie privée ... Attention cependant à ne pas utiliser cette sauvegarde automatique dans un formulaire qui collecte des données personnelles dans une session anonyme. Si l'utilisateur est sur un poste de consultation public et ne valide pas, ses données seront alors disponibles pour quiconque revient sur la même page avec son poste de consultation. Par ailleurs, il est possible de personnaliser la durée de 72H de conservation des données saisies en précisant dans le fichier mes_options.php par exemple (pour une durée de 24h) : define('_AUTOSAVE_GB_DELAY',24*3600) {tri} et #TRI dans les boucles cerdic — 2012-05-19T09:31:01Z SPIP 3.0 introduit un critère et une balise qui permettent de faire facilement des listes triables. Le critère {tri} simplifie la réalisation de listes triables de la même façon que le critère {pagination} simplifie la réalisation de listes paginées. Dans une boucle simple, il permet de définir le critère de tri en lui indiquant en argument le champ à utiliser par défaut : (ARTICLES){tri titre}> Télécharger Jusque là rien de nouveau par rapport au critère {par}. Mais {tri} peut être associé à la balise #TRI qui permet de générer un lien pour changer le critère de tri. La balise #TRI prend en premier argument le champ de tri, et en second argument le libellé du lien clicable pour utiliser ce champ pour le tri : #TRI{titre,'Trier par titre'} | #TRI{date,'Trier par date'} | #TRI{date_redac,'Trier par date de rédaction'} (ARTICLES){tri titre}> Télécharger Ce faisant l'utilisateur se voit proposer un menu pour modifier le tri de la boucle. Le tri actuellement utilisé est exposé en gras et non clicable, et les tris non utilisés sont des liens clicables. Si la boucle est dans une inclusion ajax, il suffit de renseigner la classe ajax en troisième argument de la balise #TRI pour que les liens se comportent avec un rechargement partiel de la page : #TRI{titre,'Trier par titre',ajax} | #TRI{date,'Trier par date',ajax} | #TRI{date_redac,'Trier par date de rédaction',ajax} (ARTICLES){tri titre}> Télécharger Le critère {tri} permet également d'indiquer le sens du tri par défaut en second argument. Il faut indiquer la valeur direct ou 1 pour indiquer un tri croissant par défaut, et inverse ou -1 pour un tri décroissant par défaut : #TRI{titre,'Trier par titre'} | #TRI{date,'Trier par date'} | #TRI{date_redac,'Trier par date de rédaction'} (ARTICLES){tri date,-1}> Télécharger Par ailleurs il est aussi possible de proposer le choix du sens de tri. Cela se fait en passant > pour un tri croissant et < pour un tri décroissant en premier argument de la balise #TRI : #TRI{>,'Tri croissant',ajax} | #TRI{>,'Tri décroissant',ajax} | #TRI{titre,'Trier par titre',ajax} | #TRI{date,'Trier par date',ajax} | #TRI{date_redac,'Trier par date de rédaction',ajax} (ARTICLES){tri titre}> Télécharger Cela dit, plutôt que de proposer des boutons de tri systématique, une alternative est possible : adapter automatiquement le sens du tri à la colonne utilisée pour le tri. Cela se fait en passant en second argument de la balise tri un tableau avec le sens par défaut pour chaque colonne : #SET{defaut_tri,#ARRAY{ tri,1, date,-1, date_redac,-1 }} #TRI{titre,'Trier par titre',ajax} | #TRI{date,'Trier par date',ajax} | #TRI{date_redac,'Trier par date de rédaction',ajax} (ARTICLES){tri titre,#GET{defaut_tri}}> Télécharger Ainsi quand l'utilisateur choisira le tri par titre, celui-ci sera dans un ordre croissant. Mais quand il choisira la date ou la date de rédaction, le tri se fera dans un ordre décroissant. Les itérateurs de SPIP Fil, Matthieu Marcillaud — 2012-05-19T09:30:50Z Nous sommes en train de développer dans SPIP une notion générale de boucle, basée sur les itérateurs de PHP. Ces boucles ne portent plus exclusivement sur des requêtes SQL, mais peuvent tourner sur toutes sortes de listes de données. Par exemple : — un tableau de données produit par une fonction quelconque — le contenu d'un fichier local au format XML, CSV, JSON, YAML, etc. — une liste de fichiers dans un répertoire du serveur — une requête sur un webservice — etc (LDAP...). Les boucles SQL Sans surprise, l'itérateur classique de SPIP s'appelle SQL. Il exécute la requête telle que SPIP l'a calculée, et sait parcourir la liste de résultats pour les envoyer à la boucle. La boucle (DATA) C'est une boucle capable d'itérer n'importe quel tableau de données. Sa syntaxe de base est la suivante : #BALISES Le critère {source format, données} définit les données sur lesquelles la boucle va itérer. La définition d'une source de données nécessite deux éléments : — La partie données : cet élément peut être de plusieurs natures : - un tableau de données, par exemple #ENV* - le chemin d'un fichier sur le disque dur, ex : sources/definitions.csv - l'URL d'un fichier ou d'un webservice, ex : http://per.sonn.es/bases/phobia.fr.yaml - 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'" — La partie format est à prendre dans la liste ci-dessous : - table (alias array ou tableau), pour un tableau déjà créé - csv, json, yaml pour un fichier composé dans l'un de ces formats - file pour boucler sur les lignes d'un fichier - glob ou pregfiles pour boucler sur les fichiers d'un répertoire (et plus...) - rss (alias atom) pour lire un flux de nouvelles - plugins pour lister les plugins actifs sur le site - yql pour envoyer une requête sur le webservice de Yahoo Query Language - sql pour envoyer une requête brute au serveur SQL (utiliser {source sql, connecteur:requete} pour envoyer la requête sur une base externe) - ics pour boucler sur des calendriers (nécessite le plugin icalendar : lire La boucle iCalendar) - etc. Tous ces formats sont déjà disponibles, et il est très aisé d'en ajouter un nouveau, en créant une simple fonction inc_FORMAT_to_array($u). A titre d'exemple voici la fonction qui transforme un fichier JSON en tableau de données : function inc_json_to_array_dist($u) { if (is_array($json = json_decode($u)) OR is_object($json)) return (array) $json; } A lire : Exemples de BOUCLE(DATA) . YQL — Yahoo Query Language YQL est un webservice permettant d'interroger de façon simple de nombreux sites comme google, twitter, flickr, etc. Avec la boucle (DATA), SPIP facilite grandement son intégration sous forme de boucles : Cf. Exemples de boucles YQL. Itérateurs PHP SPIP est capable d'utiliser les itérateurs PHP standards. Il convient de se reporter à leur documentation, qui est souvent très succincte, et de vérifier que les itérateurs en questions sont disponibles sur votre système. Notons, par exemple, DirectoryIterator, qui permet de lister les fichiers d'un répertoire : Boucle : {pagination 10} {valeur!==^\.}{valeur==\.jpg$} >[(#VAL{Y-m-d H:i:s}|date{#GETMTIME})] / #VALEUR #PAGINATION Résultat : 2008-02-01 23:27:23 / arton2135.jpg 2008-08-21 11:12:58 / DSC03420.jpg 2008-08-21 11:13:11 / DSC03421.jpg 2009-08-27 11:20:11 / hash-1.jpg 2009-08-27 11:20:04 / hash.jpg Il convient d'indiquer à SPIP qu'il s'agit d'un itérateur PHP, en indiquant (php:...) avant le nom de l'itérateur. Le critère {args xx,yy} définit les arguments que l'on va passer à l'itérateur lors de son initialisation. Pour DirectoryIterator, il s'agit du chemin du répertoire à lister. Les méthodes de cet itérateur (cf. http://php.net/manual/fr/class.directoryiterator.php) sont disponibles sous forme de balises (ici, #GETMTIME). Remarque : pour lister le contenu d'un répertoire, le format glob de la boucle (DATA) est sans doute plus facile à utiliser que cet itérateur PHP. {!par mtime}> ... Filtrage, tri, pagination, fusion Filtres. Comme les boucles SQL, les boucles (DATA) peuvent être filtrées par des critères du type {valeur=x} ; les opérateurs disponibles sont =, >, <, >=, <=, == (expression rationnelle) et LIKE. Cependant ce filtrage s'effectue non pas en amont lors de la requête, comme en SQL, mais en aval, sur le tableau de données initialement récupéré. Tris. Les tris {par xx} sont également possibles, avec leur variante {!par xx} pour trier en ordre inverse. Pagination. La pagination fonctionne normalement, ainsi que le critère offset/limit {a,b}. Fusion. Le critère {fusion /x/y} fonctionne aussi. Par exemple, pour un fichier d'adresses au format CSV, si l'email est le champ n° 3, on pourra ne retenir qu'un seul enregistrement par email avec la boucle suivante : {fusion /3} {par /0}{' '}> #VALEUR{0} : #VALEUR{3} La fusion se fait après le tri, et retient le premier élément rencontré. De cette manière, si un tableau est trie {!par date} puis fusionné sur l'email, l'enregistrement retenu pour chaque email sera le plus récent. Dans le prochain article, nous verrons des exemples de boucles (DATA). API editer_liens cerdic — 2012-05-19T09:30:48Z SPIP 3 introduit une gestion générique des tables de liens d'un objet avec n'importe quel autre objet. Table de lien Les liens sont structurellement non symétriques : il partent d'un objet source pour aller vers n'importe quel objet destination. Pour être associable en tant que source, un objet bidibule stocké dans une table spip_bidibules doit posséder une table spip_bidibules_liens qui possèdera un champ id_bidibule (même nom que la clé primaire de spip_bidibules) et deux champs id_objet et objet. La table peut aussi comporter d'autres champs pour qualifier les liens. API L'API permet de gérer simplement les liens sans manipuler directement des requêtes SQL, et en offrant systématiquement des points d'entrée aux plugins qui peuvent ainsi savoir quand un lien est ajouté, supprimé, ou modifié et agir en conséquence. Pour utiliser l'API il faut inclure action/editer_liens.php : include_spip('action/editer_liens'); objet_associable objet_associable($objet) teste si un objet peut être associé à d'autres via sa table de liens. Si l'objet n'est pas associable (il n'a pas de table de liens dédiée), la fonction renvoie false. Si l'objet est associable, la fonction renvoie un tableau composé du nom de la clé primaire (commune à la table de liens et à la table de l'objet), et le nom de la table de liens. Par exemple (et par défaut dans SPIP) les auteurs, les documents, les mots sont des objets associables car ils disposent tous d'une table spip_xxx_liens. Par contre, les articles ne sont pas associables car ils ne disposent pas de table spip_articles_liens. Cela signifie qu'on ne peut pas créer de liens partant des articles vers un autre objet quelconque. En revanche on peut créer un lien depuis un mot, un auteur ou un document vers un article. objet_associer objet_associer($objets_source, $objets_lies[,$qualif]) permet d'associer les $objets_lies aux $objets_source via leurs table de lien propres. $objets_source Les $objets_source doivent être tous associables au sens de la fonction objet_associable(). Les objets sources sont donc les pivots sur lesquels portent les liens. Le format de $objets_source est commun a toutes les fonctions de manipulation de liens. C'est un tableau dont chaque clé correspond au nom de l'objet à associer chaque valeur décrit le ou les id pour chaque objet. Les valeurs peuvent être : le joker "*" qui désigne "tous les id déja dans la table de lien" (il a donc peu d'intérêt dans le cas de l'ajout de liens comme ici) une valeur scalaire autre désigne un id précis un tableau désigne une liste d'id (un tableau ne peut pas contenir le joker "*") un tableau de deux éléments commençant par la valeur 'NOT' désigne une condition exclusive : tous les id déjà dans la table de lien sauf ceux décrits dans la seconde valeur (qui peut être à son tour un scalaire ou un tableau) $objets_lies Le format de $objets_lies est commun a toutes les fonctions de manipulation de liens. C'est un tableau dont chaque clé correspond au nom de l'objet à associer. La valeur joker "*" désigne "tous les objets présents dans la table de lien" (peu d'intérêt dans le cas d'ajout de lien donc) chaque valeur décrit le ou les id pour chaque objet. Les valeurs peuvent être : le joker "*" qui désigne "tous les id déja dans la table de lien" (il a donc peu d'intérêt dans le cas de l'ajout de liens comme ici) une valeur scalaire autre désigne un id précis un tableau désigne une liste d'id (un tableau ne peut pas contenir le joker "*") un tableau de deux éléments commençant par la valeur 'NOT' désigne une condition exclusive : tous les id déjà dans la table de lien sauf ceux décrits dans la seconde valeur (qui peut être à son tour un scalaire ou un tableau) $qualif La fonction objet_associer peut prendre un troisième argument facultatif $qualif qui est un tableau associatif champ=>valeur avec lequel seront modifiés les liens ajoutés. Cela peut être utile si la table de lien dispose de champs supplémentaires qui décrivent les liens. Si plusieurs liens sont créés en même temps, ils se voient appliquer tous les mêmes valeurs décrites dans $qualif exemples Les exemples ci-dessous sont valides : objet_associer(array("auteur"=>3), array("article"=>5)); objet_associer(array("auteur"=>3), array("article"=>array(5,6))); objet_associer(array("auteur"=>array(3,4)), array("article"=>5)); objet_associer(array("auteur"=>array(3,4)), array("article"=>array(5,6))); objet_associer(array("document"=>3), array("article"=>5), array('vu'=>'oui')); Télécharger Le fonction renvoie le nombre de liens effectivement créés (certains liens pouvant déjà exister au moment de la tentative d'ajout, qui ne sont alors pas comptés). objet_dissocier objet_dissocier($objets_source,$objets_lies) permet de supprimer les liens entre les $objets_source et $objets_lies. $objets_source voir le format identique à celui décrit dans objet_associer $objets_lies voir le format identique à celui décrit dans objet_associer exemples Les exemples ci-dessous sont valides : objet_dissocier(array("auteur"=>3), array("article"=>5)); /* Exemple pour associer un auteur à une liste d'article et uniquement à ceux là */ objet_associer(array("auteur"=>3), array("article"=>array(5,6))); objet_dissocier(array("auteur"=>3), array("article"=>array('NOT', array(5,6)))); Télécharger La fonction renvoie le nombre de liens effectivement supprimés. objet_qualifier_liens objet_qualifier_liens($objets_source,$objets_lies,$qualif) permet de modifier les valeurs des champs décrits dans $qualif sur les liens entre $objets_source et $objets_lies $objets_source voir le format identique à celui décrit dans objet_associer $objets_lies voir le format identique à celui décrit dans objet_associer $qualif voir le format identique à celui décrit dans objet_associer exemples Les exemples ci-dessous sont valides : objet_qualifier(array("document"=>3), array("article"=>5), array('vu'=>'oui')); La fonction renvoie le nombre de mise à jour en base ou false en cas d'échec. objet_trouver_liens objet_trouver_liens($objets_source,$objets_lies) permet de retrouver tous les liens de $objets_source vers $objets_lies. $objets_source voir le format identique à celui décrit dans objet_associer $objets_lies voir le format identique à celui décrit dans objet_associer La fonction renvoie un tableau constitué d'un tableau associatif pour chaque lien trouvé. Ce dernier contient l'ensemble des champs du lien, auquel sont ajoutés une entrée objet=>id pour la source et la destination du lien, pour simplifier le traitement au retour (évite d'avoir à connaitre les clés primaires par exemple). objet_optimiser_liens objet_optimiser_liens($objets_source,$objets_lies) nettoie les liens restant entre $objets_source et $objets_lies lorsque l'un des deux n'existe plus (suppression en base de données). Cette fonction est classiquement utilisée dans des fonctions crons de nettoyage de la base de données. $objets_source voir le format identique à celui décrit dans objet_associer $objets_lies voir le format identique à celui décrit dans objet_associer La fonction renvoie le nombre de liens obsolètes nettoyés objet_dupliquer_liens objet_dupliquer_liens($objet,$id_source,$id_cible) va dupliquer tous les liens de l'$objet $id_source sur l'$objet $id_cible. Pour cela, toutes les tables de liens de tous les objets connus seront parcourues pour trouver les liens depuis et vers l'$objet $id_source. Chaque lien trouvé sera dupliqué en substituant $id_cible à $id_source La fonction retourne le nombre de liens dupliqués. Interface d'édition Une interface générique #FORMULAIRE_EDITER_LIENS utilisable dans les squelettes permet l'édition des liens. #FORMULAIRE_EDITER_LIENS{auteurs,article,23} installera le formulaire pour associer/dissocier des auteurs de l'article N°23. Les liens sont portés par la table lien du premier objet passé en argument du formulaire (auteurs dans l'exemple ci-dessus). On peut utiliser ce formulaire de plusieurs façons : #FORMULAIRE_EDITER_LIENS{auteurs,article,23} pour associer des auteurs à l'article N°23, sur la table pivot spip_auteurs_liens #FORMULAIRE_EDITER_LIENS{auteur,12,articles} pour associer des articles à l'auteur N°12, sur la table pivot spip_auteurs_liens #FORMULAIRE_EDITER_LIENS{mot,15,auteurs} pour associer des auteurs au mot N°15, sur la table pivot spip_mots_liens #FORMULAIRE_EDITER_LIENS{auteurs,mot,15} pour associer des auteurs au mot N°15, sur la table pivot spip_auteurs_liens On peut donc, par la syntaxe d'appel, définir quels objets sont associé entre eux, ainsi que la table qui supporte les liens. Pour fonctionner, ce formulaire nécessite 2 squelettes correspondant au type d'objet associé. Par exemple pour pouvoir associer ou dissocier des auteurs de n'importe quel autre objet, les squelettes prive/objets/liste/auteurs_lies.html et prive/objets/liste/auteurs_associer.html sont nécessaires au fonctionnement du formulaire. Ils présentent la liste des objets déjà associés ainsi que la sélection des objets à associer. SPIP inclue nativement les vues nécessaires pour les auteurs, les rubriques, ainsi que les mots via le plugin mots. Des plugins peuvent rendre cette interface disponible pour de nouveaux objets éditoriaux par la définition de ces deux squelettes. API de déclaration d'objets éditoriaux cerdic, _Eric_ — 2012-05-19T09:30:18Z Dans SPIP 3.0 la création de nouveaux objets éditoriaux est simplifiée par une interface de programmation (ou API) déclarative [1] qui permet à SPIP de construire de façon automatisée une grande partie de l'interface d'édition de ces objets. La déclaration d'un nouvel objet éditorial se fait via le pipeline declarer_tables_objets_sql qui permet de peupler un tableau associatif : Les clés du tableau sont les noms des tables SQL (exemple spip_articles) à chaque clé sont associées un certain nombre de valeurs dans un tableau, selon la nomenclature ci-dessous, présentée par type d'information Base de donnée table_objet Explication nom raccourci de la table Exemple articles pour spip_articles Valeur par défaut nom de la table sans spip_ dans SPIP 2.1 non déclaré table_objet_surnom Explication synonymes de table_objet pour les cas particuliers Exemple pas de surnom pour articles (mais exemple : groupe_mots pour spip_groupes_mots) Valeur par défaut pas de surnom dans SPIP 2.1 via declarer_tables_objets_surnoms type Explication nom court de l'objet Exemple article pour la table spip_articles Valeur par défaut clé primaire sans id_ au début ni s a la fin, ou à défaut nom de la table sans spip_ au début ni s a la fin dans SPIP 2.1 type_surnoms Explication synonyme du type pour les cas particuliers Exemple Valeur par défaut pas de surnom dans SPIP 2.1 field Explication Déclaration SQL des champs de la table Exemple array( "id_article" => "bigint(21) NOT NULL", "surtitre" => "text DEFAULT '' NOT NULL", "titre" => "text DEFAULT '' NOT NULL", "soustitre" => "text DEFAULT '' NOT NULL",...) Valeur par défaut héritée de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité) dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe key Explication Déclaration SQL des clés de la table Exemple array( "PRIMARY KEY" =>"id_article", "KEY id_rubrique" => "id_rubrique",...) Valeur par défaut hérité de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité) dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe join Explication les champs déclarés explicitement pour les jointures. sinon les jointures se feront exclusivement sur la clef primaire. attention : les champs 'idx', 'maj', 'date' et 'statut' ne peuvent PAS être déclarés comme champs de jointure possible. Exemple array( "id_article"=>"id_article", "id_rubrique"=>"id_rubrique") Valeur par défaut hérité de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité) dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe tables_jointures Explication déclaration de la table de liens et de son champ de jointure. on joindra ainsi (par exemple) id_article, articles à id_auteur, auteurs en passant par la table auteurs_liens et ses lignes id_auteur, id_objet, objet (donc, ici : id_auteur, id_article, articles) Exemple array('id_auteur' => 'auteurs_liens') Valeur par défaut hérité de la déclaration $tables_jointures si existante (compatibilité) dans SPIP 2.1 $declarer_tables_objets_sql['spip_articles']['tables_jointures'] reprend l'ancien contenu de $tables_jointures['spip_articles'] principale Explication Indique si la table est table principale ou auxiliaire ; prend les valeurs 'oui' ou 'non' Exemple 'oui' Valeur par défaut hérité de la déclaration $tables_principales si existante (compatibilité) dans SPIP 2.1 Remplace l'affectation des tableaux dans le pipeline declarer_tables_principales ou declarer_tables_auxiliaires modeles Explication permet de déclarer les modèles associés a cet objet Exemple exemple pour spip_documents : array('document', 'doc', 'img', 'emb', 'image', 'video', 'text', 'audio', 'application') Valeur par défaut la valeur de type dans SPIP 2.1 Le titre, la date et la gestion du statut titre Explication Représentation SQL qui permet de récupérer le titre et la langue de l'objet Exemple "titre, lang" Valeur par défaut hérité de la déclaration $tables_titre (compatibilité) ou vide sinon dans SPIP 2.1 Remplace la déclaration du titre de l'objet dans le pipeline declarer_tables_interfaces : $interface['table_titre']['articles'] = "titre, '' AS lang"; date Explication déclare le champ date de l'objet utilisé pour le dater Exemple date Valeur par défaut hérité de la déclaration $tables_date ou vide dans SPIP 2.1 Remplace la déclaration de la date de l'objet dans declarer_tables_interfaces : $interface['table_date']['articles'] = "date"; statut Explication Déclaration du statut pour l'objet Exemple array(array( 'champ' => 'statut', 'publie' => 'publie', 'previsu' => 'publie,prop,prepa', 'post_date' => 'date', 'exception' => 'statut')) Valeur par défaut vide dans SPIP 2.1 Remplace la surcharge des boucles avec conditions where pour gerer le statut. Ici la déclaration est directement prise en compte dans les boucles génériques statut_titres Explication Chaines de langue du titre de chaque statut. Définit par la même la liste des statuts autorisés Exemple array( 'prepa'=>'info_article_redaction', 'prop'=>'info_article_propose', 'publie'=>'info_article_publie', 'refuse'=>'info_article_refuse', 'poubelle'=>'info_article_supprime') Valeur par défaut null dans SPIP 2.1 statut_images Explication definit les puces associées à chaque statut Exemple Valeur par défaut null dans SPIP 2.1 Pas d'équivalence statut_textes_instituer Explication Chaines de langue du libellé de chaque statut dans le bloc instituer de l'objet Exemple array( 'prepa' => 'texte_statut_en_cours_redaction', 'prop' => 'texte_statut_propose_evaluation', 'publie' => 'texte_statut_publie', 'refuse' => 'texte_statut_refuse', 'poubelle' => 'texte_statut_poubelle') Valeur par défaut null dans SPIP 2.1 Pas d'équivalence L'édition, l'affichage et la recherche page Explication Le nom de la page publique de l'objet Exemple article Valeur par défaut type si principale='oui', rien sinon dans SPIP 2.1 Remplace la déclaration de l'url de l'objet dans le pipeline declarer_url_objets() url_voir Explication nom de l'exec privé pour voir l'objet Exemple article Valeur par défaut type dans SPIP 2.1 url_edit Explication nom de l'exec privé pour éditer l'objet Exemple article_edit Valeur par défaut type+_edit dans SPIP 2.1 editable Explication donner acces à une page d'édition dans l'espace privé Exemple 'oui' ou false Valeur par défaut oui dans SPIP 2.1 champs_editables Explication Liste des champs de l'objet pouvant être modifiés dans le formulaire d'édition Exemple array('surtitre', 'titre', 'soustitre', 'descriptif','nom_site', 'url_site', 'chapo', 'texte', 'ps','virtuel') Valeur par défaut vide dans SPIP 2.1 listés explicitement dans la fonction articles_set de action/editer_article [2] icone_objet Explication nom du fichier d'icône fourni en 16/24/32px Exemple article Valeur par défaut type dans SPIP 2.1 champs_versionnes Explication Liste des champs de l'objet soumis au processus de révisions Exemple array('id_rubrique', 'surtitre', 'titre', 'soustitre', 'jointure_auteurs', 'descriptif', 'nom_site', 'url_site', 'chapo', 'texte', 'ps') Valeur par défaut array() dans SPIP 2.1 rechercher_champs Explication Déclaration des champs utilisés dans la recherche et de leur score respectif Exemple array( 'surtitre' => 5, 'titre' => 8, 'soustitre' => 5, 'chapo' => 3,...) Valeur par défaut array() dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline rechercher_liste_des_champs : même syntaxe rechercher_jointures Explication Déclaration des champs et de leurs scores respectifs utilisés via une jointure lors de la recherche. Préciser la table de ces champs en premier élément de l'array. Exemple array( 'auteur' => array('nom' => 10) ) Valeur par défaut array() dans SPIP 2.1 Remplace la déclaration incluse dans le pipeline rechercher_liste_des_jointures : même syntaxe Les chaines de langue On déclare dans ces items là sous forme de chaine de langue les textes standards utilisés dans l'espace privé, dans les pages générées automatiquement par SPIP. texte_ajouter Explication Chaine "Ajouter un ..." Exemple titre_ajouter_un_auteur Valeur par défaut texte_ajouter_type dans SPIP 2.1 texte_retour Explication Chaine de langue du bouton retour dans la page d'édition de l'objet Exemple icone_retour_article Valeur par défaut icone_retour dans SPIP 2.1 texte_modifier Explication Chaine de langue du bouton modifier permettant d'ouvrir le formulaire d'édition de l'objet Exemple icone_modifier_article Valeur par défaut type:icone_modifier_type dans SPIP 2.1 texte_creer Explication Chaine de langue du bouton de création d'un nouvel objet Exemple icone_ecrire_article Valeur par défaut type:icone_creer_type dans SPIP 2.1 texte_creer_associer Explication Exemple creer_et_associer_un_auteur Valeur par défaut type:texte_creer_associer_type dans SPIP 2.1 texte_signale_edition Explication Chaine de langue signalant que l'auteur x a travaillé récemment sur l'objet Exemple texte_travail_article Valeur par défaut info_qui_edite dans SPIP 2.1 texte_objet Explication Chaine de langue du singulier de l'objet. La valeur est censée être écrite avec une lettre capitale Exemple public:article Valeur par défaut type:titre_type dans SPIP 2.1 texte_objets Explication Chaine de langue du pluriel de l'objet La valeur est censée être écrite avec une lettre capitale Exemple public:articles Valeur par défaut type:titre_table_objet dans SPIP 2.1 info_aucun_objet Explication Chaine de langue désignant 0 article utilisée dans la fonction objet_afficher_nb() Exemple info_aucun_article Valeur par défaut type:info_aucun_type dans SPIP 2.1 info_1_objet Explication Chaine de langue désignant 1 article utilisée dans la fonction objet_afficher_nb() Exemple info_1_article Valeur par défaut type:info_1_type dans SPIP 2.1 info_nb_objets Explication Chaine de langue désignant nb article utilisée dans la fonction objet_afficher_nb() Exemple info_nb_articles Valeur par défaut type:info_nb_table_objets dans SPIP 2.1 texte_logo_objet Explication Chaine de langue du titre de la boite d'affichage du logo dans la page privée de l'objet Exemple logo_article Valeur par défaut type:titre_logo_type dans SPIP 2.1 Remplace l'utilisation de la globale $GLOBALS['logo_libelles']['id_objet'] Exemple des brèves Voici la déclaration telle que réalisée par le plugin qui ajoute les brèves comme objet éditorial dans SPIP : function breves_declarer_tables_objets_sql($tables){ $tables['spip_breves'] = array( 'texte_retour' => 'icone_retour', 'texte_objets' => 'breves:breves', 'texte_objet' => 'breves:breve', 'texte_modifier' => 'breves:icone_modifier_breve', 'texte_creer' => 'breves:icone_nouvelle_breve', 'info_aucun_objet'=> 'breves:info_aucun_breve', 'info_1_objet' => 'breves:info_1_breve', 'info_nb_objets' => 'breves:info_nb_breves', 'texte_logo_objet' => 'breves:logo_breve', 'texte_langue_objet' => 'breves:titre_langue_breve', 'titre' => 'titre, lang', 'date' => 'date_heure', 'principale' => 'oui', 'field'=> array( "id_breve" => "bigint(21) NOT NULL", "date_heure" => "datetime DEFAULT '0000-00-00 00:00:00' NOT NULL", "titre" => "text DEFAULT '' NOT NULL", "texte" => "longtext DEFAULT '' NOT NULL", "lien_titre" => "text DEFAULT '' NOT NULL", "lien_url" => "text DEFAULT '' NOT NULL", "statut" => "varchar(6) DEFAULT '0' NOT NULL", "id_rubrique" => "bigint(21) DEFAULT '0' NOT NULL", "lang" => "VARCHAR(10) DEFAULT '' NOT NULL", "langue_choisie" => "VARCHAR(3) DEFAULT 'non'", "maj" => "TIMESTAMP" ), 'key' => array( "PRIMARY KEY" => "id_breve", "KEY id_rubrique" => "id_rubrique", ), 'join' => array( "id_breve"=>"id_breve", "id_rubrique"=>"id_rubrique" ), 'statut' => array( array( 'champ'=>'statut', 'publie'=>'publie', 'previsu'=>'publie,prop', 'exception'=>'statut' ) ), 'texte_changer_statut' => 'breves:entree_breve_publiee', 'aide_changer_statut' => 'brevesstatut', 'statut_titres' => array( 'prop' => 'breves:titre_breve_proposee', 'publie' => 'breves:titre_breve_publiee', 'refuse' => 'breves:titre_breve_refusee', ), 'statut_textes_instituer' => array( 'prop' => 'breves:item_breve_proposee', //_T('texte_statut_propose_evaluation') 'publie' => 'breves:item_breve_validee', //_T('texte_statut_publie') 'refuse' => 'breves:item_breve_refusee', //_T('texte_statut_refuse') ), 'rechercher_champs' => array( 'titre' => 8, 'texte' => 2, 'lien_titre' => 1, 'lien_url' => 1 ), 'rechercher_jointures' => array( 'document' => array('titre' => 2, 'descriptif' => 1) ), 'champs_versionnes' => array('id_rubrique', 'titre', 'lien_titre', 'lien_url', 'texte'), ); return $tables; } Télécharger [1] qui regroupe notamment en une seule, plusieurs déclarations existantes auparavant [2] ce qui obligeait à dupliquer tout le code pour un nouvel objet, à ce détail près. Cette déclaration permet le support générique des objets dans action/editer_objet et ses fonctions objet_modifier/objet_inserer/objet_instituer Installation de SPIP3 tofulm — 2012-05-19T09:30:14Z Ce tutoriel commence à partir du moment ou vous avez téléchargé le dossier compressé de spip3 et que vous avez décompressé le contenu à la racine de votre serveur (le plus souvent un répertoire nommé www ou htdocs). Dans ce tutoriel, j'ai renommé le répertoire spip ainsi obtenu en spip3_test 1. Préparatifs - Configuration du serveur Apache Sur Linux, il est bon de modifier la configuration de base d'Apache. (En local, ce n'est pas indispensable, mais sur un serveur dédié cela permettra d'utiliser .htaccess) Voici la procédure (sous debian ou ubuntu) : 1. Activation de la Ré-écriture d'URL : module rewrite sudo a2enmod rewrite 2. Modification de la directive AllowOverride dans le Vhost editer le fichier default avec un éditeur de texte (gedit, vim, ...) sudo gedit /etc/apache2/sites-available/default modifier toutes les directives AllowOverride None par AllowOverride All 3. Relancer Apache sudo service apache2 restart 2. Préparatifs - Les droits d'accès En local, si vous êtes sur linux, vous allez devoir modifier les droits de 4 répertoires : Pour cela deux possibilités : avec votre gestionnaire de fichier, cliquez sur le répertoire en question et modifiez les droits. En ligne de commande, placez vous dans votre répertoires et tapez (il faut être en root) : chmod -R 777 local/ tmp/ config/ IMG/ (En fait les droits 777 ne sont pas obligatoires. Il faut seulement que le serveur (Apache ou autre) puisse y ecrire. Cela dépend donc du groupe et de l'utilisateur du fichier. Si c'est le serveur qui est le propriétaire de ces répertoires, 755 devrait suffire. Généralement apache correspond à www-data) Chez un hébergeur, utilisez votre client FTP (par ex. Filezilla) pour modifier les droits (clic bouton droit de la souris) 3. C'est parti ! Ouvrir son navigateur web (ex. Firefox) Entrer l'URL de votre répertoire racine de votre serveur. Si vous travaillez en local, tapez : localhost, autrement lisez la doc de votre hébergeur. 11-install_localhost Il ne vous reste plus qu'a cliquer sur votre dossier, ici spip3_test/ 4. A la découverte de SPIP Vous allez voir comme c'est très simple. A cette étape de l'installation il vous suffit de rajouter à l'url : ecrire. Vous devez obtenir : localhost/spip3_test/ecrire (n'oubliez pas de valider) 5. Installation – étape 1 : choix de la base de données. Par défaut SPIP3 utilise sqlite3 comme base de données. Dans la très grande majorité des cas il est inutile de modifier ce choix. Si sqlite3 n'apparaît pas, cela veut dire qu'elle n'est pas activée. Voici comment faire pour l'activer Petite explication de ce choix. MySQL est un serveur de BDD, c'est à dire qu'il nécessite une installation. Au contraire, Sqlite est un simple fichier que vous trouverez dans /config/bases. Si vous êtes limités en nombre de BDD, c'est parfait. Il faut simplement l'activer (si ce n'est déjà fait) Pour l'installation, Sqlite ne nécessite pas de code d'accès à la BDD. L'installation en est grandement simplifiée ! Pour administrer la BDD, une simple extension dans Firefox et le tour est joué. Il vous suffira de connecter une nouvelle base de données en choisissant le fichier dans le répertoire bases/. Gros avantage, la portabilité, tout est dans le dossier racine (ici spip3_test) L'accès en lecture est au moins aussi rapide que pour les autres BDD. C'est ce que l'on demande à une BDD pour un site internet, charger rapidement une page. Pour les fonctionnalités, on en a rien a faire, c'est SPIP qui se charge de tout (merci aux développeurs), et pour l'utilisateur ou le webmestre c'est complètement transparent. Ne vous posez plus de questions, laissez le choix par defaut ! 6. Installation – étape 2 : paramétrage de la BDD Vous pouvez, si vous le souhaitez changer le nom de la base de données. C'est le nom du fichier que vous retrouverez dans /config/bases/ Pour le préfixe des tables, laissé l'option par défaut : spip C'est tout, votre base de données est configurée, cliquez sur suivant. Si toute fois, vous voulez installer SPIP sur une base mysql, voici la démarche. 7. Installation – étape 3 : Informations personnelles Attention, le login sera celui du super administrateur, celui qui peut tout faire y compris tout casser et bloquer le site. Ne le perdez pas. Bien entendu, vous pourrez le modifier par la suite. 8. j'ai peur. Cela vient du fait que vous n'avez pas réalisé la Configuration du serveur apache 9. Installation – étape 4 : C'est terminé. Bravo ! Votre site SPIP est opérationnel mais vide. ANNEXES Installation de sqlite sur linux apt-get install sqlite3 apt-get install php5-sqlite Il ne vous reste plus qu'à relancer apache service apache2 restart Pour tous les autres systemes : Wampserver et EasyPhp pour windows, Mamp pour Mac, Xampp pour Linux Normalement cela devrait fonctionner par défaut. Parametrage de mysql Etape1 - identification Pour cela, ce n'est pas très compliqué non plus mais il faudra connaitre quelques informations supplémentaires : Adresse de la base de données : en local c'est localhost. Chez un hébergeur, c'est très souvent localhost. Le login de connexion : en local, par défaut c'est root sinon vous devez le savoir. Chez un hébergeur, il a dû vous le donner. Le mot de passe de connexion : en local, par défaut il n'y en a pas, sinon vous devez le savoir. Chez un hébergeur, il a dû vous le donner. Etape2 - creation de la base Choisissez votre base : soit vous utilisez une base existante (vous n'avez qu'à la cocher), soit vous créez une nouvelle base (ici j'ai choisi de l'appeler spip_test, mais vous pouvez mettre ce que vous voulez) Préfixe de tables : laissez spip Exemples de BOUCLE(DATA) Fil — 2012-05-19T09:30:11Z Quelques exemples de boucles (DATA) permises par les itérateurs de SPIP. Lister les plugins actifs Le format plugins ne nécessite pas de préciser les données. Boucle : #VALEUR Résultat : crayons memoization icalendar Afficher les « versions » de la configuration : critère {cle==...} Cette boucle itère sur la balise #CONFIG, comportant tous les éléments de configuration d'un site (tels qu'ils sont enregistrés dans la table spip_meta). Comme la balise #CONFIG est un tableau de données, on va employer le format table. Un critère {cle==version} filtre le tableau en ne retenant que les configurations dont la clé contient le mot « version ». Boucle : #CLE #VALEUR Résultat : version_installee 16428 revisions_base_version 1.1 Indexation_base_version 0.4 ... Le critère {liste ...} Pour simplifier l'écriture de tableaux de données, lorsqu'il s'agit d'une simple liste d'éléments qu'on veut indiquer manuellement, la boucle (DATA) accepte le critère {liste ...}, qui permet de constituer un tableau de données en séparant celles-ci par des virgules. Boucle : "}> [(#VALEUR|mult{#_i:VALEUR})] Résultat : 18 21 24 24 28 32 30 35 40 A noter : on a utilisé #_i:VALEUR pour référencer dans la boucle j la valeur calculée par la boucle i. Un fichier CSV Nous allons cette fois lire un fichier au format CSV se trouvant sur notre disque dur. Le fichier adresses.csv contient un carnet d'adresses : Fil,Philippe,fil@rezo.net,http://rezo.net/ Marcimat,Matthieu,marcimat@rezo.net,http://marcimat.magraine.net/ Boucle : {par /3} {" "}> #VALEUR{0} : #VALEUR{3} Résultat : Marcimat: http://marcimat.magraine.net/ Fil: http://rezo.net/ À noter : le critère de tri {par /3} permet de trier sur la colonne n° 3, contenant les adresses web. Le / initial est obligatoire dans le cas d'un tri sur une clé numérique ou commençant par un chiffre. Dans la démo de CSV livrée avec le plugin itérateurs, on trouvera un exemple beaucoup plus complet permettant de gérer proprement les clés du fichier CSV, et même de trier ou de fusionner sur ces clés. Lister le contenu d'un répertoire La fonction glob() de PHP permet de lister les fichiers correspondant à un masque ; elle a été transposée pour la boucle (DATA). Boucle : [(#VAL{Y-m-d H:i:s}|date{#VALEUR|filemtime})] / #VALEUR Résultat : 2008-02-01 23:27:23 / IMG/jpg/arton2135.jpg 2008-08-21 11:12:58 / IMG/jpg/DSC03420.jpg 2008-08-21 11:13:11 / IMG/jpg/DSC03421.jpg 2009-08-27 11:20:11 / IMG/jpg/hash-1.jpg 2009-08-27 11:20:04 / IMG/jpg/hash.jpg Lister les plugin.xml du site La fonction preg_files de SPIP permet de lister des fichiers selon une expression régulière et de manière arborescente. Plus versatile, mais plus lente que glob. Boucle : #VALEUR[ - (#VAL{Y-m-d H:i:s}|date{#VALEUR|filemtime})] Résultat : ../plugins/a2a/plugin.xml - 2011-04-16 20:47:02 ../extensions/simplog/plugin.xml - 2010-09-05 16:08:39 ../extensions/vertebres/plugin.xml - 2011-03-19 16:49:51 ../extensions/z-core/plugin.xml - 2010-09-05 16:08:47 Un webservice au format YAML Le site http://per.sonn.es/ propose une API permettant de lire chaque profil au format YAML. On va donc interroger le site sur l'un de ces profils, et parcourir le résultat pour afficher la liste des amis de la personne concernée. Commençons par analyser mon profil (à l'adresse http://per.sonn.es/Fil.yaml) : name: Fil sex: F birthday: '1966-08-17' job: Calorifugeur friends: - 'Maude Guérin' - 'Zohra Robin' - 'Pierre-Yves Philippe' - 'Lauriane Bertin' - 'Jeannine Pichon' - 'Vanessa Michel' - 'Wendy Allard' ... city: 'Mouxy (Rhone-Alpes)' Si l'on charge cette adresse avec le format yaml, on obtient un tableau de données un peu plus complexe que dans l'exemple précédent. En effet, certains items sont des chaînes de caractères, d'autres, comme la liste d'amis, des listes de chaînes. (name => Fil, sex => F, friends => ( Maude Guérin, Zohra Robin, ...), ... ). Parcourons ces données : Boucle : #CLE [(#VALEUR|print)] Résultat : name Fil sex F birthday 1966-08-17 job Calorifugeur friends Maude Guérin, Zohra Robin, Pierre-Yves Philippe, Lauriane Bertin, Jeannine Pichon, Vanessa Michel, Wendy Allard, Sylvie Michaud, Gwenaël Voisin, Paule Mary, Maia Ribeiro, Josianne François, Lucas Fernandes ... Maintenant, nous voulons boucler sur les amis de Fil. Pour cela il y a deux possibilités. La première consiste à récupérer les données avec notre boucle (DATA) au format yaml, puis à stocker le tableau d'amis dans une variable que nous allons parcourir avec une autre boucle (DATA), cette fois au format table : Boucle : #VALEUR Résultat : Maude Guérin - Zohra Robin - Pierre-Yves Philippe - Lauriane Bertin - Jeannine Pichon - Vanessa Michel - Wendy Allard - Sylvie Michaud - Gwenaël Voisin - Paule Mary - Maia Ribeiro Le critère {datapath ...} On voit bien dans l'exemple ci-dessus que, plus le tableau de données est complexe, plus les boucles qu'il va falloir imbriquer seront pénibles à coder. C'est là qu'intervient le critère {datapath ...}, qui permet d'indiquer à la boucle (DATA) le chemin (au sens de Xpath) vers le tableau de données qui nous intéresse. Avec cette balise notre liste d'amis s'écrit en une seule boucle (et on en profite pour ajouter une pagination) : Boucle : {source yaml, http://per.sonn.es/Fil.yaml} {datapath friends} {" - "}{pagination 10} > #VALEUR #PAGINATION Résultat : Maude Guérin - Zohra Robin - Pierre-Yves Philippe - Lauriane Bertin - Jeannine Pichon - Vanessa Michel - Wendy Allard - Sylvie Michaud - Gwenaël Voisin - Paule Mary 0 | 10 | 20 | 30 | 40 | ... Un fichier XML Le plugin « citations aléatoires » sur SPIP-Zone contient un fichier de citations, au format XML (http://zone.spip.org/trac/spip-zone/browser/_plugins_/citation_aleatoire/citations/citations_fr.xml). La boucle (DATA) permet de l'exploiter directement : Boucle : {source xml, #CHEMIN{citations/citations_fr.xml}} {par hasard} {0,1} {datapath citation} > #VALEUR{texte/0} [((#VALEUR{auteur/0}))] Résultat : L'idéal quand on veut être admiré, c'est d'être mort. (Michel Audiard) Un calendrier au format iCalendar/ics Il est aussi possible d'itérer sur les événements d'un calendrier publié au format iCalendar/ics. L'article consacré au plugin icalendar donne un exemple complet. Un document Google (spreadsheet) Dans Google Documents il est possible de « Partager > Publier un document ». Une fois cela fait, on peut récupérer l'adresse du document au format CSV, et l'afficher sous forme de table HTML. Boucle : #SET{key,0AolUP3c6K9JodGwxRjJzb2hyTGZLU29qRVItRXk1VXc} > #VALEUR{0} #VALEUR{1} #VALEUR{2} Résultat : Pays PIB Population Rémitanie 12 1 Baldoghistan 23 2 Républiques Unies 43 3 Diloduristan 12 4 Zarlatie 9 5 D'autres modes d'extraction sont possibles, notamment sous forme de liste, ou de cellules : Liste : Rémitanie pib: 12, population: 1 Baldoghistan pib: 23, population: 2 ... Cellules : A2: Rémitanie B2: 12 C2: 1 A3: Baldoghistan B3: 23 C3: 2 ... Dans l'article suivant, nous verrons des exemples de boucles chevelues à partir du webservice YQL. Deux itérateurs simples : les listes et les énumérations JLuc — 2012-05-19T09:30:06Z Parmis les nombreux et puissants itérateurs intégrés dans SPIP 3, il y en a 2 qui se distinguent par leur simplicité : les listes et les énumérations. Itérateur de liste L'itérateur de liste permet de parcourir les éléments d'une liste. Les éléments peuvent être des mots, des chiffres ou des petits morceaux de texte. Il s'appelle sous la forme d'un critère liste de la boucle DATA auquel on passe la liste des éléments devant être parcourus : Cette boucle présente une liste des premiers nombres premiers : (DATA){liste 2, 3, 5, 7, 11, 13}> #VALEUR Télécharger Il est possible d'utiliser tous les critères communs à toutes les boucles. Spécifier le séparateur : (DATA){liste janvier, février, mars, avril}{" ; "}> #VALEUR ([(#VALEUR|couper{3})]) Télécharger Affichera : janvier (jan) ; février (fév) ; mars (mar) ; avril (avr) Inverser l'ordre de parcours de la boucle : (DATA){liste 1, 10, 100, 1000}{", "}{inverse #ENV{envers}}> #VALEUR Télécharger Produira : "1, 10, 100, 100" ou "1000, 100, 10, 1" selon la valeur de 'envers' dans l'environnement. Ne boucler que sur un sous-ensemble de la liste : (DATA){liste janvier, février, mars, avril, mai, juin, juillet}{", "}{3,2}> #VALEUR Télécharger sautera 3 mois et en présentera 2, soit : "avril, mai". Les valeurs des bornes peuvent être calculées : (DATA){liste #GET{couleurpreferee}, #ENV{couleurchoisie}}{", "}> #VALEUR Télécharger Itérateur énumération L'itérateur d'énumération est une boucle très simple. Son utilisation la plus générale est de la forme (DATA){enum val1, val2}> #VALEUR Télécharger ou (DATA){enum val1, val2, pas}> #VALEUR Télécharger val1 et val2 sont 2 valeurs numériques, ou bien 2 caractères. Cette boucle va énumérer les valeurs entre val1 et val2. Dans la première forme, le pas n'est pas précisé : il vaut 1 par défaut. Entiers, pas de 1 : (DATA){enum 10,15}{", "}>#VALEUR Boucle sur les valeurs en commençant à 10 et en s'arrêtant avant 15 et renvoie donc "10, 11, 12, 13, 14". Décimaux, pas de 1 : (DATA){enum 15.5,10.3}{", "}>#VALEUR Boucle sur les valeurs en commençant à 15 et en s'arrêtant avant 10 et renvoie donc "15.5, 14.5, 13.5, 12.5, 11.5, 10.5". Entiers, pas de 2 : (DATA){enum 10, 15, 2}{", "}>#VALEUR Boucle sur les valeurs de 10 à 15, par pas de 2, et renvoie donc "10, 12, 14". Lettres : (DATA){enum g,m}{", "}>#VALEUR Boucle sur les caractères de "g" jusqu'à "m" et renvoie donc "g, h, i, j, k, l, m". #PRODUIRE JLuc — 2012-05-19T09:30:01Z La balise #PRODUIRE produit un fichier statique a partir d'un squelette dynamique de CSS (.css.html) ou de javascript (.js.html) La syntaxe de la balise #PRODUIRE est la même que celle de #INCLURE mais produit le résultat dans un fichier statique dont elle renvoie le nom. Cela permet ensuite à apache de servir ce fichier statique directement, sans passer par spip.php à chaque hit. <link rel="stylesheet" type="text/css" href="#PRODUIRE{fond=css/macss.css,couleur=ffffff}" /> Le format du fichier est indiqué par la pré-extension du fichier : .css.html ou .js.html. Sinon, c'est html. On peut forcer le format du fichier avec un argument supplémentaire format=css ou format=js passé en argument. _LOG_FILELINE b_b — 2012-05-19T09:29:58Z Utile en période de debugage, define('_LOG_FILELINE',true); permet d'ajouter dans les logs le fichier, la ligne et le nom de la fonction d'où le log est généré. - Variables et Constantes de personnalisation / SPIP 3.0

Explication	nom raccourci de la table
Exemple	articles pour spip_articles
Valeur par défaut	nom de la table sans spip_
dans SPIP 2.1	non déclaré

Explication	synonymes de table_objet pour les cas particuliers
Exemple	pas de surnom pour articles (mais exemple : groupe_mots pour spip_groupes_mots)
Valeur par défaut	pas de surnom
dans SPIP 2.1	via declarer_tables_objets_surnoms

Explication	nom court de l'objet
Exemple	article pour la table spip_articles
Valeur par défaut	clé primaire sans id_ au début ni s a la fin, ou à défaut nom de la table sans spip_ au début ni s a la fin
dans SPIP 2.1

Explication	synonyme du type pour les cas particuliers
Exemple
Valeur par défaut	pas de surnom
dans SPIP 2.1

Explication	Déclaration SQL des champs de la table
Exemple	array( "id_article" => "bigint(21) NOT NULL", "surtitre" => "text DEFAULT '' NOT NULL", "titre" => "text DEFAULT '' NOT NULL", "soustitre" => "text DEFAULT '' NOT NULL",...)
Valeur par défaut	héritée de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité)
dans SPIP 2.1	Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe

Explication	Déclaration SQL des clés de la table
Exemple	array( "PRIMARY KEY" =>"id_article", "KEY id_rubrique" => "id_rubrique",...)
Valeur par défaut	hérité de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité)
dans SPIP 2.1	Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe

Explication	les champs déclarés explicitement pour les jointures. sinon les jointures se feront exclusivement sur la clef primaire. attention : les champs 'idx', 'maj', 'date' et 'statut' ne peuvent PAS être déclarés comme champs de jointure possible.
Exemple	array( "id_article"=>"id_article", "id_rubrique"=>"id_rubrique")
Valeur par défaut	hérité de la déclaration $tables_principales ou $tables_auxiliaires si existante (compatibilité)
dans SPIP 2.1	Remplace la déclaration incluse dans le pipeline declarer_tables_principales, avec la même syntaxe

Explication	déclaration de la table de liens et de son champ de jointure. on joindra ainsi (par exemple) id_article, articles à id_auteur, auteurs en passant par la table auteurs_liens et ses lignes id_auteur, id_objet, objet (donc, ici : id_auteur, id_article, articles)
Exemple	array('id_auteur' => 'auteurs_liens')
Valeur par défaut	hérité de la déclaration $tables_jointures si existante (compatibilité)
dans SPIP 2.1	$declarer_tables_objets_sql['spip_articles']['tables_jointures'] reprend l'ancien contenu de $tables_jointures['spip_articles']

Explication	Indique si la table est table principale ou auxiliaire ; prend les valeurs 'oui' ou 'non'
Exemple	'oui'
Valeur par défaut	hérité de la déclaration $tables_principales si existante (compatibilité)
dans SPIP 2.1	Remplace l'affectation des tableaux dans le pipeline declarer_tables_principales ou declarer_tables_auxiliaires

Explication	permet de déclarer les modèles associés a cet objet
Exemple	exemple pour spip_documents : array('document', 'doc', 'img', 'emb', 'image', 'video', 'text', 'audio', 'application')
Valeur par défaut	la valeur de type
dans SPIP 2.1

Explication	Représentation SQL qui permet de récupérer le titre et la langue de l'objet
Exemple	"titre, lang"
Valeur par défaut	hérité de la déclaration $tables_titre (compatibilité) ou vide sinon
dans SPIP 2.1	Remplace la déclaration du titre de l'objet dans le pipeline declarer_tables_interfaces : `$interface['table_titre']['articles'] = "titre, '' AS lang";`

Explication	déclare le champ date de l'objet utilisé pour le dater
Exemple	date
Valeur par défaut	hérité de la déclaration $tables_date ou vide
dans SPIP 2.1	Remplace la déclaration de la date de l'objet dans declarer_tables_interfaces : `$interface['table_date']['articles'] = "date";`

Explication	Déclaration du statut pour l'objet
Exemple	array(array( 'champ' => 'statut', 'publie' => 'publie', 'previsu' => 'publie,prop,prepa', 'post_date' => 'date', 'exception' => 'statut'))
Valeur par défaut	vide
dans SPIP 2.1	Remplace la surcharge des boucles avec conditions where pour gerer le statut. Ici la déclaration est directement prise en compte dans les boucles génériques

Explication	Chaines de langue du titre de chaque statut. Définit par la même la liste des statuts autorisés
Exemple	array( 'prepa'=>'info_article_redaction', 'prop'=>'info_article_propose', 'publie'=>'info_article_publie', 'refuse'=>'info_article_refuse', 'poubelle'=>'info_article_supprime')
Valeur par défaut	null
dans SPIP 2.1

Explication	definit les puces associées à chaque statut
Exemple
Valeur par défaut	null
dans SPIP 2.1	Pas d'équivalence

Explication	Chaines de langue du libellé de chaque statut dans le bloc instituer de l'objet
Exemple	array( 'prepa' => 'texte_statut_en_cours_redaction', 'prop' => 'texte_statut_propose_evaluation', 'publie' => 'texte_statut_publie', 'refuse' => 'texte_statut_refuse', 'poubelle' => 'texte_statut_poubelle')
Valeur par défaut	null
dans SPIP 2.1	Pas d'équivalence

Explication	Le nom de la page publique de l'objet
Exemple	article
Valeur par défaut	type si principale='oui', rien sinon
dans SPIP 2.1	Remplace la déclaration de l'url de l'objet dans le pipeline declarer_url_objets()

Explication	nom de l'exec privé pour voir l'objet
Exemple	article
Valeur par défaut	type
dans SPIP 2.1

Explication	nom de l'exec privé pour éditer l'objet
Exemple	article_edit
Valeur par défaut	type+_edit
dans SPIP 2.1

Explication	donner acces à une page d'édition dans l'espace privé
Exemple	'oui' ou false
Valeur par défaut	oui
dans SPIP 2.1

Explication	Liste des champs de l'objet pouvant être modifiés dans le formulaire d'édition
Exemple	array('surtitre', 'titre', 'soustitre', 'descriptif','nom_site', 'url_site', 'chapo', 'texte', 'ps','virtuel')
Valeur par défaut	vide
dans SPIP 2.1	listés explicitement dans la fonction articles_set de action/editer_article [2]

Explication	nom du fichier d'icône fourni en 16/24/32px
Exemple	article
Valeur par défaut	type
dans SPIP 2.1

Explication	Liste des champs de l'objet soumis au processus de révisions
Exemple	array('id_rubrique', 'surtitre', 'titre', 'soustitre', 'jointure_auteurs', 'descriptif', 'nom_site', 'url_site', 'chapo', 'texte', 'ps')
Valeur par défaut	array()
dans SPIP 2.1

Explication	Déclaration des champs utilisés dans la recherche et de leur score respectif
Exemple	array( 'surtitre' => 5, 'titre' => 8, 'soustitre' => 5, 'chapo' => 3,...)
Valeur par défaut	array()
dans SPIP 2.1	Remplace la déclaration incluse dans le pipeline rechercher_liste_des_champs : même syntaxe

Explication	Déclaration des champs et de leurs scores respectifs utilisés via une jointure lors de la recherche. Préciser la table de ces champs en premier élément de l'array.
Exemple	array( 'auteur' => array('nom' => 10) )
Valeur par défaut	array()
dans SPIP 2.1	Remplace la déclaration incluse dans le pipeline rechercher_liste_des_jointures : même syntaxe

Explication	Chaine "Ajouter un ..."
Exemple	titre_ajouter_un_auteur
Valeur par défaut	texte_ajouter_type
dans SPIP 2.1

Explication	Chaine de langue du bouton retour dans la page d'édition de l'objet
Exemple	icone_retour_article
Valeur par défaut	icone_retour
dans SPIP 2.1

Explication	Chaine de langue du bouton modifier permettant d'ouvrir le formulaire d'édition de l'objet
Exemple	icone_modifier_article
Valeur par défaut	type:icone_modifier_type
dans SPIP 2.1

Explication	Chaine de langue du bouton de création d'un nouvel objet
Exemple	icone_ecrire_article
Valeur par défaut	type:icone_creer_type
dans SPIP 2.1

Explication
Exemple	creer_et_associer_un_auteur
Valeur par défaut	type:texte_creer_associer_type
dans SPIP 2.1