Installer et utiliser Scampi-Twig

Scampi-Twig est un outil de création de pages statiques ou de gabarits d’intégration html/css/js utilisant la bibliothèque de composants Scam pour les CSS et Twig pour la génération des pages html.

Il autorise la saisie des contenus par inclusion de fragments, en saisie twig/html directe ou par inclusion de fichiers markdown.

Pour l’utiliser, télécharger ou forker son dépôt et lire la présente page.

Ajouter le submodule Scampi

En principe une fois le repo cloné on devrait pouvoir simplement taper la commande suivante pour rapatrier le submodule :

$ git submodule init

Sinon, se placer dans le répertoire dev/styles/scss, puis lancer la commande :

$ git submodule add git@gitlab.com:pidila/scampi.git dev/styles/scss/scampi

Il est vivement recommandé de ne pas modifier les fichiers inclus dans ce submodule, les modifs ne seraient appliquées qu’en local et cela compromettrait la possibilité de le mettre à jour.

Si on souhaite apporter ou une amélioration au submodule Scampi, on le fait depuis son dépôt.

Personnaliser le déploiement des modules node

Dans le fichier package.json, ajuster le nom, la version et l’url du dépôt ainsi que la licence et les auteurs.

Lancer la commande :

$ npm install

Créer les pages html avec Twig

Le fichier dev/templates/layout/base.html rassemble les éléments communs à tous les projets.

Le fichier dev/templates/layout/base-projet.html hérite de la base.html et ajoute les particularités communes à toutes les pages d’un projet.

Le fichier dev/templates/index.html sert de centre d’aiguillage pour les pages prêtes à être recettées.

Le répertoire pages/ accueille les pages complètes. Une première page est livrée avec le dépôt pour le styleguide, qui sera à compléter avec les éléments propres au projet.

Des tâches gulp génèrent les pages html dans le répertoire public/ :

  • gulp make:html pour compiler
  • gulp watch:html pour la compilation au fil de l’eau

Prise en charge de markdown

Les contenus en markdown peuvent être insérés de deux façons :

  • en saisie directe dans un template :

    {% markdown %} Contenu {% endmarkdown %}

  • par inclusion de fichier depuis un template :

    {% markdown 'chemin/relatif/vers/fichier/md' %}{% endmarkdown %}

Gérer les fichiers javascript

Recopier les répertoires dev/styles/scss/scampi/libs/ et dev/styles/scss/scampi/main/ avec leurs contenus dans le répertoire dev/scripts/.

Lorsque vous utilisez un module de scampi comportant un script, recopiez-le dans dev/scripts/main/.

(Note: un fichier est déjà présent dans le répertoire main de référence de Scampi. Il s’agit de la correction d’un bug de focus Chrome/Safari/IE.)

Des tâches gulp concatènent et déplacent les fichiers de script dans le répertoire public/ :

  • gulp move:js-libs pour déplacer les fichiers rangés dans libs/
  • gulp make:js-main pour concaténer et minifier les fichiers rangés dans main/
  • gulp make:js pour faire conjointement les deux tâches précédentes.

Compiler les css

Un fichier prêt à l’emploi est présent dans dev/styles/scss/projet/. Pour personnaliser un projet :

  1. recopier dans projet le fichier core-scampi-settings, le renommer et le personnaliser, l’importer en lieu et place de celui de scampi ;
  2. dans style.scss décommenter les imports de modules scampi utilisés tels quels ;
  3. ajouter les modules et partials propres au projet.

Deux tâches gulp sont disponibles :

  • gulp make:css pour la compilation et le placement du fichier css dans public/ ;
  • gulp min-css pour la minification.

Traiter les icones svg

Si les gabarits comportent des icônes au format svg, elles doivent être placées dans dev/static/icones/unitaires/. À titre d’exemple, 2 icônes y sont déjà placées.

Une tâche gulp permet de générer depuis ce répertoire un sprite d’icones svg à utiliser dans les gabarits :

  • gulp make:svg transforme les icones unitaires en sprite (icon-sprite.svg) et le place dans dev/static/icones/

Le sprite sera déplacé avec les autres resssources statiques quand on effectuera la commande gulp générale gulp move:static.

Déplacer les fichiers statiques

Les éléments du répertoire dev/static/ et styles/ (à l’exclusion des scss) sont déplacés tels quels dans le répertoire public grâce à des tâches gulp.

  • gulp move:static pour tous les éléments du répertoire static
  • gulp move:assets pour tous les éléments du répertoire des styles sauf les scss

Récapitulatif des tâches gulp principales

  • Tout construire : gulp build
  • Tout nettoyer : gulp clean
  • Compiler sass : gulp make:css
  • Compiler twig : gulp make:html
  • Watch html et css : gulp

Liste d’échanges et d’information :

S'abonner.

Licence

Scampi-twig est distribué sous une double licence : MIT et CeCILL-B.

Vous pouvez utiliser Scampi avec l’une ou l’autre licence.