Framework Z dans SPIPr

Documentation source http://spipr.nursit.com/framework-z

Z pour SPIP

Le framework Z est disponible pour SPIP sous la forme du plugin Z-core. Il prend en charge tous les automatismes du framework, et intègre les briques de bases sur lesquelles sont construites SPIPr.

Organisation des blocs de page

Dans SPIPr il a été choisi de découper le corps de la page en 6 blocs déclinables page par page, nommés et organisés comme suit :

  • header est le bloc d’en-tête de la page ;
  • breadcrumb est le bloc de navigation fil d’Ariane de la page ;
  • content est le bloc de contenu principal de la page : cest lui qui pilote l’existence d’une page ;
  • aside est un bloc de contenu secondaire, plutôt dédié à ce qui est en relation avec le contenu principal de la page ;
  • extra est un autre bloc de contenu secondaire, pour ce qui n’a pas de rapport direct avec le contenu principal de la page ;
  • footer est le bloc de pied de la page ;

Par ailleurs, le plugin Z-core ajoute 2 blocs de meta-contenu supplémentaires, qui concernent la partie <head> de la page :

  • head est le contenu éditorial spécifique à la page (<title> et autres <meta> descriptions ;
  • head_js permet d’ajouter des scripts externes spécifiques à la page (ils ne seront pas concaténés avec les scripts communs à toutes les pages). Ces deux derniers blocs ne concernent pas du contenu visible de la page, mais fonctionnent de la même façon.

Ce découpage en blocs est une convention choisie et utilisée par SPIPr. Vous pouvez la modifier ou la personnaliser, mais alors il se peut que certains thèmes ou plugins ne fonctionnent plus automatiquement, et vous devrez adapter au cas par cas à votre convention de nommage des blocs.

Organisation des dossiers

Pour chaque bloc de la page, un dossier homonyme contient les squelettes de chaque page. On utilise donc 8 dossiers homonymes aux blocs :

  • header/
  • breadcrumb/
  • content/
  • aside/
  • extra/
  • footer/
  • head/
  • head_js/

En complément, on utilise le rangement dans les dossiers suivants :

  • inclure/ contient les squelettes inclus transverses, c’est à dire commun à plusieurs pages du site
  • img/ contient les images utilisées par les squelettes
  • css/ contient les feuilles de style au format CSS ou LESS
  • css/img/ contient les images décoratives utilisées par les feuilles de style

A la racine, subsistent certains squelettes utilies pour SPIP, comme 404.html, article.html, auteur.html, backend.html, breve.html, forum.html, mot.html, rubrique.html, site.html.

À l’exception du flux RSS (backend.html), tous ces squelettes sont réécrits de façon minimale pour inclure structure.html qui produira toutes les pages. Vous pouvez donc oublier tous ces squelettes issus de la dist : vous n’aurez plus besoin de les manipuler, sauf cas exceptionnel.

Z-core fournit le squelette structure.html qui sert à la fabrication de toutes les pages. Ce squelette pose la structure minimale de la page HTML, inclut les squelettes chargés de produire le head, puis le body.html qui définit le layout unique et sur lequel nous revenons ci-dessous plus en détail.

Layout unique

Le layout unique facilite l’homogénéité des pages du site, et simplifie la maintenance du site dans le temps.

Le framework Z permet donc d’organiser toutes les pages du site autour d’un layout unique décrit par le squelette body.html qui appelle les 6 blocs de contenus déclinables vu plus haut ainsi qu’une barre de navigation commune à tout le site et les organise à sa guise dans le HTML.

Le layout par défaut de SPIPr est simple :

Nous voyons que ce layout par défaut ne comporte qu’une unique colonne #aside, laquelle intègre le contenu des blocs de aside et extra.

Layouts spécifiques

Certaines pages du site peuvent nécessiter un layout spécifique, différent de celui utilisé sur le reste du site. Pour cela il suffit de créer un squelette de layout suffixé par le nom de la page.

Par exemple, si le layout body-sommaire.html existe, il sera utilisé pour la page sommaire et seulement pour celle-ci.

De même, si le layout body-article.html existe, il sera utilisé pour toutes les pages article du site.

Pages automatiques

Le framework Z intègre un mécanisme de génération automatique des pages complètes à partir du seul squelette de contenu principal.

Par exemple, il suffit d’écrire un squelette minimal content/inscription.html contenant simplement :

pour que la page complète spip.php?page=inscription soit disponible.

Pour réaliser cela Z utilise les éléments communs inclure/entete.html, inclure/barre-nav.html et inclure/pied.html.
Pour les autres parties de la page, Z utilise par défaut le squelettes aside/dist.html si aucun squelette aside/inscription.html, extra/dist.html si aucun extra/inscription.html n’est défini et ainsi de suite pour les blocs header, footer, ...

Ce mécanisme de pages automatiques permet d’ajouter, aussi rapidement que facilement, des pages spécifiques, en cohérence immédiate avec le reste du site. De même, il permet aux plugins SPIP de fournir des pages dédiées, utilisables sur tous les sites reposant sur Z, quelle qu’en soit leur structure, laquelle sera automatiquement fournie par le squelette.

Cette création rapide de page s’applique aussi bien à des pages particulières du site, isolées, comme la page inscription précédente, mais aussi aux pages des objets éditoriaux.
Il suffit de proposer par exemple un squelette content/evenement.html avec les boucles nécessaires pour créer une page de site pour chaque événement de la table spip_evenements

Echafaudage de page d’objet éditorial

Pour un nouvel objet éditorial associé à une table SQL, il est même possible de visualiser une page sans écrire une seule ligne de squelette.

Cette fonctionnalité est réservée aux webmestres, pour ne pas risquer de divulguer des informations non publiques aux autres utilisateurs du site (il faut avoir le statut webmestre, qui est affiché sur la page de chaque auteur dans l’interface de rédaction de SPIP).

En ayant le statut de webmestre, vous pouvez visualiser la page de tout nouvel objet éditorial existant. Si par exemple vous avez ajouté un objet evenement dans une table spip_evenements, vous pouvez visualiser sa page à l’url spip.php?page=evenement&id_evenement=1.

Z essayera alors de construire une page avec un squelette content/evenement.html. Si il ne le trouve pas, il va construire à la volée un squelette en se basant sur la structure de la table spip_evenements.

Ce squelette construit automatiquement vous permet de visualiser les données, et peut être utilisé comme point de départ à l’écriture de votre « vrai » squelette.

Pour ce faire, ajoutez &var_mode=inclure dans l’url pour visualiser le nom du squelette généré par Z et le copier ainsi dans votre dossier squelettes/ avant de le personnaliser.

Si vous utilisez le plugin SkelEditor cette opération est facilitée au maximum :

  • le bouton Squelettes&CSS vous permet de passer en &var_mode=inclure,
  • un clic sur le nom du fichier source échafaudé vous permet de l’éditer directement dans l’espace privé,
  • un clic sur Enregistrer vous permet d’en enregistrer une copie dans le dossier squelettes.

Notes

[1Le projet est né sous la forme d’un squelette pour SPIP, puis a pris son indépendance comme framework