Thèmes - SPIPr

Des thèmes prêts à l’emploi

Grâce à sa structure, SPIPr est utilisable directement avec une galerie de thèmes interchangeables.

L’écriture de nouveaux thèmes pour SPIPr se fonde sur les conventions de BootStrap, enrichies de LayoutGala et du système de résumés et listes d’objets.

Les thèmes qui respectent ces conventions pourront être utilisés indifféremment avec les différents squelettes SPIPr.

Menu de navigation principale

SPIPr permet de gérer votre navigation principale directement dans l’espace privé à l’aide du plugin Menus. Il suffit de créer un menu avec l’identifiant barrenav pour qu’il soit automatiquement inséré à la place de la navigation principale, sans modifications de fichiers.

Compositions

SPIPr est naturellement conçu pour fonctionner avec le plugin Compositions qui permet d’utiliser plusieurs types de composition par objet, et de décliner les cœurs de page en fonction des besoins.

Ecrire un thème

Les squelettes SPIPr reposent sur plusieurs conventions de balisage :

toutes les conventions de balisage HTML de BootStrap (voir notamment http://twitter.github.com/bootstrap/base-css.html et http://twitter.github.com/bootstrap/components.html)
la convention de balisage des formulaires de SPIP
la convention de balisage pour le contenu des pages
la convention de balisage des Résumés et listes d’objet

Ces conventions ainsi que la possibilité de fixer le Layout de la page indépendamment du squelette permettent l’écriture de thèmes unifiés utilisables par tous les squelettes de la famille SPIPr

Organisation des fichiers

Le thème est constitué d’un répertoire, contenant un fichier plugin.xml et un dossier css/ pour les feuilles de style.

Les feuilles de style

Le thème peut inclure dans son dossier css/ n’importe quelle feuille de style du plugin BootStrap personalisée.
Dans la plupart des cas, le thème se limitera à proposer l’une ou l’autre de ces feuilles :

css/variables.less qui permet de personnaliser toutes les couleurs et polices de caractère
css/boot-theme.less qui permet d’ajouter des styles à ceux de BootStrap pour le personaliser (cette feuille est compilée avec celles de BootStrap et peut donc utiliser les mixins de BootStrap)
css/theme.less pour ajouter des styles indépendamment de BootStrap (cette feuille est plus indiquée pour l’ajout de styles avec des images de décoration)
css/layouts.less pour définir le positionnement des blocs dans la page en fonction des tailles d’écran

Le thème peut aussi proposer une feuille css/font.less ou css/print.css dédiée au chargement des directives font-face
Le thème peut éventuellement proposer une feuille css/print.less ou css/print.css pour les variantes de style à l’impression, mais il est préférable de les intégrer directement dans les autres feuilles avec une directive @media print { }.

Ajouter des composant au `<head>`

Si le thème nécessite l’ajout de composants dynamiques dans le head , il peut fournir au choix :

inc-theme-head.html qui sera inclus à la suite de theme.less, et reçoit les variables d’environnement (bien indiqué pour une CSS dynamique)
inc-insert-head-css.html qui sera ajoutée à la fin de la balise #INSERT_HEAD_CSS, mais ne reçoit pas les variables d’environnement. Cette inclusion est plutôt indiquée pour ajouter des feuilles de style de base
inc-insert-head.html qui sera ajoutée à la fin de la balise #INSERT_HEAD, mais ne reçoit pas les variables d’environnement. Cette inclusion est plutôt indiquée pour les scripts qui utilisent jQuery ou pour ajouter un composant javascript de BootStrap

Les images de décoration

Toutes les images de décoration référencées par les feuilles de style du thème seront rangées dans le sous dossier css/img/ du thème.

Logo

Le thème doit contenir une image, au premier niveau, utilisée pour représenter le thème dans l’interface de sélection. Elle sera de préférence dans un format 200px x 150px, ou plus grand et proportionnel.

Layout

Le thème doit fournir un layout, ou structure HTML de la page. Il comprend toute la structure du HTML du <body>...</body>.

Ce layout doit inclure les 6 blocs fonctionnels génériques au moyen des lignes suivantes :

<INCLURE{fond=header/#ENV{type-page},env} /> pour le bloc fonctionnel qui constitue l’en-tête visuelle du site ;
<INCLURE{fond=inclure/nav,env} /> pour la navigation principale du site, qui ne dépend pas du type de page ;
<INCLURE{fond=content/#ENV{type-page},env} /> pour le bloc principal de contenu ;
<INCLURE{fond=aside/#ENV{type-page},env} /> pour le bloc de contenu secondaire en relation avec le contenu principal ;
<INCLURE{fond=extra/#ENV{type-page},env} /> pour le bloc d’informations complémentaires de la page ;
<INCLURE{fond=footer/#ENV{type-page},env} /> pour le pied de la page.

Ce layout peut inclure un 7^e bloc qu’il fournira lui même, nommé inc-theme-copyleft.html sous la forme <INCLURE{fond=inc-theme-copyleft,env} />. Ce bloc permet d’afficher les éventuelles informations de droits d’auteur et de crédits, y compris éventuellement un lien vers le site de l’auteur. Ce bloc ne doit pas être utilisé pour embarquer d’autres informations.

Ce layout sera renseigné dans le fichier body.html.
Ce fichier ne doit contenir que des éléments de structure de la page, et ne doit intégrer aucun contenu, sauf à entrainer une incompatibilité avec des squelettes.

`plugin.xml`

Le thème doit inclure un fichier de description plugin.xml. Ce fichier de description permet de renseigner les informations visibles dans le sélecteur de thème de l’espace privé.

Il permet aussi d’installer directement le thème dans le dossier plugins/ et de l’activer depuis le gestionnaire de plugins dans le cas où le webmestre ne veut pas mettre de galerie de thèmes à disposition des administrateurs.

Le fichier plugin.xml doit comporter au minimum les informations ci-dessous :

<plugin>
	<nom>Nom du thème</nom>
	<auteur>auteur, crédits</auteur>
	<licence>type de licence, lien vers la licence</licence>
	<version>1.0</version>
 	<description>description plus longue du thème</description>
 	<icon>vignette.jpg</icon>
 	<etat>stable</etat>
 	<prefix>theme_nomdutheme</prefix>
	<utilise id="spipr" version="[;]" />
	<categorie>theme</categorie>
</plugin>

Par convention, la balise <prefix> commencera toujours la valeur theme_.

Variantes de thèmes

Lorsqu’un thème visuel comporte plusieurs variantes possibles, il est vivement conseillé de créer un thème indépendant pour chaque variante importante.

L’utilisation de panneau de configuration pour personnaliser les thèmes est tout à fait déconseillée car peu compréhensible par les débutants. L’expérience de l’utilisateur doit être privilégiée par rapport à la facilité pour le développeur.

Pratiquement, il est conseillé de faire un dossier thème portant le nom de la famille de thème, qui comportera un sous dossier pour chaque thème activable. Chacun de ces thèmes sera indépendant et comportera son fichier de déclaration plugin.xml.

Les variantes mineures pourront faire l’objet d’un fichier texte dans le thème qui explique quoi changer pour personaliser un peu le thème.

Un thème n’est pas un squelette

Il est important de comprendre avant toute chose qu’un thème doit se limiter à la décoration visuelle, à l’habillage graphique.

Un thème ne peut pas et ne doit pas se mêler de quel type d’information est affiché, de comment les informations sont sélectionnées etc ... Autrement dit :

un thème ne doit pas surcharger des éléments du squelette autre que ceux explicitement définis dans cette documentation.
un thème ne doit pas fournir de contenu autre que celui spécifié ci-dessous.

Écrire un thème qui ne suivrait pas cette règle le limiterait à fonctionner avec un squelette donné, ou dans un cas donné, alors que le but est ici de proposer une méthode qui permette d’écrire des thèmes interchangeables avec plusieurs squelettes.

Un thème n’est pas un plugin

L’utilisation de scripts php dans un thème est fortement déconseillée. Pour des raisons de sécurité, et pour permettre le téléchargement et l’installation automatisée, un thème ne doit pas contenir de scripts PHP, ni de code PHP inline dans l’un des squelettes fournis par le thème.

Pour les mêmes raisons, les mécanismes génériques des plugins éventuellement spécifiés dans plugin.xml (tels que l’utilisation des pipelines) resteront inactifs lorsque un thème sera sélectionné par le gestionnaire de thèmes.

Un thème pas à pas

Créer le répertoire

Pour commencer un nouveau thème, créer d’abord un sous-dossier themes/ dans le dossier squelettes/.
Dans ce dossier squelettes/themes/ créer un dossier mon-theme/ avec l’arborescence ci-dessous :

 squelettes/
 	 themes/
 	 	 {{mon-theme/}}
 	 	 	 {{plugin.xml}}
 	 	 	 {{css/}}
 	 	 	 	 {{img/}}

`plugin.xml`

Dans le dossier mon-theme/ ajouter le fichier plugin.xml contenant :

<plugin>
	<nom>Mon premier th&egrave;me</nom>
	<auteur>Polatouche</auteur>
	<licence>GPL</licence>
	<version>1.0</version>
 	<description>Un th&egraveme pas a pas</description>
 	<icon>vignette.jpg</icon>
 	<etat>stable</etat>
 	<prefix>theme_pasapas</prefix>
	<utilise id="spipr" version="[;]" />
	<categorie>theme</categorie>
</plugin>

Créer aussi un fichier vignette.jpg qui peut être une image blanche pour le moment, mais qui est nécessaire.

Layout

Créer le fichier qui body.html qui pose le layout. Ici on choisit d’utiliser LayoutGala :

<body>
  <div class="page">
    <div class="container header" id="header">
      <INCLURE{fond=header/#ENV{type-page},env} />
    </div>
    [<nav class="navbar navbar-inverse" id="nav">
      (#INCLURE{fond=inclure/nav,env})
    </nav>]
    <div class="container">
      <div class="wrapper">
        <div class="content primary span8" id="content">
          <INCLURE{fond=breadcrumb/#ENV{type-page},env} />
          <INCLURE{fond=content/#ENV{type-page},env} />
        </div>
      </div>
      <div class="aside secondary span3" id="aside">
        <INCLURE{fond=aside/#ENV{type-page},env} />
      </div>
      <div class="extra secondary span3" id="extra">
        <INCLURE{fond=extra/#ENV{type-page},env} />
      </div>
    </div>
    <div class="footer container" id="footer">
      <INCLURE{fond=footer/#ENV{type-page},env} />
    </div>
  </div>
</body>

Pour la présentation, on va utiliser 3 layouts différents :

en grand ecran le Layout Gala 9 en 3 colonnes ;
en écran intermédiaire, le Layout Gala 33 en 2 colonnes, mais en faisant varier la grille autour de 979px ;
en moins de 768px, le Layout Gala 27 avec contenu en pleine largeur et 2 colonnes en dessous ;
en dessous de 450px, les 2 colonnes passent l’une en dessous de l’autre
C’est un layout complet et robuste et complet qui constitue un bon point de départ personalisable.

Créer le fichier css/layouts.less pour y définir ce mode de fonctionnement :

@import "bootstrap/css/layouts.less";
@import "css/layoutgala/9";
@import "css/layoutgala/33";
@import "css/layoutgala/27";

#layoutgala33 > .core(8,4,4,@gridColumnWidth,@gridGutterWidth);
#content > .inner {padding-right: @gridColumnWidth/2;}

@media (min-width: 1200px) {
  #layoutgala9 > .core(6,3,3,@gridColumnWidth1200,@gridGutterWidth1200);
  #content > .inner {padding-right: @gridColumnWidth1200/2;}
}
@media (min-width: 768px) and (max-width: 979px) {
  #layoutgala33 > .core(8,4,4,@gridColumnWidth768,@gridGutterWidth768);
  #content > .inner {padding-right: 0;}
}
@media (max-width: 767px) {
  #layoutgala27 > .core(auto,48%,48%,@gridColumnWidth768,@gridGutterWidth768);
  #content > .inner {padding-right: 0;}
}

@media (max-width: 450px) {
  div#aside {float:none;width:100%;}
  div#extra {float:none;width:100%;}
}

Prévisualiser

A ce stade, il est déjà possible de prévisualiser le thème. Pour cela aller dans le menu Squelettes > Thèmes de l’espace privé. Le thème « Mon premier thème » doit apparaitre dans la galerie des thèmes disponibles. Cliquez sur « Apercevoir » pour prévisualiser le thème.
Vous pouvez naviguer dans le site public en conservant l’affichage en mode aperçu avec ce thème. Seul vous le voyez, vos visiteurs continuent à voir le site avec le thème actif.
Dès que vous retournez dans l’espace privé le mode aperçu et désactivé et vous pouvez revoir le site avec son thème actif.

A tout moment de vos modifications vous pouvez passer en mode aperçu pour voir l’apparence de votre thème. Si vous avez modifié une feuille de BootStrap il faut probablement forcer la recompilation de la feuille CSS de BootStrap, ce que vous pouvez faire en ajoutant &var_mode=recalcul dans l’url de la page.

Couleurs et Polices de caractères

Pour donner une touche personnelle au thème, il suffit de copier le fichier bootstrap2spip/css/variables.less du plugin BootStrap (ou téléchargez le fichier variables.less depuis SPIP-Zone).
Poser le fichier variables.less dans le dossier mon-theme/css/.

Ce fichier contient toutes les variables de définition utilisées dans les feuilles de style de BootStrap.
Y modifier les couleurs, les polices de caractère, les tailles... permet déjà, sans aucune autre modification complexe, de personnaliser l’apparence de votre site de façon unifiée (les modifications seront prises en compte dans tout le site, pour tous les éléments de la page concernés etc...).
Vous pouvez utiliser un des outils en ligne pour modifier ce fichier.

Plus de personnalisation

Dans un second temps, vous pouvez modifier les apparences de BootStrap en ajoutant un fichier css/boot-theme.less dans votre thème. Certains des outils en ligne de personnalisation de BootStrap vous génèrent un fichier tout prêt qu’il suffit de renommer.

Vous pouvez également personnaliser les feuilles complémentaires pour SPIP existantes dans le plugin BootStrap pour SPIP :

css/spip.css vous permet de modifier les quelques styles spécifiques à SPIP
css/spip.list.less vous permet de modifier l’apparence des résumés et listes d’objets
css/spip.comment.less vous permet de modifier l’apparence des forums et commentaires de SPIP

Enfin, indépendamment de BootStrap et des feuilles existantes, vous pouvez ajouter votre feuille de style css/theme.less ou css/theme.css si vous êtes plus à l’aise avec CSS, et y mettre toutes vos personnalisation.