Cette partie décrit comment définir et faire évoluer un site d'artiste, puis comment l'administrer.
On lira avec bénéfice les articles concernant la publication du contenu dont seulement les plus importants ont été repris ici.
Ces pages sont réservées aux concepteurs et aux administrateurs des sites, mais peuvent être lues par les webmestres curieux du fonctionnement du logiciel.

Articles

1. Page de gestion d'un site

L'initialisation d'un site fait partie de la phase de conception ; il est toutefois utile en phase de production de connaître les principales valeurs affectées aux paramètres du site. Cet article décrit la page de gestion d'un objet Site (Site), sous réserve des attributs neutralisés par le moule associé.

2. Arbre des espaces

L'arbre des espaces constitue véritablement l'ossature d'un site, parce que tout le contenu et les ressources associées lui sont rattachés et parce que la navigation principale dans le site est basée sur sa structure.

3. Page d'introduction

Facultative, la page d'introduction s'affiche lors de l'appel de l'adresse de base du site pour présenter une image ou une animation de bienvenue.

4. Paramètres de génération des pages

L'usage des générateurs, et parmi eux surtout les composants, peuvent s'adapter au contexte de chaque espace grâce à des paramètres de génération (gen_params).

5. GAL, le langage des générateurs

Les générateurs peuvent être écrits dans le langage GAL, proche du langage HAML et dans lequel le code GAL est traduit avant d'être exécuter par l'application projet_a. Le convertisseur du code GAL en HAML ressemble d'ailleurs plus à un filtre qu'à un véritable compilateur.

La phase de conception d'un site est à la fois la plus créative et la plus technique :

  • la plus créative, car il faut imaginer créer la maquette du site, à la fois conforme au travail de l'artiste, montrant la valeur de ses œuvres, mais aussi esthétique et agréable à consulter, voire originale ;
  • la plus technique, car elle mobilise la pleine connaissance des capacités et des mécanismes du logiciel, sans parler des techniques web, notamment pour les feuilles de styles.

Si la participation de l'artiste, titulaire du site, est indispensable a minima pour donner son accord sur l'image rendue de son travail, la manipulation des outils pour la réalisation concrète sera effectuée par quelqu'un ayant les compétences nécessaires.

Un des objectifs du projet A est de rendre la création technique d'un site aussi simple que l'assemblage de briques dans un jeu de Lego, mais d'une part la plupart d'entre nous a perdu son âme d'enfant, d'autre part et surtout les premières versions du logiciel ne rempliront que très partiellement ce résultat, les priorités étant de produire des sites de qualité, faciles à mettre à jour.

Une fois en exploitation, l'administrateur vérifiera son bon fonctionnement et l'adaptera aux changements de contextes technique et fonctionnel : adaptation aux nouvelles versions, magasins de fichiers...

Écrans de gestion

Les écrans de gestion du logiciel sont réservés aux gestionnaires de site et aux administrateurs. Ils donnent une vision très concrète du produit.

Voir l'article Copie des écrans de gestion.

Articles en projet

  • La maquette du site
  • Vues et gabarits : les générateurs
  • Les feuilles de styles
  • Les moules de saisie
  • Les magasins de fichiers
  • Le paramétrage d'un site

Création et administration d'un site

1. Page de gestion d'un site

L'initialisation d'un site fait partie de la phase de conception ; il est toutefois utile en phase de production de connaître les principales valeurs affectées aux paramètres du site.

Cet article décrit la page de gestion d'un objet Site (Site), sous réserve des attributs neutralisés par le moule associé.

Il faut noter également que beaucoup des paramètres des générateurs valables pour tout le site sont définis sur l'espace racine du site, celui qui en général correspond à la page d'accueil.

Voir l'article Copie des écrans de gestion, § 3.2 et suivant.

1. Attributs non modifiables

Les attributs suivants ont un impact sur l'enregistrement des données et l'accès au site ; ils ne sont donc modifiable que par l'administrateur du projet A.

Nom° : Nom du site. Utilisé pour le classement des données et comme sous-domaine pour l'accès au site en l'absence de nom de domaine spécifique.

Code° : Code du site = initiales ou autres, en majuscules. Utilisé comme abréviation du nom et préfixe des noms de ressources.

Langues° : Langue principale du site et liste éventuelle des langues secondaires.

Visibilité° : Restriction à la consultation du site.
Valeurs possibles (un niveau englobe les suivants) :

Visiteur → tous les internautes sans restrictions
Invité → tous les invités au site
Abonné → tous les internautes abonnés au site
Membre → tous les membres du site
Gestionnaires → tous les titulaires, webmestres, modérateurs et administrateurs du site (et les super-administrateurs)

URL : Adresse publique d'accès internet au site.

Espace racine° : Référence de l'espace racine de l'arborescence du site, correspondant en général à sa page d'accueil.

Paramètres : Liste de paramètres de configuration du site.
Par exemple : styles pour la saisie de textes, adresses des magasins de stockage de fichiers.

2. Attributs modifiables

En phase de production, le webmestre peut modifier les champs suivants, tous visibles sur la version publique de la fiche descriptive du site :

Titre : Titre du site. Utilisé en général sur la page d'accueil.

Titre court :Titre plus court du site. Utilisé en général à la fin du titre HTML de toutes les pages du site

Sous-titre : Sous-titre du site. Utilisé en général sur la page d'accueil.

Description : Courte description du site. Cette information est reprise par la fiche du site et est souvent par les moteurs de recherche.

Mots-clés : Liste de mots-clés pour les moteurs de recherche, séparés par des virgules. Nombre à limiter impérativement.

Espace d'intro : Référence facultative de l'espace correspondant à la page d'introduction du site.

Espace d'actualités : Référence facultative de l'espace correspondant à la page d'actualités du site. La description des actualités peut être reprise sur la page d'accueil par exemple. La description des actualités publiques et actives est aussi reprise sur la page d'accueil du projet A.

Fond : Paramètres du fond d'écran sur les écrans de gestion du site et en général sur ses pages.
Format conformes aux spécifications CSS : couleur[ image[ répétition]
Exemples :

moccasin → couleurs HTML prédéfinies
#dad → valeurs sur 3 ou 6 chiffres hexadécimaux
steelblue url('/images/bg_projet_a.jpg') repeat-x → avec image de fond

Étiquettes d'objets : Liste d'étiquettes utilisables pour marquer les objets joints aux œuvres.

Paramètres : Paramètres de gestion globaux au site.

Remarques : Remarques de gestion, réservées aux gestionnaires.

À faire : Marque l'enregistrement pour mention dans l'état « À faire » des tâches à réaliser pour le site, état réservé aux gestionnaires.

NB : Le ou les titulaires du site figurent sur la page de gestion à titre d'information. Ils sont gérés par des abonnements spécifiques.

3. Commandes

3.1. Structure

Espaces : Liste les espaces du site.

Œuvres : Liste les œuvres du site.

Générateurs : Liste les générateurs du site.

CSS : Affiche la feuille de styles du site.

3.2. Interactions

Abonnements : Liste des abonnements au site.

Groupes : Liste des groupes du site.

3.3. Ressources

Plan : Plan du site (arbre des espaces et œuvres associées).

id : Permet de retrouver un objet du site par son type et son identifiant.

Fichiers : Recherche parmi les fichiers du site.

Statistiques : Affiche des informations de volumes sur le contenu du site.

À faire : Liste les remarques des éléments du site marqués "À faire".

3.4. Enregistrement

Modifier : Formulaire de modification du site.

Voir : Affiche la page d'accueil du site avec un niveau de visibilité donné.

version 0.8.11-0309-130703

Création et administration d'un site

2. Arbre des espaces

Définition de la structure d'un site

L'arbre des espaces constitue véritablement l'ossature d'un site, parce que tout le contenu et les ressources associées lui sont rattachés et parce que la navigation principale dans le site est basée sur sa structure.

Treeview 110825

La gestion des espaces est accessible depuis plusieurs écrans de gestion des sites. Pendant la consultation d'un site, le lien sur le symbole © en bas de page envoie en général sur l'écran de gestion de l'espace correspondant, après demande d'authentification si nécessaire.

Voir la copie des écrans, § 4.

1. Typologie des espaces

On peut classer les espaces en plusieurs catégories en fonction de leur utilité à structurer et à produire le site : espaces racine, réels, virtuels, ressources ou réserve.

1.1. L'espace racine

L'espace racine est la base de la structure du site. La navigation et donc les menus partent de lui. En l'absence de page d'introduction, il produit la page d'accueil sur le site.

L'espace racine est créé à la création du site et ne peut être supprimé ; il n'a pas de parents.

1.2. Les espaces réels

Les espaces réels produisent des pages et pour cela référencent au moins un générateur. Ceux qui contiennent des œuvres utilisent généralement un ou deux générateurs complémentaires pour les afficher.

1.3. Les espaces virtuels

Les espaces virtuels apparaissent dans les menus de navigation, mais ne produisent pas directement de pages : ils redirigent les internautes qui les appellent vers un autre espace.

Ils permettent ainsi une amélioration de la lisibilité de la structure du site, sans produire de pages inutiles.

1.4. L'espace des ressources d'un site

L'espace des ressources d'un site est un espace technique, non affiché aux internautes, mais dont le contenu est utilisé de multiples fois par les espaces réels du site : fond d'écran, logo, signature, etc.

Quand il existe, l'espace générant la page d'introduction est parqué dans l'espace Ressources et il est référencé comme attribut général du site.

L'espace Ressources est créé à la création du site et ne peut être supprimé ; il n'a pas de parents.

1.5. L'espace de la réserve d'un site

L'espace de la réserve d'un site est un espace de travail dans lequel seront stockées les œuvres décrochées d'un espace ou créées sans rattachement à un espace. Cette réserve joue un peu le rôle de la poubelle de Windows et des autres systèmes d'exploitation.

L'espace Réserve est créé à la création du site et ne peut être supprimé ; il n'a pas de parents.

2. Affichage

L'arbre des espaces est affiché sur les pages de gestion des espaces et de chaque espace ainsi que sur plan du site. Il peut apparaitre aussi sur les sites sur la page Plan du site et dans un panneau de navigation comme sur aio.eu.

2.1. Arborescence

L'arbre des espaces est affiché par un composant qui permet d'ouvrir ou de fermer une branche pour afficher son contenu : sous-espaces et parfois œuvres.

Un clic sur [+] ouvre la branche, sur [-] la referme. Le cas échéant, les commandes Tout ouvrir et Tout fermer agissent sur toutes les branches.

La couleur du fond est plus lumineuse en fonction du niveau dans l'arborescence. Elle devient grise pour l'espace courant, jaune pour un espace survolé lors d'une opération de collage, puis transitoirement rouge pour confirmer cette opération.

Les œuvres sont distinguées par l'icone Icone d'une œuvre en début de ligne.

2.2. Détails

Sur les pages de gestion, la ligne d'un espace comprend :

  • le numéro d'ordre de l'espace parmi ses frères ;
  • le titre, avec un lien vers la page de gestion correspondante ;
  • entre parenthèses, le nombre de collages sur l'espace.

2.3. Visibilité

La ligne d'un espace ou d'une œuvre à visibilité restreinte a une bordure de couleur à gauche : bleu = abonné ; vert = membre ; rouge = gestionnaire.

version 0.8.10-0264-121209

Création et administration d'un site

3. Page d'introduction

où comment accueillir l'internaute

Facultative, la page d'introduction s'affiche lors de l'appel de l'adresse de base du site pour présenter une image ou une animation de bienvenue.

Projeta intro space 320x76 110916

Automatiquement après quelques secondes ou sur un clic de souris de l'internaute, elle conduit à la page d'accueil du site, celle qui permet la navigation principale sur le site et qui est le sommet réel de l'arbre des espaces du site.

 

1. Création d'un page d'introduction

1.1. Générateur d'une page d'introduction

La page d'introduction est en général techniquement très simple. Par exemple, une vue composée du composant p1009 « image + texte » avec le gabarit générique minimal g0001 est généralement suffisant. L'accès à la page d'accueil se fera par un lien sur le texte et éventuellement par l'ajout dans l'entête HTML d'un renvoi temporisé, paramétrable ou non, vers la page d'accueil.

1.2. Espace d'introduction

L'espace support de la page d'introduction doit être créé comme fils de l'espace des ressources du site. Plusieurs espaces d'introduction peuvent être créé, mais au plus l'un d'entre eux sera activé à un instant donné.

L'espace d'introduction sera rempli en conformité avec son générateur. L'exemple précédent demande d'y coller une œuvre comportant l'image de fond et le texte à y superposer, avec un usage 'picture+text'.

1.3. Activation d'une page d'introduction

Sur l'écran de gestion du site, le champ Espace d'intro liste tous les espaces fils de l'espace ressource du site. Sélectionnez-en un pour l'activer ; sélectionnez Aucun pour le désactiver.

2. Exemple

Voir le site de Catherine Séher.

2.1. Générateur

Gabarit : g0001_minimal_layout

Source cs_intro.html.haml :

-# caterine.seher : vue cs_intro
#intro
= render 'see/p1009_picture_and_text'

2.2. Espace

Parent : Ressources du site
Titre :Bienvenue !
Générateur : cs_intro
Visibilité : Visiteur
Paramètres : refresh_delay = 10

Collage
    Œuvre : -intro
    Usage : picture+text

2.3. Œuvre

Nom : -intro

Texte, avec lien sur la totalité vers /see/15/home (15 = id du site)

catherine séher
peintre

Fichier normal : CS-intro4.jpeg
grande image et haute pour les écrans 4/3, fortement compressée (pour être chargée rapidement)

2.4. Extrait de la feuille de style

#intro {position:absolute; left:0; top:0; width:100%;
  opacity:1; -moz-transition:opacity 4s ease-in 6s;
  -webkit-transition:opacity 4s ease-in 6s;
  -o-transition:opacity 4 ease-in 6s; transition:opacity 4s ease-in 6s;=#Syntax}
#intro:hover {opacity:0;=#Syntax}
#intro img {width:100%;=#Syntax}
#intro p {position:absolute; top:50px; left:50px;
  font-size:3em; letter-spacing:.1em; text-shadow:1px 1px 2px #ccc;=#Syntax}
#intro p + p {margin-top:1.5em; font-size:2.4em;}
#intro p a {color:#333;=#Syntax}

Commentaires :

  • tout est positionné en absolu en haut à gauche de la fenêtre du navigateur ;
  • le bloc contenant l'image et l'image elle-même sont étirés (ou comprimés) à la largeur de l'écran ;
  • la transition efface l'écran (opacité 1 → 0) sur une durée de 4 secondes, mais avec un retard de 6, le paramètre refresh_delay=10 entraine alors le basculement vers la page d'accueil.

Création et administration d'un site

4. Paramètres de génération des pages

Comment adapter les composants aux espaces

L'usage des générateurs, et parmi eux surtout les composants, peuvent s'adapter au contexte de chaque espace grâce à des paramètres de génération (gen_params).

Les paramètres de génération des pages sont multiples et très évolutifs en fonction des générateurs. Leur enregistrement comme attributs des tables de la base de données oblige l'adaptation fréquente de sa structure et la définition superflue de beaucoup de valeurs non utilisée pour une page. Pour éviter ça, un attribut parameters dans les tables spaces et generators enregistre une liste de valeurs qui seront utilisées dans les processus de génération des pages ; chaque paramètre est de plus définit en cascade suivant l'arbre des espaces.

1. Format des paramètres

Chaque attribut parameters est un texte dont chaque ligne définit la valeur d'un paramètre.

Toutes les valeurs sont traitées comme des chaines de caractères.

1.1. Syntaxe d'une ligne

[+|–] cle_alphanum[(:| =>| =) (valeur|'valeur'|"valeur")] [# commentaire]

Une ligne comporte, dans l'ordre :

  • un indicateur d'importance, facultatif ;
  • un identifiant de paramètre, obligatoire ;
  • un groupe valeur facultatif comprenant :
    • un séparateur d'affectation « : » (non précédé d'une espace), « => » ou « = »,
    • une chaine de valeur ;
  • un groupe commentaire facultatif comprenant :
    • un séparateur « # » de commentaires,
    • une chaine de commentaire, facultatif.

Des espaces ou assimilées (tabulations, retour-chariot, saut de ligne...) peuvent être ajoutées entre les champs précédents ainsi qu'en début ou en fin de ligne.

Les lignes vides ou blanches ou ne comportant que des commentaires sont ignorées.

1.2. Indicateur d'importance

L'indicateur d'importance peut être l'un des suivants :

  • le signe plus « + », indiquant que la valeur ne peut pas être redéfinie ;
  • le signe moins « – », indiquant que la valeur ne peut pas être héritée.

1.3. Identifiant

Un identifiant est composé d'un ou plusieurs caractères parmi les lettres minuscules ou majuscules, les chiffres et le caractère « _ » de soulignement. La casse des lettres est significative.

Par convention, la partie précédent le premier souligné désignera le composant de référence.

1.4. Valeur

La valeur est extraite après le signe égale,

  • soit entre deux apostrophes simples « ' » ;
  • soit entre deux apostrophes doubles « '' » ;
  • soit du premier caractère non blanc jusqu'au signe « # » de commentaire ou la fin de la ligne.

L'absence de signe égale et de valeur est équivalent à la valeur Vrai (true).

1.5. Valeur indirecte

Si la valeur est extraite après le signe égale commence par une étoile « * » (la valeur ne doit pas être entre apostrophes), alors la chaine qui suit l'étoile donne le nom de l'identifiant dont il faut prendre la valeur.

1.6. Valeur « nil »

Une valeur peut être supprimée en lui donnant la valeur « nil » sans la placer entre apostrophes. Son usage est utile pour arrêter sa transmission lors de la collecte des valeurs décrite au chapitre suivant.

NB : Placée entre apostrophes ("nil" ou 'nil'), la valeur sera réelle et celle des trois lettres n, i, et l.

1.7. Valeurs « true » et « false »

De même, les valeurs Vrai (true) et Faux (false) sont définies en plaçant les mentions « true » et « false » directement après le signe égale (=), sans apostrophes simples ou doubles.

1.8. Exemples

Syntaxe correcte :
+ p9001_contact = 'Atelier'
site_code=CM
  +valeur_vide
   footer_with_comments => nil
– préfixe: *site_code
Syntaxe incorrecte :
= indicateur incorrect
cle : valeur # espace avant :
param = 'valeur # pas de 2° apostrophe
couleur = *bordure (si bordure non définie)
Syntaxe ambigüe :
fond_clair = #336699
écrire :   fond_clair = '#336699'
interprétée comme
fond_clair = '' → # commentaire 336699

2. Priorité des valeurs

2.1. Ordre de collecte des valeurs

Les attributs parameters sont collectés et concaténés sur les enregistrements, dans l'ordre suivant :

  1. du générateur associé à l'espace courant ; 
  2. des ancêtres de l'espace courant, en partant de l'espace racine jusqu'à cet espace courant.

La liste concaténée est alors analysée de la première à la dernière ligne.

2.2. Gestion des collisions

Si la valeur d'un même paramètre est définie plusieurs fois, celle qui sera prise en compte sera :

  • la première marquée importante (par le signe +),
  • sinon la dernière rencontrée, une valeur peu impor­tante (signe –) étant ignorée si elle n'est pas sur l'espace courant.

Une valeur importante (+) ne peut donc être redéfinie.

Une valeur peu importante (–) sur un espace n'est prise en compte que pour cet espace. Sur un générateur, elle sera ignorée, car effacée au niveau des espaces.

NB : Il est possible de définir une valeur applicable sur toute une branche d'espaces sauf à sa racine. Pour ça, il faut la déclarer deux fois dans les paramètres de la racine, une première fois normalement, puis comme valeur nulle peu importante.

Ex. :     couleur_fond: yellow
- couleur_fond: '#3cc'
    footer_with_comments
- footer_with_comments: nil

La première ligne définit la valeur qui sera héritée par les espaces fils, la seconde la redéfinit loca­lement pour l'espace courant. Il est à noter dans l'exemple de droite que la première ligne définit une valeur vide (pas de valeur) et la seconde la supprime (pseudo-valeur nil).

version 0.9.5-0429-141207

Création et administration d'un site

5. GAL, le langage des générateurs

Les générateurs peuvent être écrits dans le langage GAL, proche du langage HAML et dans lequel le code GAL est traduit avant d'être exécuter par l'application projet_a. Le convertisseur du code GAL en HAML ressemble d'ailleurs plus à un filtre qu'à un véritable compilateur.

Notes préliminaires :

Dans la notation de la syntaxe des instructions, les crochets [ ] indiquent une partie optionnelle et les triples points ... signalent une partie répétitive.

Le texte en italiques surlignées décrit des limitations actuelles du convertisseur, sujettes à une nécessaire évolution.

* L'étoile signale les dispositions qui sont réservées aux générateurs à gestion globale. Leur présence dans le code d'un générateur à gestion locale génère une erreur en post-traitement de l'analyse de son code source.

Pour faciliter la comparaison, le présent document a une structure similaire au document de référence de HAML.

1. Fonctionnalités

1.1. Fonctionnalités générales

  • Sous-ensemble structuré du HAML → simplification de la syntaxe
  • Limitation aux fonctions cloisonnées pour les concepteurs de site → sécurité
  • Ouverture possible pour les concepteurs de composants et les super-administrateurs → souplesse

1.2. Présentation

Le langage GAL est globalement un sous-ensemble du langage HAML.

Les ajouts concernent soit des simplifications d'écriture des formes les plus fréquentes (render), soit la déclaration des attributs des générateurs.

Les restrictions opérées visent soit une simplification de la syntaxe pour simplifier l'apprentissage et pour réduire les risques d'interprétation, soit une sécurisation du code par la non implémentation des fonctions potentiellement dangereuses. Elles peuvent aussi résulter d'un développement encore limité du compilateur ; dans ce cas, elles disparaitront sans doute dans une version ultérieure du compilateur.

Pour des raisons de sécurité, les concepteurs d'un site ne sont autorisés à écrire que des générateurs à gestion locale, donc obligatoirement écrits en GAL ; ils peuvent bien sûr utiliser les composants globaux. Si leurs besoins dépassent les limites du langage, ils devront faire appel à un super-administrateur qui soit adaptera un composant existant ou en écrira un nouveau, soit développera le générateur souhaité en gestion globale.

Le compilateur GAL ne vérifie pas intégralement si le code source est conforme à la syntaxe Ruby. Il se limite à vérifier juste ce qu'il est nécessaire pour garantir le cloisonnement des sites et la sécurité de l'application. Il peut donc laisser passer des erreurs Ruby qui seront détectées lors de l'exécution du fichier HAML produit.

Le compilateur GAL n'est pas encore terminé, mais le noyau réalisé permet l'écriture de la quasi-totalité des générateurs de site, hormis les gabarits, et donc d'en laisser la responsabilité aux concepteurs de site sans risque pour la sécurité des autres sites et celle de l'application.

2. Utilisation du langage

2.1. Classe Gal

Le convertisseur est réalisé sous la forme de la classe Ruby de nom Gal, intégrée dans le module GalHelper.

Le constructeur de cette classe prend deux paramètres facultatifs :

Gal.new(generator = nil, options = {})

  • generator = référence sur un générateur (de type Generator, Fixnum ou String)
  • options = liste d'options sur le contrôle du flux

Il est possible de définir ou de redéfinir le générateur de base d'un objet Gal par la méthode generator=.

Si aucun générateur n'est défini, la méthode source= permet d'initialiser un code source (de type String) à traiter.

Si le générateur est défini, le code source traité sera celui enregistré dans le fichier d'extension .gal dans le dossier des fichiers source du site ou dans celui des composants si le générateur est commun.

Les méthodes suivantes restituent les paramètres d'état :

  • generator = référence du générateur associé (de type Generator)
  • options = liste des paramètres d'appel du convertisseur
  • source = code source (de type String)

Le contexte est aussi défini par plusieurs attributs ou méthodes du générateur : filename('gal'), updatable (vrai en gestion locale, faux en gestion globale)...

La conversion est effectuée par l'application de la méthode haml sur un objet de type Gal.

Cette méthode retourne le code HAML produit. Plusieurs autres méthodes permettent de récupérer d'autres résultats ou indicateurs :

  • attributes : liste des attributs du générateur à modifier, avec leurs valeurs
  • rules : liste des paramètres d'appel du générateur, avec les valeurs par défaut
  • errors_count : nombre d'erreurs détectées par la conversion
  • require_global_management : vrai si le code contient une instruction protégée, faux sinon

Il est enfin possible d'appeler en pré- ou en post-traitement la méthode write_error(type, message) qui génère une ligne d'erreur au format d'un commentaire HAML (-#) et qui augmente le compteur d'erreurs.

2.2. Options

Les options suivantes peuvent être positionnées lors de l'appel du constructeur de la classe Gal. Elles sont toutes du type Boolean.

  • :verbose = génère en commentaires toutes les informations du convertisseur
  • :comment = génère les lignes de commentaires
  • :blank_lines génère les lignes blanches
  • :source_lines = génère en commentaires une copie des lignes source

L'effet de ces options est modifiables par des commandes dans le code source.

2.3. Codage

Les fichiers source GAL sont supposés avoir des caractères codés au format international UTF-8.

Les fichiers HAML sont produits dans ce même format. Ils commencent par la ligne de déclaration de ce format :

-# coding: utf-8

2.4. Indentation et structure du code

L'indentation des lignes représente l'inclusion des différents blocs HTML ou des blocs de code Ruby.

L'indentation doit être respectée suivant cette logique. La seule exception concerne les commandes GAL.

Le pas d'indentation est fixée à 2 espaces.

L'indentation en entrée n'est pas testée. Elle est restituée en sortie.

3. Pein texte

3.1. Texte simple

Le texte est une suite de caractères qui forment en général l'essentiel du contenu sémantique de la page HTML vers la quelle il est transféré sans modification.

texte

Une ligne de texte ne doit pas commencer par l'un des caractères - = ~ ! & : / # . %

Du texte peut figurer seul sur une ligne ou suivre une balise HTML, un identifiant ou une classe. Il ne doit toutefois pas comporter d'interpolation de code par une séquence #{ }.

3.2. Caractère d'échappement \

La barre de fraction inversée \ permet de lever la limitation sur le premier caractère d'une ligne de texte.

\texte

La caractère \ est copié vers la sortie HAML, mais il ne sera pas intégré dans la page HTML finale.

4. Éléments HTML

Les balises structurent le code des pages HTML qui seront finalement servies aux internautes.

4.1. Nom d'une balise HTML : %

%tag[#ident][.class1[.class2[...]]]{attr1: value1[, attr2: value2[, ...]]} [Text]

La code d'une balise est composé d'une ou de plusieurs lettres. Leur casse est indifférente.

Une balise peut être immédiatement suivie, dans cet ordre, d'un identifiant, d'une ou de plusieurs classes, d'une liste d'attributs, puis d'une espace et d'un texte HTML. La syntaxe HAML interdit que la présence d'un texte sur la même ligne soit suivi d'un bloc indenté sur les lignes suivantes (règle non testée par le compilateur GAL).

4.2. Attributs

Les attributs HTML précisent la balise qui précède, en début de ligne, ou implicitement la balise div si seuls un identifiant ou une ou plusieurs classes sont mentionnés.

La liste d'attributs est placée entre accolades :

%tag[#ident][.class1[.class2[...]]]{attr1: value1[, attr2: value2[, ...]]}  [Text]

La liste peut contenir un ou plusieurs couples nom: valeur.

Des espaces peuvent être insérés à volonté entre chaque élément de la liste, sauf entre un nom et le caractère deux-points : qui le suit.

NB : Si, au moment de la génération de la page HTML, une valeur a la valeur false ou nil, alors l'attribut correspondant ne sera pas généré.

{#.#. =4.3. :Identifiant et classes : # et .#}

Identifiant

Un identifiant sert à repérer un bloc du code HTML généré pour l'application des styles CSS ou du code Javascript. Un identifiant doit être unique sur une page HTML (non testé par le compilateur GAL qui n'en voit qu'une partie).

Un identifiant peut être placé soit après une balise HTML pour la qualifier, soit en début de ligne. Dans ce cas, une balise HTML div sera générée pour le rattachement de l'identifiant.

#ident[.class1[.class2[...]]]{attr1: value1[, attr2: value2[, ...]]} [Text]

Une balise ne peut avoir qu'un seul identifiant.

Un identifiant peut être suivi, dans cet ordre, d'une ou de plusieurs classes, d'une liste d'attributs, puis d'une espace et d'un texte HTML. La syntaxe HAML interdit que la présence d'un texte sur la même ligne soit suivi d'un bloc indenté sur les lignes suivantes (règle non testée par le compilateur GAL).

Classe

Une classe sert à repérer un bloc du code HTML généré pour l'application des styles CSS ou du code Javascript. Une classe peut être réutilisée sur une page HTML.

Une classe peut être placée soit après une balise HTML ou un identifiant, soit en début de ligne. Dans ce cas, une balise HTML div sera générée pour le rattachement de la classe.

.class1[.class2[...]]{attr1: value1[, attr2: value2[, ...]]} [Text]

Une ou plusieurs autres classes peuvent être définies sur la même ligne, pour le même bloc div généré.

Elles peuvent être suivies, dans cet ordre, d'une liste d'attributs, puis d'une espace et d'un texte HTML. La syntaxe HAML interdit que la présence d'un texte sur la même ligne soit suivi d'un bloc indenté sur les lignes suivantes (règle non testée par le compilateur GAL).

4.3. Suppression des espaces : > et <

%tag[#ident][.class1[.class2[...]]]< [Text]
%tag[#ident][.class1[.class2[...]]]> [Text]

Si le code d'une balise, d'un identifiant ou d'une classe est immédiatement suivi du caractère inférieur <, les données internes à cette balise sont placées immédiatement après son code HTML généré, sans saut de ligne. Ce signe est inutile si du texte figure sur la même ligne, car dans ce cas aucun saut de ligne n'est normalement généré.

Si le code d'une balise, d'un identifiant ou d'une classe est immédiatement suivi du caractère supérieur >, le code généré par cette balise est placé immédiatement après le code précédemment généré.

Il est possible de combiner les deux codes sous l'une des deux formes %tag<> ou %tag>< .

5. Doctype : !!!

La déclaration du type du document HTML se place comme première instruction utile.

!!! doctype

Seule la valeur 5 pour le doctype est utilisable en mode de gestion locale d'un générateur. Elle correspond à la syntaxe HTML 5.

!!! 5 produit <!DOCTYPE html> sur la page HTML finalement générée.

* Les autres valeurs du doctype ne sont possibles qu'en mode de gestion globale. La liste des valeurs possibles figure sur la documentation de référence HAML.

6. Commentaires

Les commentaires sont écrites par les programmeurs pour faciliter la compréhension et la maintenance du code.

Les lignes vides ou blanches peuvent être considérées comme des commentaires.

Cette instruction destinée au programmeur n'est pas restituée dans le fichier produit, sauf dans le cas des commentaires conditionnels.

6.1. Commantaires HTML

/ [comments]

Cette forme génère des commentaires HTML <!-- Comments --> dans la page finale générée.

Un bloc indenté sous cette ligne n'est valide que si aucun texte de commentaire ne figure sur la ligne. Tout le bloc est également considéré comme un commentaire.

Des commentaires conditionnels pour le navigateur Internet Explorer de Microsoft sont générés par la séquence /[ I E ], sans les espaces à l'intérieur qui ne sont placés là que pour que cette page se génère correctement... Les commentaires conditionnels sont à placer dans un bloc indenté sous cette ligne.

6.2. Commantaires HAML

-# [comments]

Le troisième caractère ne doit pas être un point d'exclamation '!' ou une barre de fraction '/', respectivement réservés aux commandes et aux méta-attributs GAL.

Un bloc indenté sous cette ligne est valide, même si un texte de commentaire figure sur la ligne. Tout le bloc est également considéré comme un commentaire.

7. Évaluation de code Ruby

7.1. Insertion Ruby : =

Rédaction ultérieure.

7.2. Exécution Ruby : -

Non encore réalisé

7.3. Interpolation Ruby

Rédaction ultérieure.

8. Filtres : :

Non encore réalisé

9. Extensions GAL

9.1. Appel d'un composant ou d'un partiel : =>

L'appel d'un composant commun permet de produire une partie de la page qui sera affichée aux internautes par un élément de la bibliothèque commune du projet. L'appel d'un partiel du site est similaire avec un partiel propre au site.

C'est une instruction tellement importante pour les générateurs de site qu'une syntaxe spéciale (non HAML) lui est réservée.

=> [component:] name[[[, param1: value1], :param2], ...]
=> partial: name[[[, param1: value1], :param2], ...]

Le nom du composant ou du partiel est donné par une valeur, en général une mot (ex. : p1007_text), mais ce peut être aussi un symbole (ex. : :p1007_text) ou une chaine de caractères (ex. : 'p1007_text').

Le nom du composant ou du partiel peut être suivi par un ou plusieurs couples (paramètre, valeur). Si la valeur est omise (syntaxe : :param2), la valeur est supposée à true, cas très fréquent pour les options d'un composant.

Le nom d'un paramètre doit être immédiatement suivi du caractère deux-points, sinon des espaces peuvent être intercalées entre chaque éléments de l'instruction.

Un changement de ligne est autorisé après une virgule à condition que l'indentation des lignes suites soit identique et supérieure à celle de la première ligne de l'instruction.

La valeur d'un paramètre est soit une constante numérique, booléenne ou chaine de caractères entre simples ou doubles apostrophes ( ' ou " ), soit une variable locale ou de classe (nom précédé d'une arobase @), en particulier l'un des paramètres d'appel définis par le méta-attribut rules.

{#.#. =9.2. :Commandes GAL : -#!#}

Les commandes contrôle le flux de la compilation ou celui de l'ajout de commentaires dans le fichier produit. Un commande a donc un effet pour les lignes source qui la suit.

Au début de l'analyse d'un fichier source, l'état du compilateur est en mode GAL et en affichage non verbeux (pas de recopie des commentaires).

-#! command [comment]

L'espace préalable au code de la commande est indifférent : il peut être absent, simple ou multiple.

La casse des lettres est indifférente.

L'ajout d'un commentaire après le code de la commande est autorisé.

Par exception aux règles régissant l'indentation des lignes, celle d'une ligne de commande est indifférente. Il est donc possible de l'écrire sans indentation pour la rendre plus visible.

Cette instruction destinée au compilateur GAL n'est pas restituée dans le fichier produit.

Liste des commandes

  • Contrôle de la compilation
    • -#! Ignore
      Les lignes suivantes sont à ignorer par le compilateur.
    • -#! Continue
      La compilation reprend pour les lignes suivantes.
    • -#! Stop
      La compilation est arrêtée.
    • -#! HAML *
      Les lignes suivantes sont en HAML. Elles sont recopiées sans analyse.
    • -#! GAL
      Les lignes suivantes sont en GAL. Elles sont normalement traitées par le compilateur.
  • Contrôle d'affichage
    • -#! Verbose
      Les lignes blanches et les commentaires sont recopiées ainsi que toutes les observations du compilateur.
    • -#! Blank
      Les lignes blanches sont recopiées.
    • -#! Comment
      Les commentaires sont recopiés.
    • -#! Source
      Les lignes source sont recopiées en commentaires numérotés.
    • -#! No [source]
      Les lignes source ne sont plus recopiées.

* : La commande HAML est réservée aux générateurs à gestion globale.

{#.#. =9.3. :Méta-attributs du générateur : -#/#}

Les méta-attributs permettent de contrôler ou de positionner les attributs du générateur.

Les méta-attributs doivent être placés en début du fichier source, avant la première instruction générée.

Cette instruction destinée au compilateur n'est pas restituée dans le fichier produit, à l'exception de l'attribut Rules (voir ci-dessous)

-#/ attribute: value

La casse des lettres du code d'un attribut est indifférente.

Un attribut à valeur unique ne peut être défini qu'une seule fois.

Un attribut à valeurs multiples peut être défini en plusieurs fois, les différentes valeurs sont alors regroupées. Le code de l'attribut peut être donné au singulier ou au pluriel.

Un attribut booléen est vrai si la valeur est true, yes ou oui dans la langue courante (casse des lettres indifférente). Il sera faux pour toute autre valeur.

Un attribut est indéfini (nil) si la valeur est absente.

Liste des méta-attributs

  • Attributs à valeur texte unique
    • -#/ name
      Le nom doit être celui du générateur.
    • -#/ kind
      Type du générateur : space_view, work_view, layout, partial ou component.
    • -#/ title
      Titre du générateur.
    • -#/ layout
      Gabarit du générateur, parmi ceux du site ou les gabarits communs.
       
  • Attributs à valeur booléenne unique
    • -#/ updatable *
      Gestion locale (si true) par un concepteur du site ou globale (si false). Les valeurs local et global sont aussi acceptées.
      Le mode de gestion doit être celui du générateur.
    • -#/ positionable
      Indicateur de positionnement graphique des œuvres sur un espace. Sauf pour les composants, sa valeur est calculée.
      Un avertissement est généré en commentaire si la valeur n'est pas celle celle du générateur de type autre que component.
    • -#/ todo
      Indicateur de gestion À faire.
       
  • Attributs à valeurs multiples
    • -#/ tags
      Étiquettes de classement par catégories du générateur.
    • -#/ rules *
      Paramètres d'appel du générateur, avec leurs valeurs par défaut et leurs descriptions. Uniquement pour les composants et pour les partiels.
    • -#/ remarks
      Remarques de gestion.

* : Les attributs rules sont réservés aux générateurs à gestion globale, y compris pour les partiels.

Méta-attribut rules

Rédaction ultérieure.

version 0.9.5-0440-150106
↑ Haut