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

La procédure pour dépolyer le submodule Scampi varie selon que le fork (ou le clone) est fait via la ligne de commande, SourceTree ou un autre client graphique et dépend aussi de si le clone est fait en utilisant ssh ou https.

Voici la commande complète pour un fork en ligne de commande :

$ git fork git@gitlab.com:pidila/scampi-twig.git
$ cd scampi-twig/
$ git submodule init
$ git submodule update

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

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.)

Une tâche gulp concatène et déplace les fichiers de script dans le répertoire public/ :

  • gulp make:js-main pour concaténer et minifier les fichiers rangés dans main/

Compiler les css

Un fichier prêt à l’emploi est présent dans dev/_assets/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/_assets/project/icones/unitaires/. À titre d’exemple, deux 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/_assets/project/icones/

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

Déplacer les fichiers statiques

Les éléments du répertoire dev/_assets/ (à l'exception des css qui sont compilées séparément) sont déplacés tels quels dans le répertoire public grâce à la tâche gulp :

  • gulp install:assets

Récapitulatif des tâches gulp principales

On peut lister toutes les tâches gulp disponibles avec leur résumé grâce à la commande :

* `gulp help`

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.