Chats 2 - SPIP 3 Créer un nouvel objet dans le futur SPIP 3 (en développement)

, par Matthieu Marcillaud

Il y a presque deux ans, j’écrivais l’article Créer un nouvel objet éditorial en mettant des félins dans l’interface privée. Le développement de SPIP 3.0 (en alpha2 actuellement) fait des prouesses extraordinaires pour tout ce qui est la création et l’utilisation de nouveaux objets éditoriaux. Je propose ici de décrire la création d’une version 2.0 du plugin d’exemple Chats, en partant de rien.

SPIP 3.0 alpha 2

C’est le nom de la version en cours de développement et qui externalise un certain nombre de fonctionnalités de SPIP, tout en rendant générique un grand nombre de processus habituels (Cédric a effectué là de biens beaux travaux !). Cette version se voit dotée d’un espace privé entièrement en squelettes (et donc facilement surchargeable), découpé en Z, tout en normalisant le code HTML sous-jacent qui en avait besoin. Certaines fonctions anciennement en plugin ont été intégrées : les itérateurs, une partie de CFG, une partie de Bonux, Textwheel, Job Queue, et d’autres ont atterri en tant qu’extension par défaut de la distribution SPIP comme la médiathèque ou le plugin de boites modales (mediabox). La liste est longue des nouveautés et comme c’est encore loin d’être finalisé nous nous attarderons juste sur ce qui nous intéresse pour notre nouvel objet éditorial.

Il faut noter tout de même que dans cette nouvelle version, on peut déclarer, comme on le faisait pour déclarer des tables SQL à SPIP un nouvel objet éditorial. Ceci fait, la simple présence d’un champ « id_rubrique » permet de ranger l’objet dans une rubrique. La simple présence de « lang » permet de gérer des langues... la simple présence de « id_trad » permet de gérer les traductions... la simple déclaration de l’objet permet d’y lier des mots, des documents, des forums, de gérer les révisions de l’objet, déclarer des statuts permet d’afficher l’encart de changement de statut, d’accéder aux prévisualisations, ... Enfin presque !

Voilà... SPIP 3, c’est ça... mais c’est aussi que... on peut pratiquement ne rien écrire, SPIP est capable de générer à la volée une partie des pages nécessaires à l’affichage de l’objet si elles n’existent pas dans le plugin (ou en tant que surcharge ailleurs).

En fait, à l’heure ou j’écris, il faut tout de même écrire le code HTML du formulaire, et son code PHP. Mais vous allez voir que c’est impressionnant !

Débuter le plugin

Créons un plugin « chats » dans notre dossier plugins/ avec les fichiers :

  • paquet.xml
  • prive/themes/spip/images/chat-24.png de même que -48, -128 et -16
  • base/chats.php
  • chats_administrations.php
  • lang/chat_fr.php
  • lang/paquet-chats_fr.php

Nous allons les remplir au fur et à mesure. Tout d’abord, le paquet.xml.

paquet.xml

Comme on le remarque, la déclaration se fait maintenant avec un fichier nommé « paquet.xml » en lieu et place de « plugin.xml » (ce dernier est toujours compris par SPIP 3.0 alpha 2). « paquet.xml » a une écriture plus cohérente et concise.

Peu de choses ont changé dans les pipelines à l’exception notable, d’un nouveau pipeline pour déclarer l’objet (et sa table SQL). Il se nomme « declarer_tables_objets_sql ».

Enfin, une partie des descriptions du plugin (slogan, descriptif et éventuellement le nom) passent dans les chaînes de langue (lang/paquet-chats_fr.php), et peuvent ainsi être traduits.

Nous retrouvons

  • le nom, l’auteur, la version
  • l’état (stable, test, dev)
  • le préfixe
  • la version de la structure des tables SQL du plugin se nomme maintenant « schéma »

chats_administrations.php

Le fichier d’installation, simple. Il peut changer (par rapport à SPIP 2.1) car on peut maintenant dans les mises à jour d’un plugin utiliser la même procédure que celle de SPIP Core pour les déclarer. Ainsi, une fonction « maj_plugin » permet de passer : la version actuelle, la version future, et un tableau de la liste des actions à faire. Contentons nous de la création et de la suppression du plugin :

Dans la variable $maj la clé « create » est appliquée à la première installation du plugin, et contient un tableau listant les fonctions à appeler avec leurs paramètres. Ici, on appelera donc l’équivalent de : maj_tables('spip_chats');.

Pour une mise à jour, on utilise par exemple $maj['numéro'] = array(...) tel que $maj['1.1.0'] = .... Nous le verrons plus loin.

base/chats.php

Le fichier de déclaration comporte les fonctions appelées par le pipeline « declarer_tables_objets_sql ». Voyons cela :

Ce tableau de la table peut prendre de nombreux autres attributs. Ils sont optionnels et complétés automatiquement par SPIP en absence de leur déclaration pour certains. Nous en verrons quelques-uns par la suite.

Nous remarquons les déclarations ’field’ et ’key’ qui n’ont pas changé, présentant le nom des champs et leur description SQL pour ’field’, de même que le type de clé et le ou les champs d’application pour ’key’.

La clé "principale" indique que la table est une table qui s’auto-incrémente. Les clés "titre" et "date" (déclarées avant dans le pipeline declarer_tables_interfaces) indiquent respectivement les colonnes servant au calculs des titres d’URLs, et aux calculs de date (si besoin).

Pour pouvoir utiliser l’alias de boucle CHATS à la place du nom complet spip_chats, comme dans <BOUCLE_liste(CHATS){par titre}>...</BOUCLE_liste>, il faut déclarer cet alias via le pipeline declarer_tables_interfaces :

lang/paquet-chats.php

Mettons un peu de texte sur la signification du plugin dans le fichier lang/paquet-chats.php , tel que :

Ces descriptions pourront ainsi être traduites. Remarque : chats_nom n’est pas encore pris en compte à l’heure de l’écriture de ces lignes, mais c’est prévu.

Premier test

À partir de maintenant, le plugin doit pouvoir s’activer et s’installer. Il est présent dans la liste des plugins.

Affichage du plugin dans la liste des plugins
En cas d’erreurs dans le fichier paquet.xml, celles-ci seraient affichées de façon précise.

Une fois coché, et la configuration enregistrée, l’activation indique l’état de l’installation. Ici, le plugin installe la version 1.0 de sa structure SQL.

Activation du plugin chats
La version 1.0.0 du plugin chats est installée.

On peut alors aller sur l’URL privée ?exec=chats qui affiche en clignotant (pour l’instant) cela :

Liste des chats...
Les chaînes de langues absentes sont affichées en rouge

Ajout d’un bouton d’accès et des chaînes manquantes

Pour pourvoir accéder à la page ?exec=chats facilement, nous allons créer un bouton dans le menu, depuis la déclaration de paquet.xml. On en profitera pour ajouter dans la foulée un bouton d’ajout rapide d’un chat. Ces 2 lignes sont donc ajoutées à paquet.xml :

Il faudra ajouter une image « chat-new-16.png » qui est la même que « chats-16.png », avec un + de dessiné. Cette image (pour faciliter la création) se trouve dans SPIP dans prive/themes/images/add-16.png

Nous pouvons ensuite ajouter quelques chaînes de langue dans le fichier lang/chat_fr.php. Attention dans le nom du fichier : ici, c’est l’objet désiré au singulier, alors que pour le fichier de langue du paquet, c’est le préfixe du plugin qui est utilisé.

Aussitôt, on peut voir (en repassant sur la page d’administration des plugins pour mettre à jour les informations du paquet) les icônes et le texte :

Icone de chat rapide, et chaînes de langues présentes

Voilà qui est maintenant plus clair. On comprend que SPIP génère automatiquement cette page, car nous n’avons créé encore aucun squelette pour afficher quoi que ce soit. Cela pourrait être fait, mais nous allons essayer le lui faire faire le maximum de chose sans rien toucher.

Créer un chat

En cliquant le bouton de création d’un chat, on voit qu’il manque des choses :
une chaîne de langue... et un formulaire !

Édition d’un chat.
Il manque le formulaire !

La chaîne de langue va dans lang/chat.php en ajoutant

Par la suite, et pour simplifier, je ne parlerai plus de l’ajout des chaînes de langue dans ce fichier. Vous saurez faire de toutes façons :)

Pour le formulaire, il va falloir un peu plus de travail, en créant les fichiers :

  • formulaires/editer_chat.html et
  • formulaires/editer_chat.php

Le fichier HTML est semblable à SPIP 2.1 et utilise ici le plugin « saisies » :

Le fichier PHP appelle des fonctions génériques de traitement des objets :

Enfin, dans la déclaration de l’objet (base/chats.php), il faut indiquer à SPIP les champs qu’il a le droit de modifier en ajoutant la clé :

Avec quelques chaînes de langues en plus, voici ce que l’on obtient : le formulaire est visible et fonctionne (cependant il ne réaffiche pas les textes saisis après une création).

Formulaire de modification du chat

La liste des chats liste les créations.

Liste des chats

Enfin, la vue d’un chat permet de changer la date de publication et de mettre un logo. Elle n’affiche pas automatiquement autre chose que le titre.

Vue d’un chat

Lier des documents et des mots clés

Pour lier des documents au chat il suffit de cocher les « Chats » dans la configuration des documents sur ?exec=configurer_contenu.

Pour lier des mots clés, il suffit de créer un groupe de mot permettant la liaison avec des chats.

Mots clés, document et logo

Versionner les modifications des chats

Pour pouvoir revenir sur des modifications effectuées sur le contenu de la table chats, il faut indiquer quels champs sont versionnables, puis activer les « révisions » sur l’objet Chats (?exec=configurer_revisions). On ajoute donc, dans la déclaration de notre objet éditorial :

Sur l’accueil, on peut ainsi suivre les modifications faites, puis revenir dessus éventuellement depuis la page des révisions :

Révisions sur l’accueil
Révision d’un chat

Lier les chats aux rubriques

Pour pouvoir lier un chat à une, et une seule rubrique, il suffit de créer un champ « id_rubrique » dans la table spip_chats et d’ajouter un sélecteur de rubrique dans le formulaire d’édition.

Déclarons le dans base/chats.php, avec les autres champs :

Créons la mise à jour dans chats_administrations.php en ajoutant la version 1.1.0, qui ajoute le champs id_rubrique et un index dessus :

Changeons le schéma dans paquet.xml pour refléter la mise à jour :

Enfin, ajoutons un sélecteur de rubrique sur le formulaire d’édition (repris de celui sur le formulaire d’édition d’un article) :

Et regardons maintenant :

Choix d’une rubrique

Afficher les chats sur les rubriques

Pour aller plus loin, on va vite souhaiter pouvoir créer et voir des chats depuis les rubriques. Pour cela, il va nous falloir d’une part se brancher sur le pipeline « affiche_enfants », et d’autre part créer un premier squelette de liste de chats, permettant de trier les chats, mais surtout de filtrer par rubrique la liste.

Ajoutons l’utilisation du pipeline dans paquets.xml :

Ajoutons dans le pipeline, l’appel à notre future nouvelle liste d’éléments, ainsi que le bouton pour ajouter de nouveaux chats si l’on peut. Avec la fonction trouver_objet_exec() qui retourne des informations utiles sur la page en cours de lecture dans l’espace privé, on peut filtrer l’affichage sur le type d’objet, et le fait qu’il soit ou non en édition.

La fonction lister_objet permet d’appeler un squelette affichant une liste de l’objet souhaité. Il est stocké dans prive/objets/liste/chats.html. Son code peut ressembler à ça :

On peut ainsi voir la liste des chats appartenant à une rubrique, dans la vue de la rubrique :

Chats dans une rubrique

Donner sa langue au chat

La présence des champs "lang" et "langue_choisie" dans la table SQL des chats suffit à faire afficher un formulaire de changement de langue de l’objet. Ajoutons les.

Dans base/chats.php ajouter :

Dans base/chats_administrations.php ajouter :

Enfin, changer la version du schéma dans paquet.xml :

Après un passage sur la page d’administration des plugins pour effectuer la mise à jour, sur la page de configuration de multilinguisme, on peut cocher la présence du formulaire de langue sur les Chats :

Configuration du multilinguisme

Ainsi, pour tout nouveau chat créé, le formulaire de langue s’affiche et on peut modifier la langue (pour peu qu’il y ait au moins 2 langues possibles dans la configuration du multilinguisme). Pour les anciens chats, il faudrait faire une mise à jour de la base en leur définissant une langue par défaut, sinon, le bouton [changer] n’apparaît pas.

Langue au chat

Traductions de chats

Sur le même principe que précédemment, on ajoute le champ « id_trad » tel que :

Sur la page de configuration du multilinguisme, il faut cocher la gestion des traductions sur les chats :

Gestion des traductions sur les chats

Il faut aussi appeler des fonctions qui vont peupler le formulaire de création d’un chat, traduction d’un autre, par les textes de la traductions. Pour cela, il faut créer le fichier inc/precharger_chat.php contenant au moins la première fonction (la seconde étant facultative si on ne change pas le code qui est présenté ici) :

On peut ainsi traduire un chat :

Formulaire de traduction d’un chat
Traduction préremplie du texte d’origine

Lier des auteurs aux chats

On pourrait créer le squelette qui affiche le contenu de notre chat, qui afficherait le formulaire de liaison entre auteurs et chat dedans, ainsi que les autres formulaires souhaités.

Nous pouvons aussi continuer d’utiliser le squelette créé automatiquement par SPIP et se brancher sur le pipeline « affiche_milieu » pour ajouter le formulaire d’auteurs sur les chats. C’est ce que nous allons voir ici. Dans paquet.xml, on ajoute l’appel au pipeline :

Son utilisation appelle l’inclusion de SPIP prive/objets/editer/liens, qui elle-même appelle le formulaire éditer liens, permettant de lier 2 objets entre eux et d’afficher les liaisons existantes. Il suffit d’indiquer la source (les auteurs) et la cible, et le tour est joué :

Auteurs liés à un chat

Mettre des statuts sur les chats

Pour mettre des statuts de publication sur les chats, il faut un champ « statut » sur la table SQL, quelques déclarations et des chaînes de langues, éventuellement quelques autorisations.

Sur le principe habituel, on ajoute le champ statut dans la déclaration de base/chats.php (il faudra faire une mise à jour dans chats_administrations.php).

Le code de la mise à jour ajoute aussi la valeur "publie" a tous les chats déjà existants :

On ajoutera aussi une déclaration des statuts prévus, toujours dans la déclaration de l’objet, ainsi qu’une description des critères limitant l’affichage d’une boucle CHATS en fonction du statut du chat :

La clé statut_textes_instituer indique la liste des statuts de notre objet éditorial ainsi que le nom des chaînes de langue correspondantes.

La clé statut dit à peu près : que restreint-on d’afficher en fonction de tel champ ? La restriction porte sur quel champ SQL ? Quel est la valeur de ce champ lorsqu’un chat est publié, lorsqu’il peut être prévisualisé. Y a t’il une date à prendre en compte pour ne pas publier les chats avant une certaine date (post_date) ? et quels critères de boucles annulent la prise en compte de cette restriction : ici {statut} et {tout}.

Statuts sur les chats

Lier des chats à des articles

Voici la plus grosse partie des squelettes et codes PHP à produire dès lors que l’on veut lier notre objet à 0 ou plusieurs autres objets, depuis la page de ceux-ci, par exemple lier des chats à des articles, depuis la page d’un article.

Pour installer un formulaire de liaison de chats sur les articles, un peu comme pour les auteurs précédemment, il va falloir insérer le formulaire sur les articles, en utilisant le même pipeline affiche_milieu. Il faut avant tout qu’il existe une table spip_chats_liens pour pouvoir lier des chats. Créons tout ça.

Dans paquet.xml, on change le schéma, et on ajoute le pipeline declarer_table_auxiliaires :

On déclare dans ce pipeline notre table de liaison :

On crée la mise à jour dans chats_administrations.php :

Ceci fait, il va nous falloir créer plusieurs squelettes de liste. Le premier prive/objets/liste/chats_lie.html est une liste affichée lorsque des chats sont liés à un objet.

Il peut être (inspiré de celui des mots-clés) :

La seconde liste est utilisée pour rechercher des chats à lier, et doit se créer dans prive/objets/liste/chats_associer.html. Il peut être ainsi, et fait appel à un troisième squelette s’il y a un trop grand nombre de chats :

Lorsqu’il y a trop de résultats à afficher, c’est un autre squelette qui est appelé, prive/objets/liste/chats_associer-recherche.html qui offre un champ de saisie pour rechercher parmi les chats afin de restreindre les résultats. Il peut être :

Note : Il y a certainement moyen de regrouper ces 2 derniers squelettes en un seul, mais je n’ai pas pris le temps de le faire.

On obtient donc, sur la page d’un article :

Des chats sur les articles

Permettre de chercher des chats

Pour permettre la recherche de chat dans l’espace privé ou via le critère {recherche} sur une boucle chat, il faut le déclarer dans la description de l’objet, en ajoutant dedans :

Recherche parmi les chats

Conclusion

Voilà une petite démonstration prometteuse donc, pour ce qui concerne les objets éditoriaux. L’espace privé utilisant Zpip permet d’adapter facilement les pages que créée SPIP, ce qui n’est pas montré ici. Une prochaine fois peut être :)