ScssPhp

Caractéristiques techniques importantes

Ce plugin demande d’avoir au minimum PHP 5.6.0 !
(il est possible d’utiliser la branche v1 du plugin avec PHP 5.4+, qui utilise la dernière version de la lib compatible avec PHP 5.4)

Dans sa dernière version, tout comme les version libsass ou Ruby, Scssphp, générera une erreur si vos variables ne sont pas initialisées avec !default (ce qui est censé être une « bonne pratique » dans beaucoup de langages).

Ex :

$base-spacing: 1.5rem !default;

Utilisation

La balise CSS : Chargement des styles

Exemple d’inclusion du fichier css/scss_demo.scss dans un squelette SPIP :

[<link rel="stylesheet" href="(#CSS{css/scss_demo.css}|direction_css)" type="text/css" />]

• le fichier/lien doit porter l’extension .css même si c’est un fichier .scss
• si une feuille css et un fichier scss portant le meme nom sont dans le même dossier, c’est la feuille css qui est retournée.
• Une feuille de style insérée via la pipeline insert_head ne sera pas surchargé par un fichier .scss de même nom.
• Comme pour le plugin lesscss, les chemin des images sont relatifs au fichier compilé, pour surcharger un image il faut donc la copier dans le dossier du fichier compilé.

Fichiers importés @import

A la différence de scss/sass, les chemins @import des scss importés doivent êtres définis depuis la racine du squelette ou plugin.

Ainsi pour un fichier theme.scss placé dans le dossier css d’un plugin/squelette, on déclarera :

// identique a la version ruby, les fichier _name.scss situé dans des sous-dossier
// peuvent être appelés sans le _ et l'extension
@import "css/libs/bourbon/core/bourbon";
@import "css/libs/include-media";
@import "css/settings";
// -------------------------------------------
// OUTPUT
// -------------------------------------------
@import "css/libs/sanitize";
@import "css/base/base";

Autre solution, pour simplifier la rédaction des @import déclarer dans paquet.xml le chemin du dossier css/scss

	<!-- Déclaration de notre dossier CSS pour ne pas avoir à préfixer "css/" dans nos @import -->
	<chemin path="./css" type="public" />
	<!--[> Et enfin le dossier du plugin pour SPIP <]-->
	<chemin path="" />

Debugage

Scssphp (depuis la version v0.7.3) permet l’utilisation de sourcemaps, indiquant dans les outils de debug de votre navigateur, le fichiers scss source qui a été appelé lors de la compilation.

Actuellement le plugin produit uniquement des sourcemaps de type inline (inclus dans le fichier compilé, il n’est donc pas recommandé d’activer cette option en la cumulant avec la compression des styles).

L’option est à définir depuis votre fichier option ainsi :

define('_SCSS_SOURCE_MAP', true);

A noter que sur certaines mixins, quand le niveau de récursion/imbriquation est important, le résultat renvoyé sera le fichier de la mixin, et non la ou elle est appelée. par exemple avec include-media

Injection de variables

Le plugin spip scssphp propose deux méthodes pour gérer l’injection de vos variables, ceci est utile quand vous souhaitez pouvoir rendre configurable via un formulaire une partie des styles compilés.

Utilisation d’un squelette spip

Utilisez un fichier mes_variables.scss.html, placé dans votre répertoire squelette. Ceci vous permet d’utiliser toute les boucles ou filtres de spip pour générer vos variables qui seront ensuite utilisés lors de la compilation.

Vous pouvez trouver un exemple d’utilisation de cette technique dans le squelette Html5Up_editorial :
https://zone.spip.org/trac/spip-zone/browser/_squelettes_/html5up_editorial/css/vars_spip.scss.html

Utilisation de la pipeline scss_variables

ScssPhp permet l’injection de variables, directement depuis php, via un array.

http://leafo.github.io/scssphp/docs/#preset-variables

Limitations de cette méthode :

-  les variables dans vos fichiers doivent êtres initalisés avec le flag !default (ce qui est censé être une « bonne pratique »).
-  la valeur de la variable est de type chaine/string et est interprété comme du scss (cf : exemple).
-  le tableau n’est pas multi-dimentionnel : les valeur de type array ne sont pas converties en scss maps, il faut les rédiger comme une chaine (cf : exemple).

Utilisation dans un plugin :

Dans votre paquet.xml :

<necessite nom="scssphp" compatibilite="[1.4.5;[" />
<pipeline nom="scss_variables" inclure="plugin_pipelines.php" />

Dans votre fichier pipeline.php :

function prefixeduplugin_scss_variables($variables){
  $variables = array(
    // ici la valeur est une map
    'header' => '(background:pink,height:2rem,)', 
    // une fonction
    'base-background-body'=>'shade(#b83768,20%)',
  );
  return $variables;
}