Les Noisettes du « Noisetier » (doc de dev)

Ceci est une archive périmée mais qui reste intéressante, parfois autant pour l’article que les commentaires associés.

Attention, cette contribution est EN CHANTIER : elle n’est peut-être pas fonctionnelle.

Nota : une contrib au développement arrêté par son créateur, pour laisser la place au noiZetier.

Cette page vise à décrire les spécificités des noisettes qui seront gérées par le Noisetier ainsi que leurs différentes options : variables d’environnement, mots-clés, paramètres, ... ,

Attention :

Cette page est un début de documentation du projet « Noisetier » en cours de développement. Les éléments ci-dessous ne sont pas figés et peuvent être amenés à évoluer au cours du développement du projet.

Nous rappelons que ce projet étant en cours de développement, certaines fonctions n’ont pas encore été codées. Il faut éviter d’installer le Noisetier sur un site en production tant qu’une première version ne sera pas finalisée.

Dans le cadre du projet Noisetier, nous appelons « noisette » un morceau de squelette qui a pour vocation d’être inséré et positionné dans une page du site. Il s’agit donc d’éléments modulaires.

Où ranger les noisettes ?

Les noisettes doivent être placées dans un sous-répertoire noisettes situé soit dans un plugin soit dans le dossier squelettes. Il est préférable de ne pas mettre de noisettes dans un plugin de thème. En effet, même si cela est techniquement possible, la noisette en question ne sera plus accessible dès lors qu’un autre plugin de thème sera activé.

Le noisetier sera livré avec les noisettes correspondant à la distribution livrée par défaut avec SPIP. Le but de ces noisettes sera de reproduire l’ensemble de cette distribution. Cependant, ces noisettes seront codées avec des paramètres permettant ainsi de personnaliser cette distribution par défaut. La valeur par défaut de ces paramètres correspondra au fonctionnement par défaut de la fraichdist.

Afin de partager les noisettes, une bibliothèque de noisettes est prévue. Se présentant sous la forme d’un plugin à activer, elle contiendra entre autres les noisettes de certaines distribution (comme BliP). Cette bibliothèque a pour vocation de s’étendre permettant ainsi de fournir un nombre important de noisettes. Les noisettes de cette bibliothèque devront fonctionner avec un SPIP de base.

Concernant les noisettes nécessitant la présence d’autres plugins (supposons par exemple des noisettes pour le plugin agenda), elles seront placées dans une seconde bibliothèque de noisettes, complémentaire, bibliothèque qui pourra comporter également des pages supplémentaires (comme une page évènement).

L’objectif des bibliothèques de noisettes est de centraliser les contributions des uns et des autres afin de disposer d’un choix important de noisettes. La distinction en deux bibliothèques permet, pour ceux qui utilisent un SPIP de base sans plugin complémentaire, de pouvoir ne pas prendre de la place sur leur serveur avec des noisettes qui leur seraient inutiles.

Convention de nommage des noisettes

ATTENTION : chaque noisette doit avoir un nom unique. Si deux noisettes, bien que situées à deux endroits différents, possèdent le même nom, alors on aura un problème d’interférence.

Techniquement, les noisettes peuvent avoir n’importe quel nom du moment deux noisettes n’ont pas le même nom. Cependant, afin de s’y retrouver, toutes les noisettes nécessitant un id_objet particulier (par exemple un id_article) auront un nom commençant par objet. Sinon le nom commencera par toutes. [1] On décrira ensuite ce que fait la noisette. On pourra faire suivre le nom de la noisette par le nom d’une distribution à laquelle elle se rattache. On utilisera le tiret - entre les trois parties et l’underscore _ au sein de la description de ce que fait la noisette. Par exemple :

  • article-ce_que_fait_la_noisette
  • article-forum_de_l_article-blip
  • article-documents-sarka
  • toutes_accroche_derniers_articles-dist.

En-tête des noisettes

Au début de chaque noisette, il est nécessaire de préciser les variables d’environnement à passer à la noisette, de donner un descriptif à la noisette. On peut également préciser des paramètres qui seront passer en variables d’environnement et éventuellement des mots-clés à installer. Chaque noisette dispose par ailleurs de son propre cache.

L’écriture de ces différents éléments se fera sous une forme à la xml au sein du balise #REM dans la mesure où ils n’ont pas à être affiché dans le squelette final. L’utilisation de cette balise permet par ailleurs de pouvoir réutiliser les noisettes indépendamment du Noisetier. Vous remarquerez ci-dessous qu’entre le crochet ouvrant et la parenthèse ouvrante doit se trouver le mot noisetier afin de distinguer une remarque de description de la noisette d’une remarque servant simplement à commenter le code.

La déclaration de la noisette sera de la forme suivante :

#CACHE[24*3600}
[noisetier(#REM)
<titre>Liste des articles</titre>
<description>
  <multi>
    <lg-fr />Cette noisette permet d'afficher la liste des articles d'une
rubrique. Les articles avec l'attribut en_avant seront mis en valeur.
    <lg-en />This nut allow to....
  </multi>
</description>
<lien>http://url_de_documentation_de_la_noisette.html</lien>
<auteur>fraichdist</auteur>
<version>0.15</version>
<env>id_rubrique</env>
<env>debut_liste_articles</env>
<param>
  <titre>nb_art_par_page</titre>
  <descriptif>Nombre d'articles par page</descriptif>
  <type>num</type>
  <valeur>10</valeur>
</param>
<param>
  <titre>resume-normal</titre>
  <descriptif>Résumé des articles</descriptif>
  <type>modele/article</type>
  <valeur>resume/article-simple</valeur>
</param>
<param>
  <titre>resume-avant</titre>
  <descriptif>Résumé des articles mis en avant</descriptif>
  <type>modele/article</type>
  <valeur>resume/article-complet</valeur>
</param>
<head>
<link rel="stylesheet" type="text/css" href="#CHEMIN{css_pour_cette_noisette.css}" />
</head>
<mot>
  <titre>en_avant</titre>
  <descriptif>Mettre cet article en avant sur la page de la rubrique
qui le contient</descriptif>
  <objet>articles</objet>
</mot>
]

Balise #REM et raccourcis SPIP

Les raccourcis typographiques de SPIP sont acceptés dans les descriptifs. Cependant, les crochets ouvrant [ et fermant ] ne peuvent être utilisés en raison d’un conflit avec la balise #REM englobante.

Pour les champs <multi></multi>, au lieu de [fr], [en] etc., utilisez <lg-fr />, <lg-en />, etc. A l’installation de la noisette, toutes les balises <lg-?? /> seront transformées en <??> pour être réinterprétées correctement par SPIP.

Concernant les liens, utilisez la forme <url>toto->http://www.toto.com/</url> qui sera à l’installation de la noisette transformé en [toto->http://www.toto.com/].

Concernant les notes, elles sont tout simplement interdite car elles compliqueraient l’affichage dans l’interface du noisetier.

Description de la noisette

<titre></titre> : Cette balise est obligatoire et permet de donner un titre à la noisette. Les raccourcis typographiques de SPIP sont possibles sauf quelques exceptions (voir plus haut).

<description></description> : permet de décrire ce que fait la noisette. Les raccourcis typographiques de SPIP sont possibles sauf quelques exceptions (voir plus haut).

<lien></lien> : url de la documentation de cette noisette s’il en existe une.

<auteur></auteur> : auteur(s) de la noisette ou distribution d’origine.

<version></version> : numéro de version de cette noisette, qui sera utilisé lors des mises à jours des noisettes.

Variables d’environnement

Pour fonctionner, une noisette nécessite certaines variables d’environnement. Nous aurions pu passer à l’insertion de chaque noisette l’ensemble des variables d’environnement de la page en cours. Cependant, cela aurait alourdi le cache car chaque noisette n’a pas besoin des mêmes variables d’environnement. C’est pourquoi, afin de ne pas alourdir le cache, on déclarera entre les balises <env></env> les variables d’environnement nécessaires au fonctionnement de cette noisette. Seules ces variables seront transmises à la noisette (d’où allègement du cache). Si la noisette a besoin de plusieurs variables d’environnement, on répètera les balises <env></env> autant de fois que nécessaire.

Paramètres des noisettes

Les paramètres sont des variables, modifiables par le webmaster via l’interface de gestion du noisetier, et transmis à l’inclusion de la noisette sous la forme d’une variable d’environnement. Ainsi, dans le code de la noisette, les paramètres sont accessibles sous la forme #ENV{param}.

Chaque paramètre doit être décrit entre les balises <param></param>. Trois “sous-balises” doivent être renseignées :

  • <titre></titre> : il s’agit du nom technique du paramètre. Il sera passé en tant que variable d’environnement à la noisette.
  • <descriptif><descriptif> : permet de décrire ce que fait le paramètre. Les raccourcis typographiques de SPIP sont possibles (pour les exceptions, voir plus haut).
  • <valeur></valeur> : permet de définir la valeur par défaut du paramètre.

La valeur par défaut du paramètre détermine le type du paramètre :

  • Si cette valeur est un nombre, l’interface du noisetier ne permettra que de la remplacer par un autre nombre.
  • Si cette valeur est oui ou non, alors l’interface du noisetier proposera une case à cocher.
  • Si cette valeur correspond à un modèle (par exemple modeles/article_simple), l’interface du noisetier proposera une liste déroulante avec l’ensemble des modèles présents sur le site du type modeles/article_quelque_chose.
  • Si le nom technique du paramètre commence par pagination, alors on considèrera qu’il s’agit d’un type de pagination (voir http://www.spip.net/fr_article3367.html). L’interface du noisetier proposera alors une liste déroulante avec les différents types de modèles de pagination trouvés. Pour la pagination par défaut, on donnera comme valeur par défaut un champ vide (si on souhaite que la valeur par défaut soit du type précédent et suivant, on entrera precedent_suivant). Par exemple : <param> <titre>pagination_type</titre> <descriptif>Type de la pagination</descriptif> <valeur></valeur> </param>. Dans les boucles de la noisette, la balise #PAGINATION sera alors de la forme #PAGINATION{#ENV{pagination_type}}.
  • Sinon, on considérera qu’il s’agit d’une valeur texte.

Déclarations dans l’en-tête HTML

Certaines noisettes peuvent nécessiter une déclaration spécifique dans l’en-tête HTML de la page où elles sont insérées. Les balises <head></head> permettent de préciser le code à insérer dans l’en-tête des pages où la noisette est inclue.

Cependant, cette piste sera peut-être abandonnée. En effet, des balises #DEBUT_TEXTE_HEAD et #FIN_TEXTE_HEAD sont en cours de test afin intégration éventuelle dans le core. Si elles sont inclues, il sera préférable de les utiliser car plus générique.

Mots-Clés des noisettes

Certaines noisettes peuvent nécessiter des mots-clés techniques pour fonctionner afin d’offrir des fonctionnalités supplémentaires. Les mots-clés nécessaires au fonctionnement de la noisette sont définis à l’aide des balises <mot></mot> qui prend trois “sous-balises” :

  • <titre></titre> : il s’agit du titre du mot clé.
  • <descriptif></descriptif> : il s’agit du descriptif du mot-clé.
  • <objet><objet> : il s’agit du type d’objet sur lequel porte le mot-clé. Correspond aux champs de la table spip_groupes_mots, à savoir articles, rubriques, breves et syndic dans le cas d’une installation par défaut de spip. Il peut s’agir d’une liste d’objets, séparés par des virgules, sans espace.

Plusieurs noisettes peuvent utiliser le même mot-clé. À l’installation de la noisette, le noisetier vérifie si les mots sont déjà présents ou non et au besoin les installe dans des groupes de mots-clés intitulés noisetier-articles, noisetier-rubriques, etc.

À la suppression d’une noisette, il sera possible de supprimer la noisette sans supprimer les mots clés associés ou bien de supprimer la noisette et les mots-clés associés. Dans ce second cas, seuls les mots clés non également utilisés par une autre noisette seront supprimés.

Une page de gestion des mots clés des noisettes permettra de voir les mots-clés présents dans la base mais qui ne sont plus nécessaires au fonctionnement des noisettes actuellement installées et permettra de les supprimer.

Nous attendons par ailleurs de voir si la notion de mots clés techniques sera intégrée ou non dans le core (voir http://zone.spip.org/trac/spip-zone...) Si c’est le cas, les mots-clés des noisettes seront considérés comme des mots clés de type noisetier. Une fonction sera proposée, pour les personnes désirant désinstaller définitivement le Noisetier, de transformer les mots clés du Noisetier en mots clés techniques simples s’ils souhaitent ne pas perdre les informations liées aux mots-clés.

Notes

[1Cela permet de classer facilement les noisettes de manière alphabétique.

Discussion

Aucune discussion

Ajouter un commentaire

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

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

Merci d’avance pour les personnes qui vous aideront !

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

Qui êtes-vous ?
[Se connecter]

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

Ajoutez votre commentaire ici

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

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom