Documentation

UGML UltraGreen Markup Language

UGML est un projet dont les débuts remontent a 1999. Il s'agit d'un langage à balises (Markup Language) mis au point par l'équipe Ultragreen.
Il a pour but de d'automatiser un certain nombre de taches récurrentes dans les problématiques de mises en page de documents.
UGML est à la fois un language, un framework, et un "moteur de template".

UGML sur le WEB

Si à l'origine UGML avait vocation à être décliné dans et pour plusieurs langage de programmation CGI C, Ruby, PERL ... et pour des usages au delà du WEB force est de constater que de part mon métier et mes compétences UGML à pris un fort tournant vers le WEB et si les spécifications d'UGML le rende susceptibles d'être décliné dans d'autres langages et pour d'autres usages seule l'API PHP à atteint un niveau de maturité permettant son usage en production.

Certes UGML n'a pas un rôle cle sur internet mais de nombreux sites internet fonctionnent déjà depuis plusieurs années avec des versions plus ou moins récentes UGML.

http://horsetrails.mn/
http://alma-immobilier.com/
http://zed-marketing.com/
http://terre-et-loire.com/
http://pierre-ricardou.com/

http://yves-berrier.com : Site d'un photographe Nantais
http://asso-sofia.org : Une association qui soutient des projets de construction d'orphelinats en Bulgarie
http://moulindegambais.com : Une salle de réception d'Ile de France
http://lefrancaisfaceaface.com : Un organisme de formation a la langue francaise (site en 4 langues dont russe et chinois)
http://marionhuet.com : Le site professionnel d'une graphiste indépendante.
http://abecedairedubabysitting.com : Site evenementiel lie a la parution d'un guide du babysitting.
http://manoirdesfoulons.com : Une autre salle de reception pour le même D.O. que la précédente
http://guibouleraies.com : Un gite rural. Un des premiers sites réalises en UGML.

UGML dans les grandes lignes

Comment fonctionne UGML. Le principe est simple. D'une part on a des fichiers de donnees ugml, de l'autre un ou plusieurs fichiers ugd dans lesquels on defini :
les variables d'environements du parser UGML
les extensions utilisables
les balises utilisables
Notion de TAG ou DEFTAG
La notion de tag est apparue des le debut des developpement d'UGML les tags sont en substance des balises auxquelles le parseur substitue leurs equivalent dans le langage cible. Ils sont definis dans un fichier ugd. Dans le fichier ugd on declare le tag puis on defini les valeurs de remplacement pour les tags d'ouverture et de fermeture.

Exemple de definition de tag
Dans cet exemple nous allons definir deux tags titre et stitre dont les equivalents souhaites en html sont respectivements
<h1> et <h2>
comme :

DEFTAG=titre=> &lt;h1&gt;|&lt;/h1&gt;
DEFTAG=stitre=> &lt;h2&gt;|&lt;/h2&gt;
NOTA BENE : La synthaxe ci-dessus est la syntaxe historique, elle est utilisee par defaut par le parseur mais il est desormais possible de modifier cette syntaxe selon vos besoins.

Exemple de fichier ugml
Regardons un peu a quoi ressemble le contenu d'un fichier ugml utilisant le fichier ugd precedent.
<titre>UGML comment ca marche ?</titre>
<stitre>A quoi ca ressemble ?</stitre>
Ca ressemble a ca ;).
Une fois que le document est interprete par le parseur celui-ci renvois le code html ci-dessous :

&lt;h1&gt;UGML comment ca marche ?&lt;/h1&gt;
&lt;h2&gt;A quoi ca ressemble ?&lt;/h2&gt;
Ca ressemble a ca ;).
Notion de HEADER
Pour faire le lien entre le fichier de description (ugd) et le fichier de donnee (ugml) nous avons introduit dans ce dernier un header dans lequel a l'instar des header html on trouve des donnees qui n'apparaissent pas directement a l'ecran. Le fonctionnement est proche dans le principe de ce que l'on fait en XML avec la DTD ou en (X)HTML avec les CSS.

Le header du fichier qui est la premiere ligne de celui-ci peut contenir informations dont une seule est "mainteant" indispensable.

le fichier ugd a utiliser
D'autres sont introduites dans le header par les extensions.

Exemple de fichier ugml complet
[HEADER]|ugd=test.ugd|[/HEADER]
<titre>UGML comment ca marche ?</titre>
<stitre>A quoi ca ressemble ?</stitre>
Ca ressemble a ca ;).
Resume intermediaire du fonctionement du parseur
Le parseur lit le fichier ugml et en recupere le header. Il ouvre le fichier ugd mentionne dans le header, recupere la definition des tags et applique les transformations sur le contenu du fichier ugml et affiche le resultat a l'ecran.

Typiquement pour un developpement Web ugml on a le processus suivant :

USER HTTP REQUESTS UGML FILE > SERVER REQUIRES PARSEUR FOR INTERPRETATION > PARSEUR PROCESSES THE FILE
USER HTTP CLIENT DIPLAYS RESULT <== SERVER REPLIES TO CLIENT <============ PARSEUR SENDS RESULT OF PARSING

Notion d'extension ou DEFEXT
La notion d'extension est apparue plus tard au court du developpement d'UGML. Le pricinpe est assez proche de la notion de TAG, il s'agit la aussi d'une substitution mais cette fois il ne s'agit pas d'une substitution statique (un tag en remplace un autre) mais d'une substitution dynamique. Les informations de remplacement viennent ici non pas du fichier ugd mais d'une fonction recuperant des donnees et/ou les mettant en forme. La fonction peut par exemple :

recuperer des donnees sur le filesystem pour construire une navigation
effectuer une redirection http
generer une images ou autres types de fichiers
lance une tache d'administration sur le server
gerer le contenu d'une base de donnee
creer une base de donnee a partir d'un modele
etc ...
Bref en fonction de vos connaissances et de vos idees faire a peut pres n'importe quoi ... Developpeur faite chauffe vos neurones.

Syntaxe standard de definition des extensions
La definition des extensions se fait (dans le fichier ugd) de la facon suivante :
DEFEXT=balise_extension=> nomdelafonctionaappeler|fichiercontenantladitesfonction|commentaire
NOTA BENE : La synthaxe ci-dessus est la syntaxe historique, elle est utilisee par defaut par le parseur mais il est desormais possible de modifier cette syntaxe selon vos besoins.

Exemple simple
Dans cet exemple nous nous baserons sur le parseur ugml ecrit en PHP et une extension bidon qui contient la tres demonstrative fonction hello. Cette fonction renvoi "hello Mr X & Y" en gras. Vraiment tres utile.

Fichier test.ugd
DEFEXT=gras=> hello|ext_bidon.php|Fontion tres utile faire tres attention
DEFTAG=titre=> <h1>|</h1>
DEFTAG=stitre=> <h2>|</h2>

Fichier test.ugml
[HEADER]|ugd=test.ugd|[/HEADER]
<titre>Les extensions comment ca marche ?</titre>
<stitre>Coment ca s'utilise ?</stitre>
<gras param="X|Y"/>
Ca ressemble a ca ;).

Fichier ext_bidon.php

function hello($data) {
return str_replace("|"," & ","&lt;b&gt;Hello Mr $data&lt;/b&gt;");
}
?>

Le resulat obtenu apres interpretation ...
<h1>UGML comment ca marche ?</h1>

<h2>A quoi ca ressemble ?</h2>
<b>Hello Mr X & Y</b>
Ca ressemle a ca ;).
Notion de variables d'environements ou DEFVAR
Un probleme nous est apparu lors d'un changement de version d'UGML sur nos sites web. Nous avions modifie la structures des sites et certains repertoires avaient changes de nom ou meme avaient disparu. Il nous a fallu e cette occasion rentrer dans le code des extensions ce qui n'est jamais souhaitable. Ceci releve de la configuration. Nous avons donc introduit un element supplementaire dans nos ugd. Les variables d'environements ou DEFVAR.

Syntaxe standard de definition des DEFVAR
DEFVAR=nom_variable=> valeur

NOTA BENE : La synthaxe ci-dessus est la syntaxe historique, elle est utilisee par defaut par le parseur mais il est desormais possible de modifier cette syntaxe selon vos besoins.
NOTA BENE BIS : Contrairement e la definition des extensions il n'est pas possible e l'heure actuelle d'introduire des commentaires dans les DEFVAR.

Principe de fonctionnement des DEFVAR
Le parseur lorsqu'il parcours le fichier UGD recupere l'ensemble des paires cle valeur et les charge en memoires. Elles sont alors accessibles sous formes de variables globales par le parseur et les extensions.

Notion de REFERENCES
Afin de facilite la construction des fichiers de configurations nous avons introduit des references. Ces references sont internes au fichier de configuration elles permettent de faire reference a un parametre de conf prealablement defini lors de la definition d'un autre.

Syntaxe standard des REFERENCES
Pour faire reference a un parametre on procede de la sorte :
[nomduparametre]

Exemple d'utilisation des references
Soit le fichier de configuration suivant :
DEFVAR=WEB_ROOT=> c:/wamp/test/
DEFVAR=ARTICLE_PATH=> c:/wamp/test/articles/
DEFVAR=ARCHIVE_PATH=> c:/wamp/test/archives/
DEFVAR=SCRIPT_PATH=> c:/wamp/test/scripts/biblio_php/
DEFVAR=EXTENSION_PATH=> c:/wamp/test/scripts/biblio_php/ext/

Il peut etre ecrit en utilisant les references de la facon suivante
DEFVAR=WEB_ROOT=> c:/wamp/test/
DEFVAR=ARTICLE_PATH=> [WEB_ROOT]articles/
DEFVAR=ARCHIVE_PATH=> [WEB_ROOT]archives/
DEFVAR=SCRIPT_PATH=> [WEB_ROOT]scripts/biblio_php/
DEFVAR=EXTENSION_PATH=> [SCRIPT_PATH]ext/
Ainsi en utilisant les references vous perdrez moins de temps lors de la mise en production de votre site. Vous n'aurez qu'un seul DEFVAR e modifier.

Creation d'un site internet en UGML
h3.Cas d'un site UGML via parseur PHP

Nous utiliserons ici les parametres standard de formatage des TAGS, HEADER, EXTENSION, DEFVAR. Pour savoir comment modifier le formatage merci de lire la section configuration avance du parseur UGML.

S'assurer des pre requis
Pre-requis :
Un serveur APACHE (NON TESTE SOUS IIS) avec PHP > 4.0
La derniere version stable du parseur UGML
Les extensions navigation et article
Une doc UGML sous la main
Montez l'arborescence du site
Une fois que vous vous etes assure que vous disposez bien des pre requis mettez en place l'arborescence de votre site.

Par exemple :

ugd/
styles/
scripts/
scripts/php/
scripts/php/ext/
scripts/js/
articles/
include/
media/
media/images/
Creer vos UGD
Pour plus de clarté et de maintenabilité, il est conseillé de séparer les donnees de configuration liées au server du reste des définitions (tags et extensions).

Creer votre fichier de configuration

Fichier de configuration conf.ugd.

DEFVAR=WEB_ROOT=> /usr/local/apache/htdocs/toto.com/
DEFVAR=UGD_PATH=> [WEB_ROOT]ugd/
DEFVAR=ARTICLE_PATH=> [WEB_ROOT]articles/
DEFVAR=EXTENSION_PATH=> [WEB_ROOT]scripts/biblio_php/ext/
Creer votre fichier de definition

Commencez par definir les extensions que vous allez utiliser et terminez par les tags
Fichier toto.com.ugd

DEFEXT=include=> parse_ugml||FAIT APPEL AU PARSEUR LUI MEME
DEFEXT=article=> article|ext_article.php
DEFEXT=menu=> liste_rubrique|ext_navigation.php
DEFEXT=smenu=> liste_article|ext_navigation.php|INUTILE DE REPRECISER L'EXTENSION SAUF POUR LE DEBUGGAGE
DEFTAG=titre=> &lt;h3&gt;|&lt;/h3&gt;
DEFTAG=stitre=> &lt;h4&gt;|&lt;/h4&gt;
DEFTAG=text=> &lt;p&gt;|&lt;/p&gt;
DEFTAG=gras=> &lt;b&gt;|&lt;/b&gt;
DEFTAG=italic=> &lt;i&gt;|&lt;/i&gt;
DEFTAG=image=> &lt;img src='./chemin/relatif/vers/vos/images/|'/&gt;
DEFTAG=item=> |&lt;br/&gt;
Creer les fichiers UGML
Les rubriques de votre site

Les rubriques de votre site constitue le niveau 0 de votre arborescence. Placez les e la racine de votre site web.

Fichier accueil.ugml
[HEADER]|ugd=toto.com.ugd|type=structure|titre=Accueil|nav_ok=ok|ordre=1|[/HEADER]
<include param="start.ugml"/>
<menu param="structure|./"/>
<!-- du html tout plein -->
<article param="texte_accueil.ugml|./articles/">
end.ugml!:parse_file!
Fichier contact.ugml
[HEADER];ugd=toto.com.ugd;type=structure;titre=Contact;navigation=ok;ordre=2;verif=1;[/HEADER]
start.ugml!:parse_file!
structure|./|./rubriqueencours.ugml|!navigation!
<!-- du html tout plein -->
texte_contact.ugml|./articles/!:article!
end.ugml!:parse_file!
Les articles de votre site

Les articles de votre site constitue le contenu reel de votre site, ce que vous y ecrivez donne du sens e votre site web. Mettez les dans le repertoire articles de votre arborescence.

Fichier texte_accueil.ugml
[HEADER];ugd=toto.com.u