Préface

A propos

Cette documentation a été rédigée par Julien Dubuc.

Version : 0.1 appliquée à Lodelscript 0.5 pour Lodel 0.5

Date de création : 05 mai 2003

Date mise à jour : 20 mai 2003

Contributeurs : modifiée par Ghislain Picard pour l'adaptation à la version 0.6.

Version 0.7 : Ghislain Picard, François Lermigeaux, Gautier Poupeau. mars 2004.

Mise à jour : 22 septembre 2004

Prérequis

Pour lire cette documentation, il est nécessaire de connaître assez bien les langages de mise en page sur internet : HTML, XHTML. Des notions de CSS sont aussi importantes. Enfin, pour aller plus loin, il est bon de connaître les rudiments de SQL, mais cela n'est pas nécessaire.

Notations

Quelques conventions de notations sont utilisées dans cette documentation. Les exemples de code sont signalés par un trait à gauche. Un texte en gras avant une portion de code indique la nature du code :

variables : les variables et leurs valeurs utilisées pour l’exemple.

template : le fichier template

résultat : le code HTML généré

Lorsque la syntaxe indiquée pour utiliser une instruction comporte des parties en italique cela signifie que ces parties sont optionnelles.

Principe de fonctionnement

LodelScript est un langage de template qui est composé de balises HTML classiques et de code de plus haut niveau spécifique à LodelScript, comme des variables ou des boucles. Ce langage permet de définir l’aspect graphique d’un site dynamique sans pour autant connaître de langage de programmation et de langage d’interrogation de bases de données comme SQL.

Lodelscript a été développé parallèlement au logiciel Lodel, mais peut très bien être adapté à d'autres systèmes de gestion des données. Cette documentation fera souvent référence à Lodel, si vous utilisez lodelscript dans un autre contexte, il vous faudra adapter quelques exemples.

La syntaxe de LodelScript s’appuie sur un système de balises comparable au XML et a été inspirée par SPIP et d'autres langages de template.

Les balises sont écrites en MAJUSCULES et se distinguent ainsi du code xhtml composé en minuscules :

<p>

<IF COND=''[#AUTEUR]''>

Cet article a été écrit par [#AUTEUR] et publié le [#DATE]

</IF>

</p>

Ce code sera interprété et permettra de générer une page dynamiquement :

<p>Cet article a été écrit par Frédéric Bertrand et publié le 14 juillet 1934.</p>

Techniquement, au premier accès à une page, le fichier template correspondant est compilé, c'est-à-dire transformé en code PHP. Le code compilé est ensuite exécuté puis conservé en cache tant que le fichier de template n’a pas été modifié. Pour les accès suivants à la page, le code compilé sera directement exécuté ou son résultat sera pris dans le cache.

Variables

Quatre types de variables peuvent être distinguées dans le lodelscript :

• Les variables natives ou définies par la modélisation par défaut de la base de données. Ces variables sont les mêmes pour tous les utilisateurs de lodel.

• Les variables définies par le modèle éditorial du site. Elles dépendent donc du modèle éditorial.

• Les variables définies par l'utilisateur dans le système des options du site dans l'interface d'administration de lodel et utilisables dans tous les templates du site

• Les variables dont la valeur est assignée dans le template par la commande LET.

Nota Bene : Les variables sont en général automatiquement remplies par l'interrogation de la base de données, il est donc très rare d'avoir à assigner une valeur à une variable.

La commande LET ne doit donc être utilisée que dans les cas où elle est absolument nécessaire, c'est à dire dans les boucles récurrentes ou pour rendre accessible une valeur dans une boucle qui redéfinit cette variable.

Si vous le souhaitez, pensez à utiliser le système des options de site dans l'interface d'administration de lodel pour donner une valeur fixe à une variable : [#OPTION_SOUSTITRESITE] peut être fixé en créant une entrée soustitresite par le menu des options.

Dans le cadre de l'utilisation normale de Lodel les variables les plus courantes sont automatiquement disponibles dans les maquettes en fonction du contexte. Ainsi, si vous visualisez un document, en y accédant par « document.html?id=12 », alors la variable [#TITRE] donnera le titre du document consulté.

Pour afficher une variable dans un template il faut utiliser la syntaxe suivante :

[#MAVARIABLE]

Les noms de variables ne peuvent contenir que des lettres majuscules, des chiffres ou le caractère ‘_’. Les minuscules, les lettres accentuées, le point (.) et le tiret (-) sont interdits.

Exemple :

variables :

[#TITRE] :

valeur : La migration des cigognes

template :

<html>

<head>

<title>[#TITRE]</title>

</head>

<body>

...

</body>

</html>

résultat :

<html>

<head>

<title>La migration des cigognes </title>

</head>

<body>

...

</body>

</html>

Certaines variables peuvent être disponibles dans la base de données « Lodel » en plusieurs langues, dans ce cas, pour afficher une variable il faut faire suivre le nom de la variable de deux points (:) et de deux lettres représentant la langue désirée suivant la norme ISO 3166-1.

Pour afficher la version française de la variable RESUME : [#RESUME:FR]

Pour afficher la version anglaise de la variable RESUME : [#RESUME:EN]

Deux chaînes de caractères peuvent être spécifiées avec une variable afin de les afficher avant et après une variable seulement si cette variable n’est pas vide.

[avant(#VARIABLE)après]

Cela peut être utilise pour n’afficher des balises entourant une variable que si elle n’est pas vide, comme par exemple :

variables :

#TEXTE :

<p>Les sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone</p>

#AUTEUR :

Paul Verlaine ou vide

template :

[#TEXTE]

[Auteur : <div class="auteur">(#AUTEUR)</div>]

résultat si #AUTEUR non vide :

<p>Les sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone</p>

Auteur : <div class="auteur">Paul Verlaine</div>

résultat si #AUTEUR vide :

<p>Les sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone</p>

Cette syntaxe doit être utilisée seulement lorsque le texte additionnel est court sous peine de rendre le code difficile à lire. Dans le cas contraire, utilisez plutôt la syntaxe des tests avec la commande <IF> ou bien encore les possibilités ouvertes par <ALTERNATIVE>.

Il est également possible d’assigner des valeurs aux variables directement dans le fichier template en utilisant la syntaxe suivante :

<LET VAR="NOMVARIABLE">valeur</LET>

La valeur peut contenir du code HTML et du code LodelScript :

variables :

[#TYPE] :

article

template :

<LET VAR="MESSAGE">

<IF COND="[#TYPE] EQ 'article'">

<em>Article</em>

<ELSE/>

<em>Document</em>

</IF>

</LET>

[#MESSAGE] publié le [#DATEPUBLI].

résultat :

Bonsoir et bienvenue.

Commentaires

Pour insérer des commentaires dans le fichier template, il faut utiliser la syntaxe suivante :

<!--[ Ceci est un commentaire.

Il est possible d’utiliser plusieurs lignes ]-->

Ces commentaires n’apparaissent pas dans la page HTML qui sera générée à partir du fichier template et visible par l'internaute. Si pour une raison ou une autre vous souhaitez que les commentaires soient visibles dans le source du document publié, utilisez les commentaires HTML normaux : <!-- et -->.

Conditions

Syntaxe

L’instruction <IF> permet d’exécuter une partie du template si une certaine condition est remplie.

<IF COND="condition">

code à exécuter si la condition est vraie

<ELSE/>

code à exécuter si la condition est fausse

</IF>

Note : le bloc <ELSE/> est facultatif.

Conditions simples

Les conditions sont composées d’une ou deux variables ou constantes et d’un opérateur.

variable :

[#TYPE] :

document

template :

<IF COND="[#TYPE] EQ ‘document’">

C’est un document.

<ELSE/>

Ce n’est pas un document.

</IF>

résultat :

C’est un document.

Il existe plusieurs opérateurs :

• var1 EQ var2 (=) : Vrai si var1 est égal à var2

• var1 NE var2 (!=) : Vrai si var1 n'est pas égal à var2

• var1 GT var2 (>) : Vrai si var1 est supérieur à var2

• var1 LT var2 (<) : Vrai si var1 est inférieur à var2

• var1 GE var2 (>=) : Vrai si var1 est supérieur ou égal à var2

• var1 LE var2 (<=) : Vrai si var1 est inférieur ou égal à var2

• var1 % var2 : Vrai si var1 n'est pas divisible par var2

• !var1 : Vrai si var1 est vide, égale à zéro ou à faux (inverse donc la condition : vrai devient faux et faux devient vrai).

• var1 Vrai si var1 n’est pas vide ou est différente de zéro

• var1 AND var2 Vrai si var1 et var2 sont vraies (toutes les deux)

• var1 OR var2 Vrai si var1 ou var2 sont vraies (au moins une des deux)

Note : var1 et var2 peuvent être des variables [#VAR] ou bien des constantes sous forme de nombres ou sous forme de chaînes de caractères. Les chaînes de caractères doivent être entourées de guillement simple: 'document'

Exemples

<IF COND="[#STATUT] GT '0'">

Ce document est publié et consultable.

</IF>

<IF COND="[#TITRE]">

Il y a un titre et il n'est pas vide.

</IF>

<IF COND="[#TITRE]">

<h1>[#TITRE]</h1>

<ELSE/>

<h1>Document sans titre</h1>

</IF>

<IF COND="![#TITRE]">

<h1>Document sans titre</h1>

</IF>

<IF COND="[#COUNT] % 2">

La variable est paire.

<ELSE/>

La variable est impaire.

</IF>

Conditions complexes

Il est possible de combiner plusieurs opérateurs afin d’obtenir des conditions plus évoluées. Il est conseillé de mettre entre parenthèses chaque condition simple afin d’éviter les problèmes de priorité des opérateurs et de gagner en lisibilité.

<IF COND="([#TYPE] EQ ‘article’) OR ([#TYPE] EQ ‘compte-rendu’)">

Ce document est un article ou un compte-rendu.

</IF>

<IF COND="(([#COUNT] GT 0) AND ([#COUNT] LE 10)) OR ([#MAX] GT 15)">

La variable COUNT est comprise entre 0 et 10 ou bien la variable MAX est supérieure à 15.

</IF>

Boucles

Les boucles permettent d’exécuter plusieurs fois une opération avec des variables dont les valeurs peuvent changer à chaque passage. Les valeurs de ces variables peuvent être extraites de la base de données directement (cas des boucles base de données) ou bien générées par une fonction PHP prédéfinie par un développeur (cas des boucles prédéfinies).

Ces variables sont locales à la boucle, c'est-à-dire qu’elles ne sont pas accessibles en dehors de la boucle et masquent les variables de même nom qui auraient été définies avant la boucle.

Boucles base de données

Quelques exemples : pour les familiers de SQL

Les boucles base de données permettent d’extraire les données directement de la base de données et s’utilisent comme le montrent les exemples suivants. Ces exemples sont repris et commentés dans la section suivante.

Une boucle montrant tous les documents présents dans la base.

<LOOP NAME="tous_les_documents" TABLE=”documents”>

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

</LOOP>

Une boucle montrant tous les documents présents dans la base ET publiés.

<LOOP NAME="tous_les_documents_publiés" TABLE=”documents” WHERE=”statut GT '0'>

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

</LOOP>

Ou bien si on ne veut que les documents publiés ET du type 'article' :

<LOOP NAME="tous_les_articles_publiés" TABLE=”documents” WHERE=”statut GT '0' WHERE=”type EQ 'article'”>

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

</LOOP>

Si on souhaite, de plus, les classer par date descendante (DESC) :

<LOOP NAME="tous_les_articles_publiés_par_date" TABLE=”documents” WHERE=”statut GT '0' WHERE=”type EQ 'article'” ORDER=”datepubli DESC”>

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

</LOOP>

Si on souhaite afficher les 10 derniers articles publiés, classés par date descendante :

<LOOP NAME="10_derniers_articles_publiés_par_date" TABLE=”documents” WHERE=”statut GT '0' WHERE=”type EQ 'article'” ORDER=”datepubli DESC” LIMIT=”0,10”>

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

</LOOP>

Syntaxe normale : LOOP, TABLE, WHERE, ORDER, LIMIT

Le corps de la boucle est compris entre les balises <DO> et </DO>, c'est cette partie qui sera affichée à chaque passage de la boucle.

L’attribut NAME est obligatoire et unique, c'est-à-dire dans un même fichier template deux boucles ne peuvent pas avoir le même nom (attention, si deux boucles ont le même nom, dans deux fichiers différents, mais inclus dans le même template, alors il y aura une erreur). Pensez à donner un nom explicite à cet attribut, il permettra de bien indiquer à quoi sert cette boucle et quelle est sa fonction.

L’attribut TABLE permet de définir de quelles tables doivent être extraites les données. A-priori, le développeur de template pour lodel utilisent quatre tables qui correspond aux 4 entités prédéfinies par lodel :

• La table “documents” qui contient les informations sur les documents ;

• La table “publications” qui contient les informations sur les publications ;

• La table “entrees” qui contient les informations sur les index ;

• la table “personnes” qui contient les informations sur les index de personnes.

Si la requête fait appel à plusieurs tables, il faut répéter autant de fois que nécessaire cette attribut. Il faut au moins définir une table.

Une boucle montrant tous les documents présents dans la base.

<LOOP NAME="tous_les_documents" TABLE=”documents”>

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

</LOOP>

La partie comprise entre <DO> et </DO> va s'afficher à chaque fois que la boucle rencontrera un document dans la base de données Lodel. S'il y en a 43, elle affichera 43 fois quelque chose comme :

<br />- Le titre de l'article, publié le 03/12/2003.

L’attribut WHERE permet de spécifier les critères que devront remplir les informations pour être extraites. Si plusieurs attributs WHERE sont spécifiés, les enregistrements seront retenus s’ils remplissent toutes les conditions.

Si l'on veut les documents publiés (c'est à dire statut supérieur à zéro) ET du type 'article' :

<LOOP NAME="tous_les_articles_publiés" TABLE=”documents” WHERE=”statut GT '0' WHERE=”type EQ 'article'”>

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

L’attribut ORDER est optionnel et permet de définir dans quel ordre seront affichées les informations.

Cet attribut doit comprendre un nom de champ suivi d’une instruction facultative permettant de choisir si le tri aura lieu dans l’ordre ascendant ou descendant. Par défaut le tri est ASC, c'est à dire ascendant (de A à Z ou du plus ancien au plus récent, du plus petit au plus grand).

• ORDER="nom ASC" : tri suivant le champ nom de A à Z ;

• ORDER="nom": équivalent à la ligne ci-dessus ;

• ORDER="nom DESC": tri suivant le champ nom de Z à A ;

• ORDER="nom" ORDER="prenom" : tri suivant le champ nom de A à Z, si deux noms sont identiques, alors le champ prenom sera utilisé pour les trier.

On peut ainsi trier des documents par ordre alphabétique à partir de leur titre :

<LOOP NAME="tous_les_articles_publiés" TABLE=”documents” WHERE=”statut GT '0' WHERE=”type EQ 'article'” ORDER=”titre”>

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

Si vous voulez que les résultats s'affichent dans l'ordre défini dans l'interface d'édition, vous devez préciser ORDER="ordre". Dans le cas de plusieurs attributs ORDER, le tri s’effectuera dans l’ordre naturel : d'abord la première condition de tri, puis la seconde, ainsi de suite.

Voici des articles publiés et triés par date de publication (descendante) et ensuite par titre.

<LOOP NAME="tous_les_articles_publiés" TABLE=”documents” WHERE=”statut GT '0' WHERE=”type EQ 'article'” ORDER=”datepubli DESC” ORDER=”titre” >

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

L’attribut LIMIT est optionnel et peut être utilisé pour limiter le nombre d’enregistrements retournés ou indiquer un décalage. Cet attribut doit être égal à une valeur numérique (limite du nombre d’enregistrements) ou deux valeurs numériques séparées par une virgule (décalage, limite du nombre d’enregistrements).

• LIMIT="x" : retourne les x premiers enregistrements ;

• LIMIT="1" : retourne le premier enregistrement ;

• LIMIT="x,y" : retourne les enregistrements du (x+1)ième au (x+y)ième, en effet, le premier enregistrement n'est pas le numéro 1, mais 0 ;

• LIMIT="0,y" : équivalent à LIMIT="y", de 0 à y ;

• LIMIT="x,-1" : retourne les enregistrements du (x+1)ième au dernier ;

Note : le décalage du premier enregistrement est 0 (pas 1) ce qui explique le x+1.

Si on souhaite afficher les 10 derniers articles publiés, classés par date descendante :

<LOOP NAME="10_derniers_articles_publiés_par_date" TABLE=”documents” WHERE=”statut GT '0' WHERE=”type EQ 'article'” ORDER=”datepubli DESC” LIMIT=”0,10”>

<DO>

<br />- [#TITRE], publié le [#DATEPUBLI].

</DO>

</LOOP>

Les boucles sont donc très utiles pour afficher des informations sous forme de listes, voici par exemple une liste de liens pointant vers des pages décrivant des auteurs (en considérant que la table auteur contient les champs id, nom et prénom) :

template :

<h1>Liste des auteurs</h1>

<LOOP NAME="liste_auteur" TABLE="auteur" ORDER="nom" ORDER="prenom">

<DO>

<a href="affiche_auteur.php?id=[#ID]">[#PRENOM] [#NOM]</a><br />

</DO>

</LOOP>

résultat :

<h1>Liste des auteurs</h1>

<a href="affiche_auteur.php?id=7">Antoine de Saint Exupery</a><br />

<a href="affiche_auteur.php?id=5">Paul Verlaine</a><br />

<a href="affiche_auteur.php?id=4">Jules Verne</a><br />

Si vous souhaitez savoir combien de résultats vous allez afficher : les boucles sur base de données définissent systématiquement les deux variables suivantes:

• [#COUNT] qui donne le numero de l'enregistrement ;

• [#NBRESULTATS] qui donne le nombre d'enregistrement que la boucle va exécuter.

Vous devez consulter la section consacrée au possibilités d'affichage avancées, avec DOFIRST pour pouvoir bien utiliser ces variables.

Commandes avancées : GROUPBY, SELECT

Les commandes suivantes sont beaucoup moins utilisées dans le cadre de l'utilisation simple de Lodel.

La commande GROUPBY et la commande SELECT permettent d'utiliser des fonctions d'agrégation pour compter ou pour chercher le maximum, le minimum, la moyenne, la somme etc d'un groupe d'enregistrements.

GROUPBY forme un « agrégat », c'est à dire qu'il va écraser un ensemble de données, en général une suite de ligne en éliminant certains doublons.

Ainsi, si nous avons les enregistrements suivants :

Auteur	Titre	Date de pulication
Robert Louis	L'utilisation des parachutes	12/04/02
Andrée Louise	La théorie du complot	14/02/03
Robert Louis	La chute libre	29/07/01

Et si nous appelons ces données par la commande :

<LOOP NAME=''un_article_par_auteur'' TABLE=''documents'' GROUPBY=''auteur''>

L'instruction GROUPBY va identifier qu'il y a 2 enregistrements ayant le même auteur et va les regrouper pour n'en garder qu'un seul :

Auteur	Titre	Date de pulication
Robert Louis	L'utilisation des parachutes	12/04/02
Andrée Louise	La théorie du complot	14/02/03

SELECT permet de faire des boucles qui contiennent des instructions spécifiques du langage SQL, en particulier les fonctions natives de MySQL, comme count() qui retourne non les résultats, mais le nombre de résultats.

Pour savoir combien de documents publiés sont publiés, on peut écrire :

<LOOP NAME="count_documents" TABLE="documents" SELECT="count(*) as total" WHERE= »statut GT '0'>

<DO>

<p>Il y a actuellement [#TOTAL] documents publiés.</p>

</DO>

</LOOP>

SELECT="count(*) as nb" permet ici de ne pas sélectionner toutes les données des documents, mais de ne donner que leur nombre. La précision « as total » signifie que ce nombre sera attribué à la variable [#TOTAL] que nous utiliserons ensuite dans lodelscript.

Cet exemple fonctionne, mais cependant, il faut savoir que :

Les boucles sur base de données définissent systématiquement les deux variables suivantes:

• [#COUNT] qui donne le numero de l'enregistrement ;

• [#NBRESULTATS] qui donne le nombre d'enregistrement que la boucle va exécuter.

Les attributs DONTSELECT et SELECT permettent de sélectionner ou de-sélectionner les champs transferés de la base de donnée. Avec DONTSELECT on peut donc ne PAS demander certaines données, avec SELECT on précise la liste des données que l'on souhaite avoir.

<LOOP NAME=''juste_titre_date'' TABLE=''documents'' SELECT=''titre,datepubli''>

SELECT=''titre,datepubli'' nous permettra d'afficher les valeurs de [#TITRE] et de [#DATEPUBLI], mais le texte des documents ne sera pas donné, la variable [#TEXTE] serait donc vide.

Les deux cas les plus fréquents pour utiliser SELECT et DONTSELECT sont :

Eviter de faire appel à des variables que vous utilisiez déjà avant une boucle. Par exemple, si la variable [#ID] est définie dans votre page et qu'une boucle pourrait la redéfinir malencontreusement et l'écraser, vous pouvez éviter cela avec : DONTSELECT=''id''.

Optimiser les transferts de la base de donnée. Cependant, des essais ont montré que même le transfert de texte long ne change en rien le temps de création d'une page. Ces commandes ne doivent être utilisées qu'en cas de besoin réel.

La commande SELECT combiné à la commande SQL « as » permet aussi de définir un nouveau nom à une variable ce qui peut être utile, si on veut réutiliser une variable dans le cas de boucles imbriqués

<LOOP NAME=''select_as'' TABLE=''documents'' SELECT=''id as iddocument''>

<DO>

[#IDDOCUMENT

</DO>

</LOOP>

Combinaisons (AND, OR)

Les critères spécifiés grâce à l’attribut WHERE peuvent être très fins grâce à des opérateurs et des fonctions, nous vous recommandons de lire un documents traitant de la commande WHERE. Par exemple sur le site de MySQL : http://www.mysql.com/

Quelques exemples de WHERE avec des opérateurs d'addition :

<LOOP NAME="maboucle" TABLE="documents" ORDER="datepubli DESC" WHERE="parent ne 'actualités' AND parent ne 'annuaire' WHERE="statut gt 0" LIMIT="0,9">

Cette boucle va sélectionner les 10 derniers documents publiés (ordonnés par date, limités à 10 et statut GT '0') qui ne sont contenus ni dans la rubrique 'actualites', ni dans la rubrique 'annuaire'. Grace à AND, vous pouvez donc combiner des conditions.

OR permet de grouper des conditions avec une alternative ou une conditions ou une autre :

<LOOP NAME="maboucle" TABLE="documents" ORDER="datepubli DESC" WHERE="parent ne 'actualités' OR parent ne 'annuaire' WHERE="statut gt 0" LIMIT="0,10">

On obtient dans ce cas, les documents qui appartiennent soit à la rubrique actualités, soit à la rubrique annuaire.

On peut regrouper les conditions dans des parenthèses.

Quelques pointeurs pour aller plus loin sur les fonctions :

(NOT) LIKE, SUBSTRING

http://dev.nexen.net/docs/mysql/annotee/string-functions.php

(NOT) IN, (NOT) BETWEEN

http://dev.nexen.net/docs/mysql/annotee/comparison-operators.php

AND, OR

http://dev.nexen.net/docs/mysql/annotee/logical-operators.php

Possibilités d'affichage évoluées dans les boucles

Il est possible de définir dans une boucle du code à exécuter suivant certains cas, comme par exemple pour le premier enregistrement ou lorsqu’il n’y a pas de résultats retournés. Pour pouvoir utiliser ces fonctionnalités, la boucle doit être définie avec des balises supplémentaires comme ci-dessous :

<LOOP NAME="ma_boucle" TABLE="table1" TABLE="table2" WHERE="critere1" ORDER="ordre1">

<BEFORE>

code exécuté avant l’affichage des enregistrements

</BEFORE>

<DOFIRST>

code exécuté pour le premier enregistrement et seulement pour lui

</DOFIRST>

<DO>

code exécuté pour tout les autres enregistrements(sauf le premier si DOFIRST est défini et sauf le dernier si DOLAST est défini)

</DO>

<DOLAST>

code exécuté pour le premier enregistrement (sauf si c’est aussi le premier)

</DOLAST>

<AFTER>

code exécuté après l’affichage des enregistrements

</AFTER>

<ALTERNATIVE>

code exécuté si aucun enregistrement n’est trouvé

</ALTERNATIVE>

</LOOP>

Note : ces balises supplémentaires peuvent être utilisées indépendamment les unes des autres.

Alternative

La balise <ALTERNATIVE> permet de spécifier le code qui sera exécuté s’il n’y aucun enregistrement trouvé. Cette balise ne fonctionne que pour les boucles sur les bases de données (c'est à dire ne fonctionne pas pour les boucles de type prédéfini).

Exemple, en considérant que la table document ne contient pas d'article :

template :

<h1>Liste des articles</h1>

<LOOP NAME="liste_articles" TABLE="document" WHERE="type=’article’ ORDER="titre">

<DO>

<a href="affiche_article.php?id=[#ID]">[#TITRE]</a><br />

</DO>

<ALTERNATIVE>

Aucun article trouvé.

</ALTERNATIVE>

</LOOP>

résultat :

<h1>Liste des articles</h1>

Aucun article trouvé.

Dofirst & Dolast

Permettent de spécifier un code particulier pour les premier et dernier enregistrements. Ces balises ne fonctionnent que pour les boucles base de données (c'est à dire ne fonctionne pas pour les boucles de type prédéfini).

Exemple :

template :

<p>Document écrit par :

<LOOP NAME="liste_auteur" TABLE="auteur" ORDER="nom" ORDER="prenom">

<DOFIRST>

[#PRENOM] [#NOM]

</DOFIRST>

<DO>

, [#PRENOM] [#NOM]

</DO>

<DOLAST>

et [#PRENOM] [#NOM].

</DOLAST>

</LOOP>

</p>

résultat :

<p>Document écrit par : Ghislain Picard, François Lermigeaux et Gautier Poupeau.</p>

BEFORE & AFTER

Permettent de spécifier du code qui sera exécuté avant le premier enregistrement ou après le dernier enregistrement. Ces balises fonctionnent avec les boucles de base de donnée et les boucles prédéfinies uniquement si le code de la fonction PHP le prévoit ce qui est généralement le cas.

Une utilisation fréquente est la création d’un tableau avec des lignes de titre uniquement s'il y a des résultats à afficher :

Exemple :

template :

<LOOP NAME="liste_auteur" TABLE="auteur" ORDER="nom" ORDER="prenom">

<BEFORE>

<table>

<th>

<td>Prénom</td>

<td>Nom</td>

</th>

</BEFORE>

<DO>

<tr>

<td>[#PRENOM]</td>

<td>[#NOM]</td>

</tr>

</DO>

<AFTER>

</table>

</AFTER>

<ALTERNATIVE>

Aucun auteur trouvé.

</ALTERNATIVE>

</LOOP>

résultat s’il y a des enregistrements :

<table>

<th>

<td>Prénom</td>

<td>Nom</td>

</th>

<tr>

<td>Antoine</td>

<td>de Saint Exupery</td>

</tr>

<tr>

<td>Paul</td>

<td>Verlaine</td>

</tr>

<tr>

<td>Jules</td>

<td>Verne</td>

</tr>

</table>

résultat s’il n’y a pas d’enregistrements :

Aucun auteur trouvé.

Boucles prédéfinies

Pour effectuer une boucle prédéfinie il faut utiliser la syntaxe suivante :

<LOOP NAME="nom_fonction">

<DO>

code de la boucle

</DO>

</LOOP>

Cette boucle va appeler la fonction PHP prédéfinie correspondant au nom « nom_fonction ». Cette fonction va remplir certaines variables qui seront accessibles dans le code de la boucle.

Ces boucles sont codées en PHP et dépendent donc du contexte dans lequel vous utilisez lodelscript. Lodel comporte certaines boucles prédéfinies, sur lesquelles nous allons nous appuyer, mais vous pouvez très bien en coder de nouvelles. Voir le fichier boucles.php dans les sources de Lodel pour ajouter des boucles personnalisées.

La boucle TOC

Cette fonction permet de générer la table des matières d’un document, celui-ci doit avoir été convenablement stylé dans votre traitement de texte avec l'utilisation des styles titre1, 2, 3 etc.

Pour appeler cette fonction, vous devrez ajouter dans votre template cette boucle :

<LOOP NAME="toc" TEXT=”texte”>

<IF COND="[#NIVEAU]==1">

<a href="#tocto[#TOCID]"NAME="tocfrom[#TOCID]">

[#TITRE]

</a>

</IF>

</LOOP>

Cette boucle permet d’afficher tous les titres de premier niveau contenu dans le texte de votre document, si vous voulez aussi ajouter les titres de second niveau, vous devrez ajouter à l’intérieur de votre boucle :

<IF COND="[#NIVEAU] EQ '2' "></IF>

et ainsi de suite pour les autres niveaux.

L’attribut TEXT à l’intérieur du <LOOP> permet de déterminer quelle partie de votre document la TOC doit prendre en compte. Si vous voulez prendre en compte le texte et les annexes, vous noterez TEXT= "texte, annexe” et juste les annexes TEXT="annexe” … etc.

Si vous voulez que chaque titre à l’intérieur de votre texte soit un lien qui renvoie à la table des matières, vous devrez rajouter la fonction filtre (pipe) 'tocable' à la variable [#TEXTE] :

[(#TEXTE|tocable)]

Voir la section consacrée aux filtres pour cela.

Les liens PREVIOUS / NEXT

Les boucles PREVIOUS et NEXT permettent de faire dynamiquement des liens d'une entité vers les entités suivantes et précédentes.

On les appelle avec ID correspondant à l'ID du document ou de la publication en cours.

Exemples :

<LOOP NAME="previous" ID="[#ID]">

<LOOP NAME="next" ID="[#ID]">

THROUGH est facultatif. Il permet de traverser un niveau de publication (dont le/les types sont donnés par THROUGH). Cela est très utile, en particulier si vous souhaitez que les liens « traversent » des regroupements, des rubriques ou des numéros.

<LOOP NAME="previous" ID="[#ID]" THROUGH="rubrique">

<DO>

<a href=''document.html?id=[#ID]''>Suivant</a>

</DO>

</LOOP>

Il est possible de spécifier plusieurs types :

<LOOP NAME="previous" ID="[#ID]" THROUGH="rubrique,numero">

Attention, ce système ne permet pas en l'état de traverser deux niveaux, donc l'exemple suivant pourra donner des comportements surprenants en passant ou non certains regroupements :

<LOOP NAME="previous" ID="[#ID]" THROUGH="regroupement,rubrique,numero">

Utilisez donc plutôt THROUGH="regroupement" pour passer d'un document à un autre, mais si possible sans aller d'une publication à une autre.

La boucle exporte toutes les variables de la table entités : [#ID], [#IDPARENT], [#STATUT]... ainsi que le nom du type de l'entité : [#TYPE].

Les listes suivants / précédents

Dans une boucle, quelle qu’elle soit, il est très facile de construire des liens « suivants » et « précédents » pour naviguer dans des listes de résultats, par exemple de 10 en 10.

Pour déclencher ce comportement, il suffit d’indiquer dans l’attribut LIMIT un nombre représentant la quantité d’éléments souhaités, lodel fabrique alors le nombre de pages nécessaire et propose des liens sous la forme des variables [#NEXTURL] et [#PREVIOUSURL].

Voici un exemple qui liste les titres de tous les documents, de 20 en 20 en les classant par date de publication.

<LOOP NAME="touslesdocuments" TABLE="documents" ORDER="datepubli DESC" LIMIT="20">

<DO>

<li>[#TITRE]</li>

</DO>

<AFTER>

<IF COND="[#NEXTURL]"><a href="[#NEXTURL]">Suivants</a></IF>

<IF COND="[#PREVIOUSURL]"><a href="[#PREVIOUSURL]">Précédents</a></IF>

</AFTER>

</LOOP>

Les variables [#NEXTURL] et [#PREVOUSURL] pointent directement vers la bonne page. Les tests ci-dessus permettent de n'afficher les liens que s'ils restent des résultats.

La boucle EXTRAIT_IMAGES

Cette boucle va chercher à l'intérieur d'un document les images qui y sont contenues pour les rendre disponibles. Vous pouvez alors afficher une image tirée d'un document sans pour autant l'afficher complètement.

<LOOP NAME="EXTRAIT_IMAGES" TEXT="[#TEXTE]">

[#IMAGE]

</LOOP>

Cet boucle va alors afficher toutes les images. Si on souhaite limiter, il faut utiliser la commande LIMIT, comme suit pour la première image :

<LOOP NAME="EXTRAIT_IMAGES" TEXT="[#TEXTE]" LIMIT=''0,1''>

[#IMAGE]

</LOOP>

La variable [#IMAGE] contient tout le tag HTML : <img src=''chemin/vers/image.gif''>, si on ne souhaite que le chemin pour personnaliser le tag <img>, il faut écrire [#SRC] :

<LOOP NAME="EXTRAIT_IMAGES" TEXT="[#TEXTE]" LIMIT=''1''>

<img src=''[#SRC]'' alt=''mon image''>

</LOOP>

Variables disponibles : "src","alt","border","style","class","name".

La boucle PARAGRAPHES

Elle permet de parcourir les paragraphes d'un texte les uns après les autres.

Elle demande un argument TEXT, qui sera le texte parcouru par la boucle. Les paragraphes sont affichables les un après les autres par la variable [#PARAGRAPHE] et une variable [#COMPTEUR] est incrémentée automatiquement.

<LOOP NAME="PARAGRAPHES" TEXT="[#TEXTE]">

<p>Paragraphe numéro [#COMPTEUR] : [#PARAGRAPHE]</p>

</LOOP>

La boucle RSS

Elle permet à Lodel de lire un flux RSS, c'est à dire un fil de syndication, proposé par un autre site que le vôtre. Il suffit de la mettre en place dans vos templates pour que vous puissez afficher des informations proposées par d'autres sites.

La boucle générale s'appelle avec le nom rss, elle correspond à l'ensemble du fil RSS, avec les variables générales du fil. Ensuite, chaque article du fil est accessible par la boucle "rssitem".

<LOOP NAME="rss" URL="[#URL]" REFRESH="600">

<h2>[#TITLE]</h2>

<ul>

<LOOP NAME="rssitem" LIMIT="0,10">

<li><a href="[#LINK]">[#TITLE]</a>

<IF COND="[#AUTHOR]">par [#AUTHOR]</IF>

<IF COND="[#CATEGORY]"> dans [#CATEGORY]</IF>

<br/>[#DESCRIPTION]

</li>

</LOOP>

</ul>

</LOOP>

Modification des variables : fonctions filtres ou pipe

Il est possible d’appliquer des fonctions aux variables pour les modifier au moment de l'affichage. Cela est particulièrement utile pour conserver des informations dans la base de données tout en les adaptant à votre mise en page : mise en majuscules, raccourcir un texte long, enlever des mises en forme, etc.

Pour appliquer une fonction à une variable, il faut faire suivre la variable du caractère | ("pipe" en anglais) puis du nom de la fonction et de mettre le tout entre parenthèses.

[(#VARIABLE|fonction)]

Certaines fonctions peuvent accepter des paramètres qui sont passés entre parenthèses après le nom de la fonction.

[(#VARIABLE|fonction(param1, param2)]

wiki

Si vous souhaitez permettre à vos utilisateurs d’utiliser la syntaxe wiki dans leurs formulaires vous disposer du filtre |wiki.

Données entrées dans la variable [#NOTES]:

Voici mes mots en ''italiques'' et aussi en __gras__.

template :

<p>[(#NOTES|wiki)] </p>

résultat :

<p> Voici mes mots en italiques et aussi en gras.</p>

Lodel utilise la classe php "wiki renderer" de Laurent Jouanneau, vous pouvez vous reporter à l'url suivante pour en connaître la syntaxe précise :

http://ljouanneau.com/softs/wikirenderer/documentation.php

tocss

Le filtre 'tocss' (lire "to css") effectue les nettoyages et les transformations pour traduire les styles importés par le traitement de texte en balises HTML.

Elle donne alors des classes du type :

class="nom_du_style">texte du div.</div>

Cette fonction est importante et doit être appliquée à tous les champs qui comportent plus d'un paragraphe importés par l'intermédiaire du servOO (OpenOffice et Writer2LateX).

Par défaut, les niveaux de titre sont codés <div class="sectionx"> où x est le niveau du titre. En ajoutant le paramètre heading : [(#VAR|tocss('heading'))] au filtre tocss, les niveaux de titre sont codés <hx> comme recommandé en XHTML.

pluriel

Affiche un s si la valeur de la variable est supérieure et permet de mettre au pluriel des mots. Cependant, les pluriels irréguliers (cheval/chevaux par exemple) ne sont pas supportés et devront être géré par un condition du type <IF>.

variables :

#NB_ARTICLE : 4

#NB_REVUE : 1

template :

<p>[#NB_ARTICLE] article[(#NB_ARTICLE|pluriel)] trouvé[(#NB_ARTICLE|pluriel)] et [#NB_REVUE] revue[(#NB_REVUE|pluriel)] trouvée[(#NB_REVUE|pluriel)].</p>

résultat :

<p>4 articles trouvés et 1 revue trouvée.</p>

Lettrines

Permet d’extraire la première lettre d’un texte contenu dans une variable avant de l’afficher avec un style particulier.

variables :

#TEXTE :

<p>Les sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone</p>

template :

[(#TEXTE|lettrine)]

résultat :

<p><span class="lettrine">L</span>es sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone</p>

multiline

Permet de passer à la ligne tout les x caractères sans couper les mots sauf si un mot fait plus de x caractères. Le nombre de caractères par lignes doit être passé en variable. Cette fonction est très utile pour les balises <textarea> afin d’éviter d’avoir un ascenseur horizontal.

Note : le comportement par défaut des navigateurs ne nécessite plus l’utilisation de cette fonction.

variables :

#TEXT :

Les sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone

template :

<form>

<textarea cols="20" rows="10">[(#TEXT|multiline(20))]</textarea>

</form>

résultat :

<form>

<textarea>Les sanglots longs

des violons de

l'automne, blessent

mon coeur d'une

langueur monotone

</textarea>

</form>

nbsp

Cette fonction renvoie un espace insécable si la variable est vide. Cela permet d'éviter les cases vides dans les tables.

Si par exemple on a un titre, mais parfois pas de sous-titre dans un tableau, on peut remplir les cases vides par des '&nbsp;'

template :

<LOOP NAME=''nbsp'' TABLE=''documents'' WHERE=''type EQ 'article'''>

<tr><td>[#TITRE]</td><td>[#SOUSTITRE]</td></tr>

</LOOP>

résultat :

<tr><td>Rapport général</td><td>pour l'année 2002</td></tr>

<tr><td>Comptes</td><td>&nbsp;</td></tr>

<tr><td>Bilan annuel</td><td>de l'association lodel</td></tr>

strtoupper, strtolower

Passe toutes les lettres de la variable en majuscules et minuscules respectivement.

variables :

#TEXTE :

C’est la rentrée, les élèves sont en classe.

template :

Le texte brut : [#TEXTE]<br />

Le texte modifié : [(#TEXTE|majuscules)]<br />

résultat :

Le texte brut : C’est la rentrée, les élèves sont en classe.<br />

Le texte modifié : C'EST LA RENTRÉE, LES ÉLÈVES SONT EN CLASSE.<br />

textebrut

Cette fonction transforme la variable en supprimant toutes les balises HTML et en remplaçant les espaces insécables, les tabulations et les retours à la ligne par des espaces.

variables :

#TEXTE :

<p>Les sanglots longs des violons de l'<strong>automne</strong>,\nblessent mon coeur d'une langueur monotone</p><p>Paul&nbsp;Verlaine</p>

template :

Le texte : [#TEXTE]<br />

Le texte modifié : [(#TEXTE|textebrut)]<br />

résultat :

Le texte brut : <p>Les sanglots longs des violons de l'<strong>automne</strong>,

blessent mon coeur d'une langueur monotone</p><p>Paul&nbsp;Verlaine</p><br />

Le texte modifié : Les sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone Paul Verlaine<br />

Ce filtre est utile pour le <TITLE> d'une page HTML par exemple. Attention toutefois avec les écritures non latines, l'affichage du titre dans la barre d'état du logiciel peut être incorrecte dans les navigateurs actuels.

couper

Affiche les n premiers caractères d’une variable et ajoute la chaîne « (…) » à la fin de l’extrait. Le nombre de caractères est passé à la fonction. Cette fonction est utile pour afficher le début d’un article sur une page d’accueil par exemple.

Cette fonction gère automatiquement les balises HTML qui se trouveraient dans votre texte. Ainsi, si une balise s'ouvrait avant la coupure, elle sera automatiquement refermée. Cela évite de laisser une balise <em> ouverte qui s'appliquerait à tout le reste de votre page.

variables :

#TEXTE :

Les sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone

template :

Le texte : [#TEXTE]<br />

Le texte modifié : [(#TEXTE|couper(40))<br />

résultat :

Le texte brut : Les sanglots longs des violons de l'automne,

blessent mon coeur d'une langueur monotone<br />

Le texte modifié : Les sanglots longs des violons de (...)<br />

couperpara

Cette fonction permet de n’afficher que les n premiers paragraphes d’une variable.

variables

#TEXTE :

<p>Premier paragraphe</p>

<p>Deuxième paragraphe</p>

<p>Dernier paragraphe</p>

template :

Le texte brut : <br />

[#TEXTE]

Le texte modifié : <br />

[(#TEXTE|couperpara(2))]

résultat :

Le texte brut :

<p>Premier paragraphe</p>

<p>Deuxième paragraphe</p>

<p>Dernier paragraphe</p>

Le texte modifié :

<p>Premier paragraphe</p>

<p>Deuxième paragraphe</p>

humandate

Permet d’afficher une date dans un format du type 01 janvier 2003. Si l’année est supérieure à 9000, la fonction renvoie « jamais » et si l’année est nulle la fonction n’affiche rien.

variables

#DATE :

1981-07-31

template :

Le texte a été écrit le [(#DATE|humandate)].

résultat :

Le texte a été écrit le 31 juillet 1981.

formateddate, formatedtime

Les fonctions formattedate et formatedtime permettent de formater respectivement une date ou un « timestamp ». Le format de sortie est à préciser ainsi :

 [(#DATEPUBLI|formateddate("%A %d %B %Y"))]

Donnera « Mercredi 31 mars 2004 », en effet '%A' signifie « jour de la semaine », '%d' numéro du mois et ainsi de suite. Référence complète des codes de formatage :

http://fr2.php.net/manual/fr/function.strftime.php

tocable

Permet de rendre rétrocliquable les titres. S'utilise avec la boucle prédéfinies TOC (voir supra).

vignette

Cette fonction permet d’afficher la miniature d’une image dont l’url est contenue dans la variable. L’url de l’image est remplacée par celle de la miniature. La largeur de la vignette doit être passée en paramètre de la fonction.

Si l’image miniature n’existe pas, elle sera créée et stockée automatiquement. L’url peut être absolue ou relative.

variables :

#IMG :

http://www.revues.org/commun/logos/300X61.jpg

template :

L’image normale: <img src="[#SRC]" /><br />

La vignette de largeur 100 pixels : <img src="[(#SRC|vignette(100))" /><br />

résultat :

L’image normale: <img src="http://www.revues.org/commun/logos/300X61.jpg" /><br />

La vignette de largeur 100 pixels : <img src="http://www.revues.org/commun/logos/300X61-small100.jpg" /><br />

Note : cette fonction nécessite l’installation de la librairie GD 2.0.1 et du module GD de php. Ce module est courant chez la majorité des hébergeurs. Au besoin vous pouvez le vérifier en utilisant la fonction phpinfo() sur une de vos pages.

sizeattributs

Cette fonction permet d’afficher la largeur et la hauteur d’une image telles qu’elles peuvent apparaître dans une balise <img>. Ces informations aident les navigateurs à afficher plus rapidement vos pages.

variables :

#IMG :

http://www.revues.org/commun/logos/300X61.jpg

template :

L’image : <img src="[#IMG]" [(#IMG|sizeattributs)] /><br />

résultat :

L’image : <img src="http://www.revues.org/commun/logos/300X61.jpg" width="300" height="61" /><br />

removefootnotes, removeennotes et removenotes

Supprime les renvois vers les notes de bas de page, les fins de notes et toutes les notes respectivement.

isadate

Cette fonction renvoie vraie si la variable n’est pas une date vide. On l'utilise donc dans des tests :

<IF COND=''[(#DATEPUBLI|isadate)]''>c'est bien une date !<ELSE>Ce n'est pas une date…</IF>

replacequotationmark

Permet de remplacer les guillemets contenus dans la variable par l’entité html correspondante (&quot;)

variables :

#TEXTE :

"Les sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone"

template :

Le texte : [#TEXTE]<br />

Le texte modifié : [(#TEXTE|replacequotationmark)<br />

résultat :

Le texte brut : "Les sanglots longs des violons de l'automne,

blessent mon coeur d'une langueur monotone"<br />

Le texte modifié : &quot;Les sanglots longs des violons de l'automne,

blessent mon coeur d'une langueur monotone&quot;<br />

Filtres pour les champs multi-langues

[(#resume|multilingue("fr"))] est équivalent à [#RESUME:FR].

Ce filtre peut néanmoins être intéressant dans le cas de filtrages automatisés.

[#RESUME|humanlang] : revoie la langue de la variable sous sa forme lisible « français » et non fr par exemple.

true

Cette fonction affiche les chaînes avant et après la variable uniquement si celle-ci a la valeur true ou n’est pas vide. Cela permet d’éviter d’utiliser une instruction <IF>.

template :

[(#TITRE|true)<p>Le document a bien un titre</p>)]

résultat :

<p>Le document a bien un titre</p>

L'utilisation de cette fonction n'est pas recommandée pour des raisons de lisibilité.

false

Identique à true sauf que l’affichage est réalisé si la variable a la valeur false ou est vide.

Voir true. L'utilisation de cette fonction n'est pas recommandée.

Fonctions diverses (réservées à l'interface de lodel)

• Voici la liste de fonctions existantes, mais conçues pour l'interface de Lodel.

• function yes : renvoie "checked" si vrai

• function no : renvoie "checked" si faux

• - function eq(str) : renvoie "checked" si égale à 'str'

• function notes(type) : fonction pour sélectionner dans les footnotes ou les endnotes un seul type de notes : type=nombre, lettre ou astérisque.

• function isrelative : permet de savoir si un lien est relatif

• function isabsolute : permet de savoir si un lien est absolu

• function strip_tags_keepnotes(keeptags) Enleve les tags HTML qui gardent les footnotes et les endnotes de OpenOffice

Filtres PHP et développements

Les fonctions php qui modifient les chaînes de caractères peuvent être utilisées directement comme des filtres lodelscript.

Exemple : la fonction php trim() enlève les espaces en début et en fin de chaîne. On peut donc effectuer ce nettoyage en écrivant :

[(#TITRE|trim)]

Consultez la liste des fonctions sur les chaînes de caractères dans la documentation de Php :

http://www.php.net/manual/fr/ref.strings.php

Vous pouvez développer vos propres filtres. Pour cela consultez les sources de Lodel et le fichier textfunc.php.

Combinaisons de modificateurs de variables

Il est possible d’appliquer plusieurs fonctions à une variable. Il suffit de mettre bout à bout les noms des fonctions séparés par le caractères ‘|’ (pipe). Les fonctions seront exécutées de gauche à droite. Attention, l'ordre des filtres a une incidence sur le résultat. Il est donc important de réfléchir à l'ordre d'exécution des filtres.

variables :

#TEXTE :

"Les sanglots longs des violons de l'automne, blessent mon coeur d'une langueur monotone"

template :

Le texte modifié : [(#TEXTE|replacequotationmark|majuscules)<br />

résultat :

&quot;LES SANGLOTS LONGS DES VIOLONS DE L'AUTOMNE, BLESSENT MON COEUR D'UNE LANGUEUR MONOTONE&quot;<br />

Mini-texte

Des blocs de texte peuvent être insérés en utilisant la syntaxe suivante :

<TEXT NAME="nom_du_texte">

Utilisez l'interface pour les modifier.

Macros

Les macros sont des extraits de template qui sont utilisés plusieurs fois dans un template ou dans plusieurs templates déférents. Les macros peuvent être définies et regroupées dans des fichiers qu’il faut inclure dans le fichier template grâce à l’instruction suivante :

<USE MACROFILE="macro.html">

Après cette instruction, toutes les macros définies dans le fichier macro.html seront accessibles dans le fichier template.

La définition d’une macro se fait comme suit :

<DEFMACRO NAME="nom_de_la_macro">

corps de la macro

</DEFMACRO>

Le nom de la macro peut être composé de lettres majuscules et minuscules, de chiffres et du caractère ‘_’. Les lettres accentuées, le point et le tiret sont interdits.

Pour appeler une macro il faut utiliser la commande ci-dessous :

<MACRO NAME="nom_de_la_macro">

Exemple :

Fichier macro.html :

<DEFMACRO NAME="exemple">

<strong>Ceci est un exemple.</strong>

</DEFMACRO>

Fichier template :

<USE MACROFILE="macro.html">

<h1>Exemple de macro</h1>

Premier appel :<br />

<MACRO NAME="exemple">

<br />

Deuxième appel :<br />

<MACRO NAME="exemple">

<br />

Dernier appel :<br />

Résultat :

<h1>Exemple de macro</h1>

Premier appel :<br />

<strong>Ceci est un exemple.</strong>

<br />

Deuxième appel :<br />

<strong>Ceci est un exemple.</strong>

<br />

Dernier appel :<br />

<strong>Ceci est un exemple.</strong>

<br />

Inclusion de fichiers template

Il est possible d’inclure un fichier template dans un autre fichier template lorsqu’ils sont situés dans le même répertoire tpl. La syntaxe est la suivante :

<USE TEMPLATEFILE="fichier">

Attention, lors de son inclusion la page ne peut pas faire appel à des macros extérieures. Vous risquez alors d'avoir un message d'erreur.

Intégrer PHP à Lodelscript

Php dans lodelscript

Il est possible d'intégrer du code PHP à du code lodelscript. Pour cela, il suffit d'utiliser les balises d'ouverture et de fermeture de php : <?php et ?>

<DEFMACRO NAME='phpinfo''>

<?php phpinfo(); ?>

</DEFMACRO>

Attention cependant, ce code ne sera exécuté que lorsque les templates seront compilés. Ensuite, le résultat sera mis en cache.

La gestion du cache : ESCAPE et REFRESH

On peut vouloir que ce code ne soit pas exécuté ni mis en cache, mais obligatoirement exécuté au moment où l'internaute demande la page.

Ce serait le cas si l'on souhaite afficher l'heure ou la date du jour. Pour cela il faut utiliser les balises <ESCAPE>

<ESCAPE>

<?php date("d/m/y");?>

</ESCAPE>

ESCAPE permet donc d'exécuter systématiquement une partie de code. ESCAPE ne peut contenir que du code php ou du texte html, pas de LodelScript.

Cependant, si l'on souhaite plutôt une mise à jour régulière et non systématique, alors il faut utiliser l'attribut REFRESH qui permet un contrôle poussé de la mise en cache.

L'attribut REFRESH est indiqué en tête de votre template :

<CONTENT VERSION="1.0" LANG="fr" CHARSET="iso-8859-1" REFRESH="3600" />

REFRESH supporte deux syntaxes :

Si l'attribut est un nombre, il indique l'intervalle minimal en seconde pour un nouveau calcul de la page : avec REFRESH="3600", le fichier est recalculé si la version dans le cache a été produite il y a plus d'une heure ET si la page est demandée. La page n'est donc PAS recalculée toutes les heures automatiquement.

Si l'attribut est de la forme hh:mm ou hh:mm:ss, alors le fichier est recalculé une fois passée l'heure indiquée.

Cela est utile quand on sait qu'une information arrive a telle ou telle heure et qu'on souhaite mettre immédiatement le site à jour (c'est le cas pour les flux RSS ou ATOM). Ce contrôle peut aussi être utile lorsque l'on gère un calendrier, un REFRESH="0:00" met le site à jour.

Il est possible d'utiliser plusieurs heures, dans la balise :

REFRESH="6:00, 12:00, 18:00" les espaces ne sont pas significatifs.

Jeu de caractères.

Lodel produit par défaut des caractères en UTF-8 ce qui permet de supporter d'afficher des caractères spéciaux mais aussi de gérer les alphabets non latins.

Cependant, comme peu d'éditeurs HTML supporte l'édition en UTF-8, il est possible d'écrire les templates en ISO-8859. Pour cela, il faut definir au début du template :

<CONTENT VERSION="1.0" LANG="fr" CHARSET="iso-8859-1"/>

Votre template sera ensuite traduit automatiquement en UTF-8 par Lodel.

Les attributs VERSION et LANG ne sont pas utilisées actuellement mais devrait l'être. Il donne de toute façon une information utile.

Liste des messages d’erreur

Messages renvoyés par le parseur LodelScript

"Unable to read file $in" :

Lodelscript tente de lire un fichier sans y parvenir. Vérifiez qu'il existe et si il n'y a pas de problèmes de droits.

"Invalid refresh time \"$refresh\""

Le temps de refesh n'est pas valide.

"the macro file ''fichier.html'' does exist"

Le fichier de macro n'existe pas. Vérifiez.

"this file contains more closing tags than opening tags"

Une erreur de codage, certaines <BALISES> sont fermées mais pas ouvertes. Vérifiez votre fichier.

"cannot write file $out"

Erreur d'écriture : vérifiez les droits sur le répertoire.

"internal error in parse_main. Report the bug"

Bogue important. Contactez l'équipe de Lodel : lodel@lodel.org

"The closing tag ".$this->arr[$this->ind]." is malformed"

Erreur dans l'écriture d'une balise.

"internal error in parse_main. Report the bug"

Bogue important. Contactez l'équipe de Lodel : lodel@lodel.org

"name already defined in loop $name"

Vous utilisez deux fois le même attribut NAME.

"Attribut LIMIT should occur only once in loop $name"

Vous ne pouvez utilisez LIMIT qu'une seule fois dans une boucle.

"Attribut GROUPY should occur only once in loop $name"

Vous ne pouvez utilisez GROUPBY qu'une seule fois dans une boucle.

"Attributs SELECT and DONTSELECT are exclusive in loop $name"

Vous ne pouvez pas utiliser à la fois SELECT et DONTSELECT dans la même boucle.

"unknown attribut \"$result[1]\" in the loop $name"

Attribut inconnu dans votre boucle.

"the name of the loop on table(s) ''nom'' is not defined"

L'attribut NAME de la LOOP n'est pas défini.

"loop $name cannot be defined more than once"

Deux boucles ne peuvent pas avoir le même nom.

"internal error in parse_loop. Report the bug"

Bogue important. Contactez l'équipe de Lodel : lodel@lodel.org

"In loop $name, the block $state is defined more than once"

Un bloc (DO, ALTERNATIVE, ou autre) est défini plus d'une fois dans une boucle.

"<TAG> not closed in the loop $name"

Une balise n'est pas fermée dans une boucle.

"unexpected <BALISE> in the loop $name"

Une balise innattendue dans une boucle.

"end of loop $name not found"

La boucle n'a pas de fin.

"In the loop $name, a part of the content is outside the tag DO",$j }

"MACRO tag malformed" }

Erreur de syntaxe dans votre boucle.

"the macro $result[2] is not defined" }

Vous appelez une macro non définie.

"IF have no COND attribut"

IF sans COND

"ELSE found twice in IF condition"

Vous utilisez deux fois ELSE.

"incorrect tags \"".$this->arr[$this->ind]."\" in IF condition"

Erreur de syntaxe dans un IF

"IF not closed"

Il manque un </IF>

"LET have no VAR attribut"

LET sans VAR.

"Variable \"$result[1]\"in LET is not a valide variable"

La variable que vous voulez assigner avec LET n'est pas valide. Probablement un problème de nom.

"</LET> expected, <BALISE> found"

Le LET est mal fermé.

"</ESCAPE> expected, <BALISE> found"

ESCAPE est mal fermé.

Messages renvoyés par le parseur PHP ou SQL

Fatal error: Call to undefined function: boucle_ma_boucle()

Vous essayer d’appeler une boucle prédéfinie qui n’existe pas, vérifiez le nom de la boucle.

You have an error in your SQL syntax near …

Une boucle base de données contient des informations qui ne correspondent pas à la base de données, vérifiez que les attributs TABLE et WHERE contiennent bien des tables et des champs existants dans la base de données.

Les tags wiki par défauts

La syntaxe wiki pouvant être utilisée par lodel est la suivante :

de types bloc

• Paragraphe : 2 sauts de lignes

• Trait HR : ==== (4 signes "égale" ou plus) + saut de ligne

• Liste : une ou plusieurs * ou - (liste simple) ou # (liste numérotée) par item + saut de ligne

• Tableaux : | texte | texte. | encadré par des espaces (sauf pour le premier) = caractere séparateur de colonne, chaque ligne écrite = une ligne de tableau

• sous titre niveau 1 : !!!titre + saut de ligne

• sous titre niveau 2 : !!titre + saut de ligne

• sous titre niveau 3 : !titre + saut de ligne

• texte préformaté : un espace + texte + saut de ligne

• citation (blockquote) : un ou plusieurs > + texte + saut de ligne

• Définitions : ;terme : définition + saut de ligne (le : doit être encadré par des espaces)

de type inline

• emphase forte (gras) : __texte__ (2 underscores)

• emphase simple (italique) : ''texte'' (deux apostrophes)

• Retour à la ligne forcée : %%%

• Lien : [ nomdulien | lien | langue | déscription (title)]

• Image : (( lien vers l'image | textalternatif | position | longue déscription )) . valeurs de position : l/L/g/G => gauche, r/R/d/D =>droite, rien : en ligne. Dans le code généré, c'est une balise style qui est crée, et non un attribut align (obsolète).

• code : @@code@@

• citation : ^^phrase|langue|lien source^^

• reférence (cite) : {{reference}}

• acronym : ??acronyme|signification??

• ancre : ~~monancre~~

Note : Dans un texte wiki, on peut désactiver l'interprétation d'un tag wiki en mettant un antislash devant la balise d'ouverture (et de fermeture pour les tags en lignes). Exemple : \__emphase\__.