Aide-Mémoire SPIP

Les squelettes se trouvent dans /squelettes/. Les squelettes de formulaires se trouvent dans /squelettes/formulaires/. Les squelettes de modèles se trouvent dans /squelettes/modeles/. Un squelette se présente sous la forme d’un fichier HTML. La page d’accueil du site est le squelette sommaire.html. Il est possible d’utiliser des chaînes de langues, en créant un fichier lang_fr.php dans /squelettes/lang/. Une chaîne de langue s’appelle de cette façon : <:chaine_de_langue:>. Le contenu du fichier lang_fr.php est de la même forme que celui de /ecrire/lang/ecrire_fr.php. Pour traduire un squelette créé avec des chaînes de langue, il suffit de traduire lang_fr.php dans lang_xx.php avec xx le code ISO 639-1. La réécriture d’URL fonctionne en éditant le fichier /ecrire/mes_options.php (à créer si absent) et en y ajoutant une ligne : $type_urls = "html"; pour /article123.html, $type_urls = "propres"; pour /Titre-de-l-article, $type_urls = "propres2"; pour /Titre-de-l-article.html et enfin $type_urls = "propres-qs"; pour /?Titre-de-l-article. Vous aurez besoin de renommer le fichier htaccess.txt en .htaccess pour finaliser la réécriture, sauf pour le mode propres-qs qui permet de s’en passer si votre hébergeur ne le supporte pas.

Boucles

À utiliser de la façon :

<B_nomdelaboucle>
Ce texte est affiché si la boucle a au moins un résultat.
     <BOUCLE_nomdelaboucle(TYPE){critère}{critère2}>
     Ce texte sera affiché le nombre de résultats de la boucle.
     </BOUCLE_nomdelaboucle>
Ce texte est affiché si la boucle a eu au moins un résultat.
</B_nomdelaboucle>
Ce texte est affiché si la boucle n'a eu aucun résultat.
<//B_nomdelaboucle>

• ARTICLES, BREVES, RUBRIQUES correspondent aux ressources de base de SPIP.
• AUTEURS permet d’afficher les inscrits au site.
• SYNDICATION permet d’afficher les sites référencés ou leurs derniers articles publiés grâce au RSS.
• FORUMS, SIGNATURES et DOCUMENTS permettent d’afficher respectivement les forums (commentaires), les souscriptions aux pétitions et les documents joints à une ressource.
• HIERARCHIE retourne la liste des rubriques qui permettent d’arriver à la rubrique ou à l’article en cours.

Critères

Ils permettent d’affiner ce que retourne une boucle.

• {a,b} affiche b résultats, du a+1 jusqu’au a+b. {0,10} affiche ainsi les 10 résultats du 1 jusqu’au 10 et {4,4} affiche les 4 résultats du 5 jusqu’au 8. On peut utiliser n dans ce critère, qui représente le nombre total de résultats. Ainsi, {0,n-10} n’affiche pas les 10 derniers résultats de la boucle. {n-20,10} affiche les 10 résultats suivants le 20e à partir de la fin.
• {a/b} affiche une fraction a/b des résultats. Si la boucle a 9 résultats, {1/3} renverra les 3 premiers, {2/3} les 3 suivants et {3/3} les 3 derniers.
• {racine} ne retourne que des rubriques situées à la racine du site.
• {par critère} permet de trier les résultats. Le critère peut-être titre, date, … En ajoutant un ! devant le par, on inverse le tri. {!par date} classera les ressources par date décroissante.
• {id_x} permet d’utiliser les identifiants des ressource pour les classer de différentes manières. {id_article!=2} ne retournera pas l’article 2, {id_rubrique>4} ne retournera que les rubriques dont l’identifiant est supérieur à 4. Pour faire une boucle sur l’article courant ( spip.php?article2 par exemple), {id_article} est indispensable. En doublant le =, une expression régulière peut-être utilisée : {titre!==^[aA]} exclue les articles dont le titre commence par a ou A.
• {age} est l’ancienneté des ressources, en jours. {age>29} retournera tout ce qui a plus de 29 jours. {age_relatif} est le même critère, mais le jour "0" est fixé à la date de l’élément dans lequel il se trouve. Si un article Y est daté du 1 janvier 2007, et que {age_relatif} est utilisé dans une boucle à l’intérieur de celle affichant l’article Y, {age_relatif<30} retournera les articles écrits entre le 2 et le 30 janvier.
• {doublons} permet d’éviter la présence d’une même ressource dans deux boucles différentes. L’article Boomerang sélectionné avec <BOUCLE_articlesrecents(ARTICLES){age<30}{doublons}> ne sera pas présent dans les résultats de <BOUCLE_touslesarticles(ARTICLES){doublons}>.
• {"inter"} sera inséré entre chaque résultat de la boucle. Pour une liste d’articles par exemple, <BOUCLE_listearticle(ARTICLES){", "}>#TITRE</BOUCLE_listearticle> renverra les titres de tous les articles séparés par une virgule et un espace.
• {extension==} permet, dans une boucle DOCUMENTS exclusivement, de sélectionner les extensions désirées. {extension==jpg|png|gif} ne récupèrera que les images.

Balises indispensables

À utiliser de la façon : #BALISE{paramètre,paramètre2} (type 1) ou de la façon : [(#BALISE|filtre1|filtre2)] (équivalent à #BALISE sans filtre) (type 2)

Balises statiques (non-influencées par la ressource)

• #HTTP_HEADER permet de modifier les entêtes HTTP. Par exemple, pour un squelette css.html qui est une feuille de style, on peut utiliser #HTTP_HEADER{Content-type: text/css;} ++type 1++
• #CACHE permet de spécifier la durée du cache. #CACHE{0} sera utilisé pour les pages dynamiques ne devant pas être mises en cache. ++type 1++
• #SELF retourne l’URL de la page courante vidée de tous ses paramètres (pour utilisation dans un formulaire, par exemple).
• #URL_PAGE{page,arguments} crée l’URL de la page répondant au squelette page.html. arguments sert à ajouter des paramètres à l’URL. #URL_PAGE{article_imprimer,id_article_imprimer=#ID_ARTICLE} créera une adresse de la forme spip.php?page=article_imprimer&id_article_imprimer=ID_ARTICLE. ++type 1++
• #ENV{valeur,valeurpardefaut} récupère l’élément valeur d’une requête HTTP (GET dans l’URL, et POST par formulaire). Ainsi, avec l’exemple précédent, pour boucler l’article à imprimer, on pourra faire <BOUCLE_articleaimprimer(ARTICLES){id_article=#ENV{id_article_imprimer,1}}>. Si l’identifiant n’est pas renseigné, alors c’est l’article 1 qui sera sélectionné grace au paramètre valeurpardefaut. ++type mixte++, peut être utilisé sous la forme [(#ENV{valeur}|filtre)].
• #CHEMIN{fichier} sert à trouver l’URL du fichier fichier, qu’il se trouve dans squelettes/, dans les plugins, à la racine, dans dist/ ou dans ecrire/. SPIP cherche le fichier en examinant les répertoires dans l’ordre dans lesquels ils ont été énumérés, et s’arrête dès qu’il a été trouvé. Cette balise est utile pour assurer la portabilité des squelettes (à utiliser pour un lien vers une feuille de style, …).
• #FORMULAIRE_X appelle le squelette formulaires/formulaire_x.html. Sont disponibles #FORMULAIRE_INSCRIPTION, #FORMULAIRE_OUBLI, #FORMULAIRE_SIGNATURE (qui affiche le formulaire de signature de pétition), #FORMULAIRE_SITE (qui affiche un formulaire de soumission de site à référencer dans l’annuaire), #FORMULAIRE_ECRIRE_AUTEUR (qui affiche le formulaire de contact). Deux autres balises peuvent prendre un paramètre : l’adresse de la page affichée après validation du formulaire. Ce sont #FORMULAIRE_FORUM (qui affiche le formulaire pour commenter une ressource) et #FORMULAIRE_RECHERCHE.
• #LOGIN_PRIVE appelle le squelette formulaires/formulaire_login.html qui permet de se connecter à l’espace privé. ++type 2, aucun filtre++
• #LOGIN_PUBLIC{#URL_PAGE{connecte}} affiche le formulaire qui permet de se connecter tout en restant sur le site public, pour par exemple participer à des forums modérés. Sans paramètre, il redirige vers la page actuelle, avec #URL_PAGE{connecte} en paramètre, il redirige vers la page spip.php?page=connecte. Vous pouvez aussi indiquer directement l’URL, mais pour un souci de pérennité des adresses, il vaut mieux choisir la solution #URL_PAGE. ++type 1++
• #INCLURE{fond=page} permet d’insérer le squelette "page.html". Ce dernier n’est pas recalculé à chaque recalcul du squelette dans lequel il est inséré, à la différence d’<INCLURE>. ++type 1++
• #NOM_SITE_SPIP et #DESCRIPTIF_SITE_SPIP affichent les informations de base sur votre site. ++type 2++

Balises contextuelles

• #COMPTEUR_BOUCLE et #TOTAL_BOUCLE affichent respectivement le numéro du résultat de la boucle et le nombre total de résultats de la boucle (égal au dernier #COMPTEUR_BOUCLE).
• #DATE permet d’afficher la date de l’article, de la brève, ou de l’élément le plus récent d’une rubrique. À utiliser avec le filtre |affdate qui permet de l’afficher sous la forme "3 novembre 2006". ++type 2++
• #URL_X permet d’afficher l’URL d’une ressource. Ainsi, #URL_ARTICLE retourne l’adresse de l’article, etc. ++type 2++
• #LOGO_X permet d’afficher le logo d’une ressource. Ainsi, #LOGO_ARTICLE retourne le logo de l’article, etc. #LOGO_SITE_SPIP retourne le logo du site. ++type 2++
• #TEXTE, #DESCRIPTIF, #PS, #CHAPO, #NOTEScorrespondent aux champs respectifs des articles/brèves/rubriques. ++type 2++
• #LESAUTEURS affiche la liste du ou des auteur(s) de l’article. ++type 2++
• #DEBUT_SURLIGNE et #FIN_SURLIGNE sont utilisés sur une page retournée par la recherche. Ils permettent de délimiter une zone dans laquelle une classe "spip_surligne" sera appliquée aux mots demandés trouvés. ++type 2, aucun filtre++
• #FICHIER, dans une boucle DOCUMENTS, permet d’afficher le nom du fichier. Peut-être utilisé avec image_reduire s’il s’agit d’une image.

Filtres essentiels

Les filtres sont très nombreux, en voici les plus importants. Ils s’appliquent à une balise de type 2 de la façon suivante : [(#BALISE|filtre{paramètre,paramètre2})]. Les paramètres ne sont pas toujours indispensables selon les filtres.

• supprimer_numero permet d’enlever le numéro d’une ressource dont le titre est de la forme "2. Article". Le numéro peut-être utilisé pour faire un tri sans être affiché dans la partie publique. En ajoutant la ligne $table_des_traitements['TITRE'][]= 'supprimer_numero(typo(%s))'; au fichier /ecrire/mes_options.php, le filtre est automatiquement appliqué à toutes les balises #TITRE.
• extraire_attribut{‘attribut’} permet d’utiliser l’attribut d’un élément HTML directement généré par SPIP. [(#LOGO_ARTICLE|image_reduire{60,80})] retourne un code du type <img … />, [(#LOGO_ARTICLE|image_reduire{60,80}|extraire_attribut{'src'})] retourne simplement l’adresse que SPIP aurait inséré dans l’attribut src de la balise <img>
• inserer_attribut{‘attribut’,’valeur’}, à l’inverse, permet d’ajouter un attribut non présent dans du code HTML directement généré par SPIP. [(#LOGO_ARTICLE|inserer_attribut{'alt',#TITRE)] rajoute un attribut alt contenant le titre de l’article au logo.
• abs_url s’applique à une URL ou à un texte susceptible d’en contenir, et transforme tous les liens en liens absolus.
• textebrut enlève toutes les balises HTML d’un texte et supprime les espaces insécables.
• texte_backend transforme un texte pour qu’il puisse être utilisé dans un fichier XML.
• couper{taille} et lignes_longues{taille} permettent respectivement de couper un texte à taille caractères donnés, sans couper brusquement les mots, et de couper les mots faisant plus de taille caractères, pour éviter les problèmes de dépassement de cadres.

Filtres de test

• sinon{‘sivide’}, choixsivide{‘sivide’,’sinonvide’} et choixsiegal{‘egalaquoi’,’siegal’,’sinon’} permettent d’effectuer des tests conditionnels simples. [#TOTAL_BOUCLE (#TOTAL_BOUCLE|choixsiegal{1,'article','articles'})] retournera le nombre de résultats suivi d‘article au singulier s’il y en a un seul, et au pluriel sinon. Cet exemple ne prend pas en compte le 0. [(#CHAPO|sinon{#DESCRIPTIF})] permet d’afficher le descriptif de l’article si le chapô n’est pas présent. choixsivide est une variante de sinon (l’argument sinonvide est facultatif), on devrait écrire pour le même résultat : [#CHAPO|choixsivide{#DESCRIPTIF,#CHAPO})].
• Il est possible de tester une balise avec une valeur et d’afficher quelque chose en fonction du résultat. [(#TITRE|=={'Édito'}|?{'id="edito"','id="articleclassique"'})] teste si le titre de l’article est "Édito". Si c’est le cas, un id="edito" est inséré, sinon, c’est un id="articleclassique". Les différents tests sont |== (égalité), |!= (inégalité), et pour les chiffres |> (infériorité stricte), |>= (infériorité), |< (supériorité stricte), |<= (supériorité).
• Plus avancé, on peut inclure un squelette si un paramètre a été passé. @@(#ENV{affichage}@@ inclue le squelette inc-liste-breves.html si le paramètre affichage est à breves.

Filtres d’images

• image_typo{police=police.ttf, taille=12, couleur=000000, largeur=350, align=center, padding=25} transforme un texte en image, en utilisant la police police.ttf (à placer dans le répertoire /ecrire/polices/), de taille 12 points, de couleur noire (la couleur s’indique en hexadécimal sans le dièse #), de largeur maximale 350 pixels (au-delà, le texte subira un retour à la ligne), centré sur l’image, avec 25 pixels d’espacement avec les bords de l’image (si jamais la police est mal configurée et dépasse du cadre). Chaque argument est optionnel.
• image_reduire{largeur,hauteur} permet de réduire une image directement si appliqué à une balise comme #LOGO_ARTICLE ou de réduire toutes les images contenues dans un texte comme #DESCRIPTIF. En l’absence de largeur ou de hauteur, l’image est redimensionnée à la taille du paramètre indiqué en conservant l’échelle.
• image_nb et image_sepia désaturent l’image, le second lui ajoute une teinte sépia.
• image_gamma{intensite} éclaircit ou assombrit l’image. intensite est compris entre -254 et 254, 254 rendra l’image blanche et -254 noire.
• image_rotation{angle} fait pivoter l’image d‘angle degrés.

Merci à mortimer, cent20 et à alexandra pour leur relecture attentive !

Historique

• version 0.2 : corrections par Fil et amélioration de la lisibilité
• version 0.1

Réactions

Ajoutez la votre