Carnet Wiki

A la découverte des sources.... de SPIP

Version 8 — March 2012 YannX

SPIP est un [logiciel libre->http://fr.wikipedia.org/wiki/Logiciel_libre] SPIP logiciel libre : cela veut dire en particulier que les sources sont ouvertes, modifiables certes, mais déjà à lire !

Pour les core-dev, qui connaissent par coeur tant php que ces sources, c’est du biberon !
Et certains vous assommeront, à grand renfort de RTFM [1]..... sauf que le manuel de Spip ne suit pas toujours.
Ou ils vous prieront d’écrire la doc.... “à partir de quoi ?” vous enteterez-vous ? et “Read The F...Source Code”

Et là, il faut oser : un jour, j’ai pas eu le choix ; alors, je pense à tous ceux qui n’ont pas ( -pas encore- ;) franchi le pas : c’est pas si difficile, et sans danger !

Et j’ai commencé à écrire ce que j’aurais bien aimé pouvoir lire en accompagnement il y a quelque temps....

Comment s’en servir


Avant d’entamer notre voyage initiatique d’étudier la liste ( toujours croissante ) des possibilités , une petite révision s’impose : comme beaucoup de fonctionnalités de SPIP, les codes offerts aux administrateurs/webmestes de SPIP sont directement issus de fonctions php, et c’est souvent la seule façon d’en trouver la documentation : : lire le source.
. _ Pas la peine d’en avoir peur, vous ne pouvez rien casser (tant que vous n’écrivez pas )!

C’est l’avantage d’un produit libre, comme SPIP ou Linux : vous avez accès au source !
Et, meme sans connaitre PHP, vous allez vite en comprendre l’intéret...

Pour lire le source php (du texte dans un langage de programmation..), il suffit de décompresser une archive de SPIP ; point besoin d’outils spéciaux spéciux , éditeurs editeurs de programme ou autres, un explorateur suffit, à moins que vous ne préféreriez lire avec une interface Web : à ce jour, deux sources sont connues, l’incontournable http://doc.spip.org ou la zone librement accessible en lecture, ou bien la presentation améliorée disponible sur http://codes-libres.org
Dans les deux cas vous trouverez aussi bien les sources du core que ceux des plugins : cela peut souvent servir d’exemple !

A première vue, c’est (encore une fois) la zone : plus de 4000 fichiers disséminés dans plus de 500 répertoires ! ?
-  première étape, vous devez connaitre la différence entre fichiers .HTML (présentation des squelettes de pages et formulaires), .CSS pour les feuilles de styles, et les sources .php (qui renferment les programmes composant spip.
-  seconde étape, vous réviserez l’organisation des répertoires privés de la version de Spip que vous étudiez : consultez par exemple programmer.spip, la référence doc.spip.

Les squelettes


Commençons par les squelettes du privé : habitués déjà à l’organisation des squelettes (et peut-etre à la structure Zpip-dist et ses conventions ), vous devriez retrouver assez vite les squelettes d’origine, dans les sous-répertoires de ./squelettes-dist et ceux de ./prive pour l’interface privée : nous ferons juste une référence particulière pour leurs sous-dossiers nommés ./prive/formulaires/ d’où nous pourrons regarder les contenus des-dits formulaires.

Du coté du code source .php, cela se passe essentiellement dans tous les sous-répertoires de ./ecrire, voire aussi dans < ./plugins sans oublier ./extensions.

Comprendre le rangement et la dénomination des fichiers se fera peu-à-peu peut-être, sauf à identifier les tables natives de spip qui sont mises-à-jour....

Maintenant, il faudrait savoir quoi chercher : le sera donné par une recherche de fichiers contenant le mot cherché dans la branche de votre source SPIP.. votre explorateur de fichiers vous donnera vite les réponses.

Essentiellement le l langage de spip s’articule autour :
-  des tables (ou objets ) sur lesquels portent les boucles : pour dépasser les explications du manuel des boucles, PhpMyAdmin est votre ami, en attendant la mise-à-jour de la structure de la base de données.

-  des #BALISES : ces mots-réservés correspondent à des fonctions php qui doivent donc être définies une fois dans un fichier source : vous chercherez la suite de caractères function balise_, en principe plutot en minuscules.

Par exemple, en recherchant function balise_url_page, vous arriverez facilement à lire le fichier ./ecrire/balises/url.php, avec une ligne qui serait :

@@@SPIP_DIFF1@@@
 
 
@@@SPIP_DIFF8@@@Par exemple, en recherchant <code> function balise_url_page

, vous arriverez facilement à lire le fichier

./ecrire/balises/url.php&lt;/code >,  avec  une  ligne  qui  serait  : 
&lt; code  class="php  sans_tele­char­ge­ment ">
 function  balise_URL_PAGE_dist($p )  {
 

Pas très explicite ! Tout ce qu’on peut en dire, c’est que la fonction existe ! Et cela pourrait meme vous paraitre en contradiction avec votre connaissance opérationnelle de la balise...
Heureusement, en regardant quelques lignes autour de celle-ci, vous avez la chance de découvrir des commentaires :

//
// #URL_PAGE{backend} -> backend.php3 ou ?page=backend selon les cas
// Pour les pages qui commencent par "spip_", il faut eventuellement
// aller chercher spip_action.php?action=xxxx
// Sans argument, #URL_PAGE retourne l'URL courante.
// #URL_PAGE* retourne l'URL sans convertir les & en &
// http://doc.spip.org/@balise_URL_PAGE_dist
function balise_URL_PAGE_dist($p) {
 
 
$code = interprete_argument_balise(1,$p);
	$args = interprete_argument_balise(2,$p);
       .....

Ces lignes (conventionnellement affichées en vert-de-gris) précédées de deux slash marquent des commentaires, écrit par un programmeur ..... à destination de ses seuls lecteurs humains : vous .

Si les premières lignes ont plutot valeur historique (le php3 était utilisé au début de SPIP), vous saurez desormais utiliser #URL_PAGE sans argument, et sans surprise (pour ré-afficher la page : mais pour être sur de la recalculer, penser à rajouter un |parametre_url{var_mode,recalcul}

En dessous, nous pourrons découvrir que la balise reçoit d’une part un code (celui de lapage fond à charger) et d’autres arguments... peut-etre accolés par le filtre |parametre_url

Justement, les filtres, que vous connaissez bien : même principe, vous rechercherez la suite de caractères donnant le nom du filtre [2], précédé du mot réservé function :
function xxx(
Cette fois-ci vous avez des chances de récupérer une chaine un peu plus riche.. en arguments !
Il faut savoir que, contrairement a SPIP qui utilise les accolades, php utilise les classiques parenthèses pour entoure la liste de paramètres ; l’accolade ouvrante marque le début du code exécutable...

Prenons par exemple le filtre couper (l’un des premiers que j’ai utilisé : voici sa documentation ):

<blockquote class="spip">

Le filtre |couper coupe un texte après un nombre de caractères paramétrable....
Le filtre coupe par défaut à 50 caractères, mais on peut spécifier une autre longueur en la passant comme paramètre au filtre, par exemple : [(#TEXTE|couper80)].

</blockquote>

Sans surprise, vous trouverez dans le fichier /inc/texte.php :

// http://doc.spip.org/@couper
function couper($texte, $taille=50, $suite = ' (...)') {
	if (!($length=strlen($texte)) OR $taille <= ) return '';  
......

Et vous ferez naturellement la correspondance avec les paramètres :
-  le premier, $taille vient de la chaine qui précédait le filtre [3]
-  le second $taille precise la taille à laquelle tronquer : comme il n’est pas obligatoire, php impose au développeur Spip de préciser une valeur par défaut !
-  quant au troisième, vous reconnaissez les caractères de suite habituels.