• [^] # Re: Exemples ?

    Posté par . En réponse à la dépêche Sortie de Stog en version 0.15. Évalué à 2.

    Voici un exemple.

    Développer un site web statique consiste surtout à écrire ou générer des fichiers
    HTML (dans la suite je parlerai d'HTML, mais il s'agit dans le cas de Stog de
    fichiers (X)HTML, puisque Stog fonctionne surtout par réécriture d'arbres XML).

    On peut tout faire à la main, mais on se retrouve rapidement confronté à devoir
    assurer, à travers tous les fichiers, la cohérence de différentes choses,
    typiquement une barre de menu identique sur toutes les pages, et en général
    un <header> commun, à quelque chose près (comme le <title>).

    Pour cela, Stog offre un système de gabarits. Ainsi, je peux définir un
    gabarit page, dont le contenu sera stocké dans toto/.stog/templates/page.tmpl
    (si je suis en train de faire un site dont les sources sont dans toto).
    Ce gabarit aura un contenu de la forme suivante:

    <html>
<header>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title><doc-title/></title>
...
</header>
<body>
<div id="page-title"><doc-title/></div>
<div id="page-body">
<doc-body/>
</div>
</body>
</html>

    Là, c'est un contenu simple mais on a déjà deux balises qui seront remplacées
    à la compilation par un contenu: <doc-title> (le titre du document) et
    <doc-body> (le contenu du document).

    Ce gabarit me permettra donc de générer des pages de la même forme pour tous les
    documents du type "page".
    Pour écrire des documents du type "page", par exemple toto/foo.html, il suffit
    qu'il commence par un nœud "page" dans lequel on donne des métadonnées comme
    le titre:

    <page title="Ma page foo">
bla bla bla
</page>

    Avec un tel document, lorsque le gabarit "page" sera appliqué,
    <doc-body/> sera remplacé par bla bla bla et <doc-title/> par Ma page foo.

    Lors de la compilation du site, Stog génère un fichier pour chaque document.
    Ce fichier se retrouve dans le répertoire de destination avec le même chemin
    que le fichier source dans le répertoire des sources. Ainsi, si j'ai en plus
    du fichier toto/foo.html un fichier toto/bonjour/monde.html, je peux compiler
    ce site avec la commande stog -d dest toto; stog générera les fichiers
    dest/foo.html et dest/bonjour/monde.html en utilisant le gabarit indiqué
    dans chaque document et le contenu du document pour faire les substitutions
    qui vont bien.

    L'écriture d'un site web, ou même d'un simple document, ne se résume cependant
    pas seulement à l'utilisation de gabarit. On souhaite avoir également une cohérence
    interne, par exemple si on a des exercices, on souhaite que ces derniers
    soient toujours présentés de la même façon. Stog permet donc d'ajouter ses propres
    règles de réécriture, pour utiliser par exemple des balises <exercice> et
    avoir moins d'XML à taper.

    Voyons un exemple. Imaginons que je souhaite écrire un document foo/cours.html
    qui soit une page et dans lequel j'aurais plusieurs fois à donner un exercice.
    Je voudrais donc pouvoir utiliser une balise <exercice> en donnant un titre
    et un corps, de la façon suivante:

    <exercice title="Palindrome">
Ecrire une fonction ...
</exercice>

    Je souhaite que lorsque je mettrai ce code dans mon document, la réécriture
    me donne dans le document final

    <div class="exercice">
 <div class="exercice-title">Palindrome</div>
 <div class="exercice-body">Ecrire une fonction ...</div>
</div>

    Dans mon document foo/cours.html, je définirai donc une règle de réécriture,
    de la façon suivante:

    <page title="Cours de machin"
 with-contents="true">
<exercice title="">
 <div class="exercice">
 <div class="exercice-title"><title></div>
 <div class="exercice-body"><contents/></div>
 </div>
</exercice>
<contents>
...
<exercice title="Palindrome">
Ecrire une fonction ...
</exercice>
...
</contents>
</page>

    Quelques explications: Dans le premier nœud <page> du document,
    with-contents="true indique que le corps du document sera dans un nœud
    <contents> au lieu d'être juste sous le nœud racine. Cela permet d'ajouter
    des définitions de règles de réécriture supplémentaires, comme c'est le cas
    avec <exercice>, définie ainsi:

    <exercice title="">
 <div class="exercice">
 <div class="exercice-title"><title></div>
 <div class="exercice-body"><contents/></div>
 </div>
</exercice>

    Ce bloc indique qu'on définit une nouvelle règle qui s'appliquera pour les
    nœuds <exercice>. S'il n'y a pas d'attribut title, alors on indique une
    valeur par défaut qui est vide. Le contenu de <exercice> est ce qui remplacera
    le nœud <exercice> lors de la réécriture. On retrouve les balises <div>
    que je souhaite obtenir dans le document final. Dans cet arbre, on trouve
    également <title/> et <contents/>. Le premier sera remplacé par la valeur
    associé à title dans l'environnement (soit "vide" soit le contenu de l'attribut
    title de la balise <exercice> en cours de réécriture). <contents/> sera
    remplacé par le contenu de la balise <exercice> en cours de réécriture.
    Ainsi, lorsque dans le corps de mon document on trouve

    <exercice title="Palindrome">
Ecrire une fonction ...
</exercice>

    ce nœud est réécrit avec la règle définie, en associant la valeur Palindrome
    à <title/> et Ecrire une fonction ... à <contents/>.

    Si je souhaite changer la façon dont apparaissent les exercices dans le document
    final, il me suffit de changer la règle de réécriture mais pas chaque occurrence
    d'un exercice dans mon document.

    Stog permet de définir de nouvelles règles par document, mais aussi pour tout
    un site. Enfin, des greffons peuvent définir de nouvelles règles plus complexes,
    en ayant accès au nœud en cours de réécriture.