Initiation aux squelettes SPIP

Damien Raude-Morvan - <drazzib@drazzib.com>

Organisation des squelettes de SPIP

Les fichiers squelettes sont présent dans le dossier : /dist/ Chaque fichier .html représente un gabari pour une « vue » de SPIP. On y trouve :

sommaire.html : fichier utilisé pour la page d'accueil de votre site
rubrique.html : affichage d'une rubrique de votre site
article.html : affichage d'un article seul
breve.html : affichage d'une breve seule
forum.html : affichage du forum de discussion attaché à un article

Utiliser ses propres squelettes

ou « /dist/, c'est bien, mais y a mieux »

Par défaut, SPIP va chercher un répertoire /squelettes/
Si on souhaite utiliser un autre répertoire, il faut créer un fichier /config/mes_options.php :
```
<?php
$dossier_squelettes = 'squelettes/monsquelette';
?>
```
On peut indiquer plusieurs répertoires, séparés par le caractère « : » :
```
<?php
$dossier_squelettes = 'squelettes/essai:squelettes/monsquelette';
?>
```
Utilisation du Switcher : permet de passer d'un squelette à un autre via une liste déroulante dans le site public

Priorité des dossiers de squelettes

liste de dossiers désignés dans variable $dossier_squelettes, si celle-ci est définie
ensuite dans le dossier squelettes/ situé à a racine du site
liste de dossiers de la variable $plugins
racine du site
répertoire dist/
répertoire ecrire/

On peut copier uniquement certains fichiers de /dist/ dans notre /squelettes/ : SPIP saura retomber sur ces pattes

Exemple de squelette

Squelette simple qui permet d'afficher un article :

<html>
<body>
<BOUCLE_un_article(ARTICLES){id_article}>
  <h1>#TITRE</h1>
  <b>#CHAPO</b>
  <div align="justify">#TEXTE</div>
</BOUCLE_un_article></body>
</html>

Dans la boucle ci-dessus le parametre id_article provient de l'URL

spip.php?page=article&id_article=8

Fabrication d'une page par SPIP

Identification de la « vue » demandée : http://monspip/spip.php?page=article&id_article=1
Chargement du squelette associé : article.html
Passage de la valeur du paramètre id_article au squelette
Declenchement par le squelette des accès en base de données : ARTICLE=1
Remplacement des fragments dynamiques du squelette par les valeurs lues en base de données : #TITRE, #INTRODUCTION, #TEXTE
Enregistrement de la page générée dans le cache SPIP : /tmp/cache/A/dfksdf.html
Envoi de la page au navigateur web.

La notion de boucle de SPIP

La notion de base du langage de SPIP est donc la boucle.

SPIP s'appuie sur une base de données pour stocker les articles, les rubriques - bref tout votre site

SPIP doit extraire des listes d'éléments (Articles, Rubriques) pour les afficher sur le site. C'est ici qu'intervient la boucle qui permet de :

extraire un seul élément d’une liste
exemple : afficher l’article désiré
extraire plusieurs éléments d’une liste
exemple : dans la page d’une rubrique, on veut afficher tous les articles contenus dans cette rubrique
gérer l’éventualité de l’absence de ces éléments
exemple : le squelette de l’affichage des rubriques demande l’affichage de toutes les sous-rubriques contenues dans une rubrique

Structure d'une boucle

BOUCLE : OBJET « liste des articles » + CRITERE « de cette rubrique »

BALISE : afficher ici le titre de l'article

BALISE : afficher la date + FILTRE « uniquement le mois et l'année »

BALISE : afficher le sous-titre

BALISE : afficher le texte de l'article

Fin de la BOUCLE

Le système de boucle permet, dans un code unique : - d’indiquer à quel endroit du code HTML on a besoin de quel type d’élément (à tel endroit on veut récupérer la liste des articles, à tel endroit on veut inclure la liste des sous-rubriques...) - de prévoir l’affichage d’un élément unique - d’indiquer comment est affichée une liste de plusieurs éléments - de déterminer ce qu’on affiche lorsqu’il n’y a aucun élément correspondant.

Sélectionner ou trier les données : criteres

Certains critères s'appliquent à toutes les boucles. Ils permettent :

Classer les résultats
Afficher les données en fonction de la date
Affichage d’une partie des résultats (pagination par exemple)

Affichage d’une partie des résultats

{doublons} : permet d’interdire l’affichage des résultats déjà affichés dans d’autres boucles utilisant ce critère
{exclus} : permet d’exclure du résultat l’élément (article, brève, rubrique, etc.) dans lequel on se trouve déjà
{a,b} : où a et b sont des chiffres. Ce critère permet de limiter le nombre de résultats. a indique le résultat à partir duquel on commence l’affichage (attention, le premier résultat est numéroté 0 - zéro) ; b indique le nombre de résultats affichés.

Afficher les données par rapport à une date

Exemples :

{age<30} : éléments publiés depuis moins d'un mois
{annee<=2006} : permet d'afficher uniquement les données de l'année 2006

{age_relatif} : Articles de la même rubrique publiés à la même date que l'article principal :

<BOUCLE_principal(ARTICLES){id_article}>
        <BOUCLE_suivant(ARTICLES){id_rubrique}{age_relatif<=0}
        {exclus}{par date}>
        </BOUCLE_suivant>
</BOUCLE_principal>

Classer les résultats

Classement des elements par un critère au choix :

{par critère_de_classement}

Exemples :

{par date} : classe les élements par ordre chronologique
{par date}{inverse} : on commence la liste avec les articles les plus récents
{par hasard} : permet de classer les éléments de façon aléatoire

Afficher les données sélectionnées : les balises

Avec les boucles on récupère un ou plusieurs éléments (article, rubrique, brève...)
Avec les balises on affiche les données contenues dans ces éléments (titre de l'article, texte de l'article...). Une balise SPIP se place donc à l’intérieur d’une boucle

Utilisation des balises

Insérer une valeur (et ce qui l'entoure) uniquement si cette valeur n'est pas vide :
```
[ texte optionnel avant (#BALISE) texte optionnel après ]
```
Distinguer le même type de données (titre d'une rubrique et titre d'un article) dans des boucles imbriquées :
```
#_boucle:BALISE
```

Balises génériques

Certaines balises sont utilisables dans l'ensemble du site, et ne sont pas liées à un contexte particulier.

#URL_SITE_SPIP
#LOGO_SITE_SPIP
#DOSSIER_SQUELETTE (notamment pour les chemins vers les images)
```
src="#DOSSIER_SQUELETTE/image1.png"
```
#FORMULAIRE_RECHERCHE Affichage du formulaire de rechercher
#LOGIN_PUBLIC Affichage du formulaire de connexion qui redirige vers le site public (utile notamment pour le plugin Acces Restreint)

Balises spécifiques aux articles

#TITRE
#SOUSTITRE
#LESAUTEURS
#TEXTE
#URL_ARTICLE

<BOUCLE_une(ARTICLES)>
    <h4><a href="#URL_ARTICLE">#TITRE</a></h4>
</BOUCLE_une>

Transformer les données : filtres de SPIP

Les filtres permettent d'effectuer un ou des traitements sur les balises

[ texte... (#BALISE|filtre1|...|filtren) texte... ]

Les filtres 1, 2 jusque n sont appliqués successivement à la suite les un des autres.

Filtres sur le texte

couper{n} coupe le texte de la balise au nombre de lettre n
lignes_longues{n} coupe les mots trops longs pour les faire passer à la ligne (ou n est la longueur de la ligne)
textebrut permet d'obtenir le texte brute sans balise HTML
majuscule tranformation du texte en lettres majuscules.

Filtres sur les dates

affdate affiche la date sous forme de texte

<BOUCLE_blog2(ARTICLES){par date}{inverse}>
  [<hr/><h1>(#DATE|annee|unique)</h1>]
[<h2>(#DATE|affdate{'Y-m'}|unique|nom_mois)</h2>]  <a href="#URL_ARTICLE">#TITRE</a><br/>
</BOUCLE_blog2>

affdate_mois_annee affiche le mois et l'année : « Avril 2006 »...
affdate_jourcourt affiche le format de date court : « 19 Mars » dans l'année courante ou « 1 Décembre 2006 » dans les années précédentes
nom_jour affiche le jour courant : « lundi », « mardi »
saison affiche la saison : « été », « hiver »

Filtres sur les images

image_reduire permet de réduire la taille des images (calcul effectué sur le serveur et mis en cache)
```
[(#TEXTE|image_reduire{600,0})]
```
reduit toutes les images contenues dans le corps de l'article à une largeur maximale de 600 pixels (et de conserver ainsi une mise en page propre)
image_recadre{largeur,hauteur,position} permet de recadrer une image
```
[(#FICHIER|image_recadre{90,90,center})]
```
recadre l’image originale en un carré de 90 px de largeur et hauteur ne gardant en se basant sur le centre de l’image
image_sepia transforme une image en tons sepia

Créer ses propres filtres

Dans $dossier_squelette/mes_fonctions.php :

<?php
function mon_filtre($texte){
   $texte = (bidouillages en PHP) ...;
   return $texte;
}
?>

Dans $dossier_squelette/article.html

[(#TEXTE|mon_filtre)]

CSS de SPIP

Les styles CSS de SPIP sont organisés en plusieurs fichiers :

spip_style.css : styles associés au code généré par SPIP. Indispensables au bon fonctionnement de SPIP
spip_admin.css : styles associés à la partie privée de SPIP
impression.css : styles utilisés lorsque le navigateur demande une impression
habillage.css : styles liés aux squelettes que vous utilisez

SPIP et le multilinguisme

Trois niveau de configuration disponibles :

par secteur : à chaque secteur du site correspond une langue modifiable par les administrateurs, qui concerne toutes ses sous-rubriques ainsi que les articles et les brèves qui y sont publiés
par rubrique : on peut changer la langue pour chacune des rubriques du site, pas seulement celles de premier niveau
par article : la langue peut être modifiée au niveau de chaque article ; ce choix est compatible avec les précédents

Obtenir les traductions d'un article

Il faut utiliser le critère {traduction} afin d'afficher les traductions de l'article courant :

...BOUCLE principale...
<BOUCLE_autres_traduction(ARTICLES){traduction}{exclus}>
[<a href="#URL_ARTICLE" rel="alternate" hreflang="#LANG">(#LANG|traduire_nom_langue)</a>]
</BOUCLE_traductions>
.../BOUCLE principale...

Traduire des libellés

Il faut créer un fichier $dossier_squelettes/local_[code].php (ex: local_fr.php) :

<?php
$GLOBALS[$GLOBALS['idx_lang']] = array(
  'bonjour' => 'Bonjour'
);
?>

Dans le squelette, on peut ensuite utiliser le code :

<:bonjour:>

Les modeles SPIP

Modèles de SPIP : fragments de squelettes réutilisables. Ils sont présents dans le dossier : /dist/modeles/

uniquement des fragments = non utilisables seuls
réutilisable dans n'importe quel autre squelette « complet ». Inclusion d'un modele dans un squelette :
```
<modele10
  |param1=valeur1
  |param2=valeur2
 >
```
Exemples bien connus : <img1>, <doc1>

Initiation aux squelettes SPIP, le 17 Janvier 2008