ExperSHOP - DynHtml

Page Principale Table

Pour tout rapport de bug ou suggestion, envoyez un mèl au Support ExperLog

Vue générale

DynHtml est une technologie permettant d'inclure des données provenant d'une base de données, ou d'autres données dynamiques, dans des pages HTML.

Les pages DynHtml sont interprétées à la volée par ExperSHOP, et les résultats des requêtes à la base de données sont inclus dans le texte HTML (ainsi que d'autres informations dynamiques comme par exemple des valeurs de paramètres HTTP).

Les fichiers sources DynHtml sont des fichiers ASCII, qui mélangent du HTML avec des tags spécifiques DynHtml: ceux-ci sont interprétés à l'exécution, afin d'afficher de l'information dynamique.

Comment écrire une page DynHtml

Voici un exemple de page DynHtml: 

<html><body>
<b>Liste des Clients</b><p>

$DefineSql ListeClients SELECT Prenom, Nom FROM Client

$IfPresent AgeMin
 $AppendSql ListeClients WHERE Age>AgeMin
$Endif

$ExecSql ListeClients

$IfNoResult ListeClients
 Il n'y a pas de client.

$Else

$LoopOnResults ListeClients client
 Nom du client: $client:Nom$, $client:Prenom$<br>
$EndLoop

$EndIf

</body></html>

Les valeurs de "Nom" et "Prenom" retournées dans le résultat de la requête apparaîtront dans le navigateur web, à la place de $client:Nom$ et $client:Prenom$;
L'utilisateur verra, par exemple:

Liste des Clients

Nom du client: Durand, Paul
Nom du client: Perrier, Martin

Remarquez l'instruction "$IfPresent... $Endif": si la page DynHtml est appelée avec un paramètre HTTP nommé "AgeMin", une clause WHERE est ajoutée à la requête SQL.

Comment s'interprète une page DynHtml

Les pages DynHtml sont interprétées par les servlets ExperSHOP Lite:
l'utilisateur n'a rien de particulier

Retrieve an SQL request into a variable

  $ExpandSql varname requestName

à faire.

Instructions DynHtml

$#
$Action
$Add
$Append
$AppendSql
$AppendSql2
$Assign
$Case
$CheckNumber
$ClearError
$Cookie
$Debug
$Default
$Defvar
$Div
$Else (voir les instructions If...)
$EndCase
$Endif (voir les instructions If...)
$EndLoop (voir LoopOnEnum, LoopOnFiles, LoopOnResults)
$EndSwitch
$ExecSql
$Exit
$ExitLoop
$ExpandFile
$ExpandSql
$Forward
$FetchProduct
$If
$IfEe
$IfEqual
$IfError
$IfFilePresent
$IfGe
$IfGt
$IfLe
$IfLt
$IfNoResult
$IfPresent
$Include
$Invoke
$LoopOnEnum
$LoopOnFiles
$LoopOnResults
$Mul
$NewObject
$SetCookie
$Sub
$Switch
$System

Variables et paramètres

 Variables, paramètres, colonnes dans la base de donnée, etc... sont désignés par un nom de variable: pour afficher la valeur correspondant à un nom de variable, mettez un caractère "$" de chaque côté du nom de variable:
$nom-de-variable$

Il est possible d'utiliser des formats d'affichage, par exemple pour les valeurs numériques: le format doit être mis entre parenthèses juste après le caractère "$" qui délimite la variable (par exemple, $(.00)nom-de-variable$ affichera la valeur de la variable avec 2 décimales).

Formats numériques:

Tous formats supportés par la classe java java.text.DecimalFormat.
Par exemple, le format "(.00)" appliqué à "20.123" affichera "20.12" ; appliqué à "20.1", il affichera "20.10".
Exemples:

      $(.00)Prix$
      $(##.##)Total$

Notez que les formats numériques n'ont pas pour but d'arrondir des nombres: leur effet lorsqu'il sont utilisés dans ce but n'est pas garanti, en particulier les formats (0) et (00) peuvent réserver des surprises si on les applique à des réels.

Si vous avez besoin d'arrondis, utilisez les formats (Round), (Ceil) ou (Floor).
(Round) arrondit un nombre à l'entier le plus proche.
(Ceil) arrondit un nombre au plus petit entier supérieur à ce nombre.
(Floor) arrondit un nombre au plus grand entier inférieur à ce nombre.

Formats de chaînes de caractères:

String.sub - Sous-chaine. Par exemple, $(String.sub5,8)chaine$ retourne les caractères entre les positions 5 (incluse) et 8 (exclue), et $(String.sub5)chaine$ retourne tous les caractères après la position 5 (incluse). La première position est 0, pas 1.
String.length - Longueur de chaine (entier).
String.indexof:souschaine - Recherche de sous-chaine. La position du 1er caracère de la 1ere occurrence de la sous-chaine est retournée (en commençant à 0). "souschaine" est un nom de variable : s'il s'agit d'une constante, il faut ajouter le caracère "%" devant (par exemple, $(String.indexof:test)machaine$ recherche la valeur de la variable "test", alors que $(String.indexof:%test)machaine$ recherche la chaine "test").
String.padl - Produit une chaine de longueur définie, en ajoutant des blancs à gauche. Par exemple, si $allezfrance$ est égale à "Allez France", $(String.padl20)allezfrance$ retournera "        Allez France".
String.padr - Produit une chaine de longueur définie, en ajoutant des blancs à droite. Par exemple, si $allezfrance$ est égale à "Allez France", $(String.padr20)allezfrance$ retournera "Allez France        ".
String.padc - Produit une chaine de longueur définie, centrée. Par exemple, si $allezfrance$ est égale à "Allez France", $(String.padc20)allezfrance$ retournera "    Allez France    ".

Formats de dates :
Voir le document "travailler avec les dates".

Autres formats:

Upper - Passage en majuscules (exemple: $(Upper)nom$)
Lower - Passage en minuscules (exemple: $(Lower)nom$)
UcFirst - Première lettre en majuscule (exemple: $(UcFirst)nom$)
UrlEncode - URL-encodage d'une valeur, pour la passer en paramètres via HTTP (exemple: $(UrlEncode)nom$)
HtmlEncode - Encodage de caractères spéciaux en HTML (par exemple, pour les valeurs des tags "hidden"). Remplace ", &, < et > respectivement par &quot;, &amp;, &lt; et &gt;.
(exemple: $(HtmlEncode)nom$)
JsEncode - Encodage de caractères spéciaux pour les chaines Javascript. Remplace " et ' respectivement par \" et \'.
(exemple: $(JsEncode)nom$)
XmlEncode - Encodage de caractères spéciaux pour les attributs et éléments Xml.
(exemple: $(XmlEncode)nom$)
SqlEncode - Encodage d'une valeur, pour l'utiliser dans une requête SQL. Si le verbe est utilisé tel quel, l'encodage sera appliqué avec le datasource principal de l'application.
(exemple: $(SqlEncode)nom$)
Il est possible de préciser le datasource avec lequel l'encodage doit être fait: $(SqlEncode.[nom_du_datasource])nom$
(exemple: $(SqlEncode.Oracle)nom$)
RemoveHtmlTags - Supprimer les tags HTML.
(exemple: $(RemoveHtmlTags)question$)
QuoteMessage - Formatage analogue aux réponses d'email ("> " en début de ligne). Exemple: $(QuoteMessage)msg$

Variables DynHtml prédéfinies

$COOKIE$

Le numéro de session client ExperShop, sous forme de paramètre HTTP, à inclure dans les URL ExperSHOP (dans les liens HTTP utilisant le tag HTML <A HREF=...> tag).
Exemple:
<A HREF= "com.expershop.lite.ExperSHOP?$COOKIE$&Page=ProchainePage.tmpl"> Page Suivante</A.>

Voir aussi: instruction $Cookie, pour les URLs invoquées via des "FORM" HTML.

$\$

Affiche un caractère "$".
Cette séquence escape est parfois nécessaire: par exemple, "Prix de l'article: $10" sera affiché correctement.
Par contre, "Prix de l'article: $10, plus $2 de frais de port" pose un problème: ExperSHOP va chercher à afficher la valeur d'une variable nommée "10, plus " (le texte compris entre les deux "$" sera considéré comme un nom de variable).
Dans ce cas, il faut utiliser la variable prédéfinie "$\$": "Prix de l'article: $\$10, plus $\$2 de frais de port" fonctionnera parfaitement.

Data sets et data objects

Un "data object" est equivalent à un n-uplet de base de données, avec des attributs équivalents aux colonnes du n-uplet.

Un "data set" est un ensemble de "data objects": par exemple, le résultat d'une requête à une base de données, ou le panier d'achats d'un client vu comme un ensemble d'articles.
Il est possible de boucler sur le contenu d'un "data set", en utilisant l'instruction $LoopOnResults...$EndLoop; A chaque tour de la boucle, vous pouvez accéder au "data object" courant et à ses attributs.

Il y a deux types de "data sets": les "data sets" prédéfinis d'ExperSHOP (comme le panier d'achats ou le fichier de configuration de la boutique), et les "data sets" transitoires générés à l'exécution (comme les résultats de requêtes à une base de données, ou les énumérations).

Par exemple, ExperShop fournit un "data set" prédéfini appelé ShoppingCart, qui donne accès au panier d'achats: cet objet a un attribut appelé TotalPrice, le prix total des articles contenus dans le panier d'achats: vous pouvez l'afficher dans une page DynHtml, en utilisant la syntaxe suivante:
$ShoppingCart:TotalPrice$.

Le panier d'achats, "ShoppingCart", est aussi un "data set": vous pouvez boucler sur les articles du panier, pour afficher leurs caractéristiques (chaque article étant un "data object").
Par exemple, dans une boucle $LoopOnResults ShoppingCart item ... $EndLoop, vous pouvez afficher la quantité correspondant à chaque article en utilisant la syntaxe suivante:
$item:Qty$.

Les requêtes SQL sont elles aussi des "data sets", dès leur exécution:
Par exemple, l'instruction $ExecSql MaRequete [MaBase] crée un "data set" nommé "MaRequete" avec la bas "MaBase", sur lequel vous pouvez boucler pour afficher ses résultats. "MaBase" est définie dans le fichier de configuration de l'application.

Définir des variables et des paramètres

Une variable est une association nom/valeur.
Pour définir une variable, utilisez l'instruction $DefVar.
Exemple: $DefVar njours 31

Un paramètre est une variable vue comme un paramètre HTTP: en particulier, il sera transmis aux actions si $Action est utilisé. (par contre, il ne sera pas transmis si la page courante est soumise en tant que "form" HTML: c'est un paramètre de la page courante).
Pour définir un paramètre, utilisez l'instruction $Assign.
Exemple: $Assign nom Jean

Pour ajouter du texte à la fin d'une variable ou d'un paramètre, utilisez l'instruction $Append.
Si vous ajoutez un caractère blanc (espace), mettez-le entre guillemets.
Exemple:
$Append nom " "
$Append nom Durand

Une variable peut être calculée :
Exemple:

$DefVar jour (24 * 60 * 60)

Enumérations

 Une énumération est une liste de valeurs separées par des virgules, ou une série continue d'entiers, ou les deux; par exemple, vous pouvez définir des énumérations comme ceci:
$DefVar mois Jan,Fev,Mar,Avr,Mai,Jun,Jul,Sep,Oct,Nov,Dec
$DefVar jourssemaine 1->7
Le premier exemple liste les mois, le second est équivalent à 1,2,3,4,5,6,7.
La combinaison des deux syntaxes est valide: par exemple,
$DefVar intervalles 1->5,10->20

Il est possible de boucler sur les valeurs d'une énumération, en utilisant l'instruction $LoopOnEnum ... $EndLoop; exemple:

      $LoopOnEnum mois mm
      Le mois courant est: $mm:value$
      $EndLoop

      $LoopOnEnum jourssemaine jj
      Le jour courant est: $jj:value$
      $EndLoop
En fait, une énumération est un "data set", dont chaque valeur "data object" comporte une seule colonne, nommée "value" (c'est pourquoi mm:value est utilisé dans la boucle ci-dessus).

Erreurs

Certaines instructions, comme $ExecSql (exécution d'une requête SQL) ou $Action (exécution d'une action), peuvent provoquer des erreurs d'exécution.

Il est possible de traîter les erreurs d'exécution en utilisant l'instruction $IfError...$Endif, ainsi que d'effacer les erreurs d'exécution en utilisant l'instruction $ClearError.

Passage du numéro de session client dans une "FORM" HTML

L'instruction $Cookie passe le numéro de session client sous forme de tag "HIDDEN" via une "FORM" HTML.
$Cookie est remplacée par un ensemble de tags HTML "<INPUT TYPE=HIDDEN ...>", afin de passer le numéro de session client comme paramètre d'une "FORM" HTML.

Exemple (dans une page DynHtml, la plupart des "FORM" doiven commemcer ainsi):

      <FORM METHOD=POST ACTION="com.expershop.lite.ExperSHOP">
      $Cookie

Stocker des informations liées à la session

 $Cookie permet d'accéder à toute information liée à la session client: par exemple, $Cookie:CustId$ est le numéro de client lorsqu'un client est loggé.

Notez qu'ExperShop n'utilise pas de "vrais" cookies: dans ce document, "cookie" fait référence à des informations relatives à la session, et disponibles pendant toute sa durée.

Il est possible de stocker des informations dans le "cookie":

  • En définissant des paramètres HTTP dont le nom se termine par "_" (comme "uneinfo_"); Ces paramètres seront transmis une première fois via un lien HTTP ou la soumission d'une "form", puis seront ensuite accessibles via $Cookie (exemple: $Cookie:uneinfo_$).
  • En appelant $SetCookie.
    Par exemple, $SetCookie salut Bonjour ! définit une nouvelle information de session appelée "salut" et égale à "Bonjour !"; pour accéder à sa valeur, utilisez $Cookie:salut$

Requêtes SQL

 Il est possible de définir des requêtes SQL, de les exécuter, et de boucler sur leurs résultats pour afficher le contenu des n-uplets.

Définir une requête SQL

      $DefineSql nomRequete instruction-sql

Ajouter du texte à une requête SQL
      $AppendSql nomRequete texte
      $AppendSql2 nomRequete texte
$AppendSql et $AppendSql2 permettent d'ajouter du texte à une requête SQL. $AppendSql2 évalue la requête tout de suite (toutes les variables connues sont remplacées par leur valeur), alors que $AppendSql laisse les variables telles quelles (la requête sera évaluée par $ExecSql, dont elle peut être paramétré).
$AppendSql ou $AppendSql2 peuvent être utilisés avec une instruction "If... Else", pour compléter le texte d'une requête.
Note: Si "texte" commence par "AND" ou "OR", la chaîne AND ou OR sera supprimée si "texte" est la première condition d'une clause WHERE.
Par exemple, ajouter "AND Prix>10" à la requête "SELECT * FROM Articles WHERE" produira "SELECT * FROM Articles WHERE Prix>10".
Ensuite, ajouter "AND Prix<100" produira "SELECT * FROM Articles WHERE Prix>10 AND Prix<100".

Exécuter une requête SQL

      $ExecSql nomRequete [nomBase]
Si la requête contient des variables, celles-ci sont évaluées avant exécution de la requête.
Le nom de la base est optionnel dans le cas de la base de données définie par défaut dans le fichier de configuration de l'application, sinon la base de données doit être définie sous forme d'une datasource dans le fichier de configuration de l'application.

Boucler sur les résultats d'une requête

      $LoopOnResults nomRequete nomTuple [i j]
      ...
      $EndLoop
Il est possible de rajouter au nom du tuple les bornes de la requête, pour pouvoir boucler de l'élément i, jusqu'à l'élément j. Attention, cette option ne guarantit en rien l'ordre des éléments provenant de la base (contrainte SGBD).
exemple : 
      $LoopOnResults MyREQ myTuple 11 20
      ...
      $EndLoop

Afficher la valeur d'une colonne (dans une boucle)

$nomTuple:colonne$ nomTuple est le nom du n-uplet défini dans l'instruction LoopOnResults, et colonne est le nom de la colonne.

Cas où il n'y a pas de résultat

      $IfNoResult nomRequete
      ...
      $Else
      ...
      $Endif

Gestion d'erreur
      $IfError
      ...
      $Else
      ...
      $Endif

Extraire une requête SQL dans une variable

  $ExpandSql nomVariable nomRequete

Actions

 Vous pouvez exécuter une Action ExperSHOP depuis une page DynHtml, en utilisant l'instruction $Action (pour en savoir plus sur les Actions ExperSHOP, voir la page web des actions DynHtml).

Syntaxe: $Action classe-de-l-action [paramètre]
paramètre est optionnel (peu d'actions reçoivent un paramètre par ce moyen: en général, les paramètres sont passés aux actions via des paramètres HTTP).
classe-de-l-action est le nom de la classe java de l'action.

Exemple: vider le panier d'achats. 

      $Action com.expershop.actions.ESEmptyCart

Tester la présence d'une variable

 
      $IfPresent nomVariable
      ...
      $Else
      ...
      $Endif
Exemples:
$IfPresent Prenom
$IfPresent client:Prenom (dans une boucle)

Tester la présence d'un fichier

      $IfFilePresent nomFichier
      ...
      $Else
      ...
      $Endif
Exemples:
$IfFilePresent fichierLocal.txt (dans le répertoire local)
$IfFilePresent /tmp/fichier.txt (chemin absolu)
$IfFilePresent f:NomFich (dans une boucle)

Accéder au contenu d'un répertoire

      $LoopOnFiles repertoire fich
       Nom: $fich:name$, Extension: $fich:ext$,
       Date: $(DateFormat.dd/MM/yyyy)file:lastmodified$,
       FichierOuRepertoire: $file:isfile$ <br>
       ...
      $EndLoop
Le nom du répertoire est soit relatif à ESRootDir, soit absolu (par exemple, s'il commence par / sous Unix).
Le champ "isfile" vaut 1 s'il s'agit d'un fichier, 0 sinon (répertoire, lien...)

Vérification de syntaxe des nombres

Il peut être nécessaire de vérifier si une valeur est un nombre ou pas.
$CheckNum réalise le test, et provoque une erreur si la valeur n'est pas un nombre (l'erreur peut être détectée avec $IfError ... $Endif, puis effacée avec $ClearError); Exemple: 
      $DefVar x 2.3
      $CheckNumber $x$
      $IfError
       ERREUR: $x$ n'est pas un nombre<br>
      $Else
       Ok<br>
      $Endif
      $ClearError

Opérateurs de calcul simples

 Il est possible de faire des additions, soustractions, multiplications et divisions, en utilisant $Add, $Sub, $Mul and $Div.
Les variables utilisées doivent avoir été préalablement déclarées; exemple: 
      $DefVar a 1
      $Add a 1
      $DefVar b 2
      $Div a $b$
Dans cet exemple, a=1, puis on ajoute 1 (a=2), et on divise par la valeur de b (à la fin, a=1).

Comparer des valeurs

Egalité de chaînes de caractères
      $IfEqual nomvariable valeur
      ...
      $Else
      ...
      $Endif
Exemples:
$IfEqual Ville Paris
$IfEqual Prenom ""
$IfEqual Prenom $nom$
$IfEqual client:Prenom Jean (dans une boucle)

Comparaisons de valeurs numériques

$IfEe...$Endif (=), $IfGe...$Endif (>=), $IfGt...$Endif (>), $IfLe...$ Endif (<=), $IfLt...$Endif (<)
Exemples: 

      $IfEe variable 0
      Zero!
      $Endif
      $IfLe variable 10
      $variable$ <= 10
      $Endif
      $IfLt variable $unNombre$
      $variable$ < $unNombre$
      $Endif
      $IfGe variable 10
      $variable$ >= 10
      $Endif
      $IfGt variable $unNombre$
      $variable$ > $unNombre$
      $Endif

Comparer et évaluer des expressions

 $If permet d'utiliser des expressions à l'intérieur d'une syntaxe conditionnelle : 
      $If ( expression opérateur expression)
      ...
      $Else
      ...
      $Endif
"expression" peut être un calcul : ($var1$ + 14)*3 + $var2$
"opérateur" peut être un opérateur de comparaison, ou un opérateur logique.
Les opérateurs de comparaison sont : 
 < > <= >= = <> !=
Les opérateurs logiques sont : 
      && ("et" logique)
      || ("ou" logique)
      ! ("not" logique)
Il est possible d'utiliser des parenthèses pour regrouper des expressions.
Par exemple, la syntaxe suivante est valide : 
      $If $courant$ >= $min$ && ! ($courant$ > $max$)
        La valeur courante semble correcte.
      $Else
        La valeur courante est en dehors des bornes.
      $Endif

Exit

 
      $Exit
Quitter la page immédiatement.

ExitLoop

      $ExitLoop
Quitter la boucle courante immédiatement.

Switch (Case, EndCase, EndSwitch)

      $Switch var
        $Case val_1
          ...
          ...
        $EndCase

        $Case val_2
          ...
          ...
        $EndCase
        $Default
          ...
          ...
        $EndCase
      $EndSwitch
Selon la valeur de l'expression le cas approprié est exécuté. Dans le cas où aucune expression ne convient, il est possible de rajouter un cas "attrape-tout" ("$Default").

Afficher une autre page DynHtml

      $ExpandFile chemin

$ExpandFile est différent de $Include: par exemple, une variable ou une requête définie dans le fichier expansé ne sera pas accessible au retour dans le fichier d'origine.
chemin est relatif au répertoire où se trouve la page courante.

Executer le code d'une autre page DynHtml

      $Include chemin

$Include est différent de $ExpandFile: par exemple, une variable ou une requête définie dans le fichier expansé sera accessible au retour dans le fichier d'origine.
chemin est relatif au répertoire où se trouve la page courante.

Transférer la requête HTTP à une autre URL (HTTP Forward)

  $Forward URL

URL peut être absolue ou relative.
$Forward sera ignoré s'il n'a pas de sens dans le contexte considéré (ex. dans un $ExpandFile ou une action SendMail...)
Seule la requête HTTP d'origine sera transféré (les paramétres qui auraient été ajoutés, par exemple avec $Assign, seront perdus).

Exécuter une commande sur le système

      $System command

$System exécute une commande du système d'exploitation: les résultats de la commandes sont affichés sur le flux HTML de sortie.
Par exemple, pour lister les fichiers dans /tmp sur un système Unix:
      <pre>
      $System ls -l /tmp
      </pre>

Traces de Debug

      $Debug texte
Affiche du texte sur la sortie standard, dans un but de debug.
Exemples:
$Debug Bonjour les gars!
$Debug Nom = $Nom$

Commentaires

      $# Ceci est un Commentaire

Accédes à un produit par référence article

  $FetchProduct refProduit nomVariable
Accès à un produit de la base articles (par défaut : table EProduct), par référence article (par défaut : colonne ProdId). Le résultat est un "data object" (stocké dans une variable dont le nom est spécifié par "nomVariable") avec au moins 3 attributs : ProdId (réf. article), Name (nom), Price (prix unitaire).
Cette instruction sert à encapsuler les produits, pour éviter d'utiliser des requêtes SQL complexes dans les templates (ex. pour calculer le prix unitaire d'un article en fonction d'une catégorie de client ou d'une devise...)