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 Scampi 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 https://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

Ou

  $ yarn

Si yarn est installé sur votre ordinateur et que vous préférez l'utiliser.

Un ensemble de tâches gulp est disponibles dans le répertoire tasks/ du dépôt. On peut les lister avec leur résumé grâce à la commande :

  $ gulp help

Créer les pages html avec Twig

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

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

Le fichier dev/templates/index.twig sert de centre d’aiguillage pour les pages prêtes à être recettées ; ce n'est pas le gabarit de la home du projet.

Le répertoire pages/ accueille les pages complètes. Trois pages sont livrées avec le dépôt pour le styleguide, qui sera à compléter avec les éléments propres au projet.

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

Compiler les css

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

1. recopier dans *project/* le fichier core-scampi-settings, le renommer et le personnaliser, l’importer à la 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.

Traiter les icônes 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, trois 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.

Le sprite sera déplacé avec les autres resssources statiques quand on effectuera le build.

Déplacer les fichiers statiques

Les éléments du répertoire dev/_assets/project/ (à 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.

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.