Présentation de la Java Standard Tag Library (JSTL)

Date de publication : 09/02/2005 , Date de mise à jour : 18/02/2007

Par F. Martini (adiGuba) (mes autres tutoriels)
 

Remerciement
Présentation
1.1. Objectifs de la JSTL
1.2. Documentation
1.3. Les versions
1.4. Configuration de la JSTL
2. <c:/> : Librairie de base
2.1. Gestion des variables de scope
<c:out/> : Afficher une expression
<c:set/> : Définir une variable de scope ou une propriété
<c:remove/> : Supprimer une variable de scope
<c:catch/> : Intercepter les exceptions
2.2. Actions conditionnels
<c:if/> : Traitement conditionnel
<c:choose/> : Traitement conditionnel exclusif
<c:when/> : Un cas du traitement conditionnel
<c:otherwise/> : Traitement par défaut
2.3. Itérations
2.3.1. Attributs standards des boucles
<c:forEach/> : Itérer sur une collection
<c:forTokens/> : Itérer sur des éléments d'une String
2.4. Les URLs
<c:param/> : Ajouter un paramètre à une URL
<c:url/> : Créer une URL
<c:redirect/> : Redirection
<c:import/> : Importer des ressources
3. <fmt:/> : Librairie de Formatage
3.1. Internationalisation (i18n)
3.1.1. Configuration
3.1.1.1. Locale
3.1.1.2. Locale par défaut
3.1.1.3. Contexte de localization
<fmt:setLocale/> : Définir la Locale
<fmt:setBundle/> : Définir le ResourceBundle
<fmt:bundle/> : Définir un ResourceBundle partiel
<fmt:message/> : Afficher des messages
<fmt:param/> : Ajouter un paramètre au message
<fmt:requestEncoding/> : Encodage du client
3.2. Formatage
3.2.1. Configuration
3.2.1.1. Fuseau horaire (TimeZone)
<fmt:setTimeZone/> : Définir le fuseau horaire
<fmt:timeZone/> : Utiliser un Timezone
<fmt:parseDate/> : Analyser une date
<fmt:formatDate/> : Formater une date
<fmt:parseNumber/> : Analyser un nombre
<fmt:formatNumber/> : Formater un nombre
4. <sql:/> : Librairie SQL
4.1. Configuration
4.1.1. DataSource
4.1.2. Nombre de ligne maximum
<sql:setDataSource/> : Définir le Datasource
<sql:query/> : Exécuter une requête
<sql:update/> : Exécuter une commande SQL
<sql:transaction/> : Exécuter une commande SQL
<sql:param/> : Définir un paramètre de la requête
<sql:dateParam/> : Définir une date en paramètre de la requête
5. <x:/> : Librairie XML
5.1. XPath
5.2. Actions XML de base
<x:parse/> : Analyser un XML
<x:out/> : Evaluer une expression
<x:set/> : Créer une variable de scope
5.3. Actions de contrôle XML
<x:if/> : Action conditionnelle
<x:choose/> : Traitement conditionnel exclusif
<x:when/> : Un cas du traitement conditionnel
<x:otherwise/> : Traitement par défaut
<x:forEach/> : Itérer sur le fichier XML
5.4. Transformation XSLT
<x:transform/> : Appliquer un XSLT
<x:param/> : Ajouter un paramètre XSLT
6. ${fn:} : Librairie de fonctions EL
${fn:contains()}
${fn:containsIgnoreCase()}
${fn:endsWith()}
${fn:escapeXml()}
${fn:indexOf()}
${fn:join()}
${fn:length()}
${fn:replace()}
${fn:split()}
${fn:startsWith()}
${fn:substring()}
${fn:substringAfter()}
${fn:substringBefore()}
${fn:toLowerCase()}
${fn:toUpperCase()}
${fn:trim()}
7. Créer une taglib compatible avec la JSTL
7.1. Accès à la configuration
7.2. Tags conditionnels
7.3. Tags itératifs
7.4. Accès aux données localisées
Conclusion

Remerciement

Présentation

Ce tutoriel est également disponible en version PDF :  ftp://ftp-developpez.com/adiguba/tutoriels/j2ee/jsp/jstl/jstl.pdf Mirroir :  http://adiguba.ftp-developpez.com/tutoriels/j2ee/jsp/jstl/jstl.pdf

1.1. Objectifs de la JSTL

1.2. Documentation

1.3. Les versions

• La JSTL 1.0 nécessite au minimum un conteneur JSP 1.2 (J2EE 1.3).
• La JSTL 1.1 nécessite au minimum un conteneur JSP 2.0 (J2EE 1.4).

Ces URI ne doivent pas être utilisées dans une application J2EE 1.4 afin de ne pas rentrer en conflit avec l'interpréteur d'EL intégré dans les JSP 2.0. De plus cela interdit l'utilisation de scriptlets en tant que valeur des attributs des tags (seules les chaines de caractères sont autorisées) :

Attention, si ces URIs sont utilisées dans des JSP 1.1 ou 1.2, les Expressions Languages ne seront pas interprétés.

Afin de les distinguer des URIs de la JSTL 1.0, la chaîne "/jsp" a été ajoutée afin d'indiquer que cette version se base sur le conteneur JSP pour interpréter les Expressions Languages.

L'utilisation des Expressions Languages est nécessaire pour une utilisation optimale de la JSTL, consultez le tutoriel dédié aux Expressions Languages pour plus de détails :  http://adiguba.developpez.com/tutoriels/j2ee/jsp/el/

1.4. Configuration de la JSTL

La valeur de ces paramètres peut être modifiée dynamiquement via la classe Config ou via des tags spécifiques décrits dans la librairie correspondante. La nouvelle valeur est alors stockées dans un des scopes de l'application, avec les influences suivantes :

Scope	Description
page	La nouvelle valeur n'affecte que la page JSP courante.
request	La nouvelle valeur affecte toute la requête courante (pages JSP forwardées/incluses compris).
session	La nouvelle valeur affecte toute la session de l'utilisateur.
application	La nouvelle valeur affecte tous les utilisateurs.

Lorsqu'une valeur de configuration est nécessaire, elle est d'abord recherchée dans les différents scopes (dans l'ordre naturel : page, request, session puis application). Si la valeur n'existe dans aucun des scopes, la valeur définit dans le web.xml est utilisée, ou une valeur par défaut le cas échéant.

2. <c:/> : Librairie de base

Cette section et ses sous sections définissent les différentes actions de la librairie "code" de la JSTL. C'est à dire la librairie qui contient les actions de base d'une application web.

Déclaration de la librairie 'core' :

<%@ taglib uri="http://java.sun.com/jstl/core" prefix="c" %>

2.1. Gestion des variables de scope

Cette section comporte les actions de base pour la gestion des variables de scope d'une application web :

• L'affichage de variable
• La création/modification/suppression de variable de scope
• La gestion des exceptions

<c:out/> : Afficher une expression

Evalue une expression et l'affiche dans la page JSP.

Attribut	Req.	Type	Description
value	oui	Object	L'expression qui sera évaluée et affichée. Si le type réel implémente java.io.Reader, alors c'est son contenu qui sera affiché.
default		Object	Valeur à afficher si l'expression value est null (défaut : "").
escapeXml		booleen	Détermine si les caractères <, >, &, ', " doivent être remplacés par leurs codes respectifs : &lt;, &gt;, &amp;, &#039;, &#034; (défaut : true).

Le Corps du tag peut être utilisé à la place de l'attribut default.

Exemple

<!-- Afficher l'user-agent du navigateur ou "Inconnu" si il est absent : --> <c:out value="${header['user-agent']}" default="Inconnu"/> <!-- Même chose en utilisant le corps du tag : --> <c:out value="${header['user-agent']}"> Inconnu </c:out>

Le conteneur JSP 2.0 gère lui-même les EL, ainsi le code <c:out value="${expression}" escapeXml="false"/> est équivalent à ${expression}.

<c:set/> : Définir une variable de scope ou une propriété

Permet de définir une nouvelle variable de scope, ou de changer la valeur d'une propriété d'un beans.

Attribut	Req.	Type	Description
value		Object	L'expression à évaluer.
var		String	Nom de l'attribut qui contiendra l'expression dans le scope.
scope		String	Nom du scope qui contiendra l'attribut var (page, request, session ou application) (défaut : page).
target		Object	L'objet dont la propriété définit par property sera modifiée. Il doit correspondre soit à un bean avec la méthode mutateur correspondante (setProperty)), soit à un objet de type java.util.Map.
property		String	Nom de la propriété qui sera modifiée.

Le Corps du tag peut être utilisé à la place de l'attribut value.

Exception :
Une exception est propagé lorsque l'attribut target ne correspond ni à une Map, ni à un bean possédant une propriété "property".

Exemple

<!-- Mettre ${expression} dans l'attribut "varName" de la session : --> <c:set scope="session" var="varName" value="${expression}" /> <!-- Changer la propriété "name" de l'attribut "varName" de la session : --> <c:set target="${session['varName']" property="name" value="new value"/> <!-- Changer la propriété "name" de l'attribut "varName" de la session en utilisant le corps : --> <c:set target="${session['varName']" property="name"> Nouvelle valeur de la propriété "name" </c:set>

Si l'attribut value est null, cela correspond à supprimer la variable ou la propriété d'une Map, ou à passer à null la propriété du bean.

<c:remove/> : Supprimer une variable de scope

Supprime la variable de scope indiqué.

Attribut	Req.	Type	Description
var	oui	String	Nom de la variable de scope à supprimer.
scope		String	Nom du scope qui contiendra l'attribut var (page, request, session ou application) (défaut : page).

Corps du tag : Aucun.

Exemple

<!-- Supprime l'attribut "varName" de la session --> <c:remove var="varName" scope="session"/>

<c:catch/> : Intercepter les exceptions

Intercepte les exceptions qui peuvent être lancées par son corps

Attribut	Req.	Type	Description
var		String	Nom de la variable dans le scope page qui contiendra l'exception interceptée.

Corps du tag : Le code JSP dont les exceptions seront interceptées...

Exemple

<!-- Ignorer toutes les exceptions d'une partie de la page : --> <c:catch> <c:set target="beans" property="prop" value="1"/> </c:catch> <!-- Stocker dans le scope page l'exception intercepté : --> <c:catch var="varName"> <c:set target="beans" property="prop" value="1"/> </c:cath>

Si var n'est pas spécifié, les exceptions interceptées ne seront pas sauvegardées. Si var est spécifié et qu'aucune exception n'est lancée, alors la variable de page "var" sera supprimée.

2.2. Actions conditionnels

Cette section comporte les actions permettant d'effectuer les tests conditionnels de la même manière que les mots-clef if ou switch du langage Java.

<c:if/> : Traitement conditionnel

Permet d'effectuer un traitement conditionnel de la même manière que le mot-clef if du langage Java.

Attribut	Req.	Type	Description
test	oui	booleen	La condition de test qui déterminera si le corps devra être evalué ou non.
var		String	Le nom d'une variable de scope de type Boolean qui contiendra le résultat du test.
scope		String	Nom du scope qui contiendra l'attribut var (page, request, session ou application) (défaut : page).

Corps du tag : Le code qui sera interprété selon le résultat de la condition.

Exemple

<!-- Afficher un message si le paramètre "page" de la requête HTTP est absent --> <c:if test="${empty param['page']}"> Le paramètre page est absent ! </c:if>

<c:choose/> : Traitement conditionnel exclusif

Permet d'effectuer un traitement conditionnel de la même manière que le mot-clef switch du langage Java, ou qu'une série de if/else. C'est à dire que sur plusieurs possibilités, une seule sera évaluée.

L'action <c:choose/> n'accepte aucun attribut, et le corps du tag ne peut comporter qu'un ou plusieurs tags <c:when/> et zéro ou un tag <c:otherwise/>.

L'action <c:choose/> exécutera le corps du premier tag <c:when/> dont la condition de test est évaluée à true. Si aucune de ces conditions n'est vérifiée, il exécutera le corps de la balise <c:otherwise/> si elle est présente.

Consulter les informations sur les balise <c:when/> et <c:otherwise/> pour plus de détail.

<c:when/> : Un cas du traitement conditionnel

Définit une des options de l'action <c:choose/>.
La balise parent doit obligatoirement être <c:choose/>.
Le premier tag de la balise <c:choose/> dont la condition est vérifiée sera le seul à évaluer son corps.

Le tag <c:when/> a le même fonctionnement que le mot-clef case d'un bloc switch en Java.

Attribut	Req.	Type	Description
test	oui	boolean	La condition de test qui déterminera si le corps devra être évalué ou non (on utilise généralement une Expressions Languages).

Corps du tag : Le code qui sera interprété selon le résultat de la condition.

Exemple

<!-- Afficher un message différent selon la valeur du bean 'value' : --> <c:choose> <c:when test="${value==1}"> value vaut 1 (Un) </c:when> <c:when test="${value==2}"> value vaut 2 (Deux) </c:when> <c:when test="${value==3}"> value vaut 3 (Trois) </c:when> </c:choose>

<c:otherwise/> : Traitement par défaut

Le traitement à effectuer si aucun tag <c:when/> n'a été évalué.
La balise parent doit obligatoirement être <c:choose/> et après la dernière balise <c:when/>.

Elle n'accepte aucun attribut et n'évaluera son corps que si aucune des balises <c:when/> n'est vérifiée.

Le tag <c:otherwise/> a le même fonctionnement que le mot-clef default d'un bloc switch en Java.

Exemple

<c:choose> <c:when test="${value==1}"> value vaut 1 (Un) </c:when> <c:when test="${value==2}"> value vaut 2 (Deux) </c:when> <c:when test="${value==3}"> value vaut 3 (Trois) </c:when> <c:otherwise> value vaut ${value} (?) </c:otherwise> </c:choose>

2.3. Itérations

Cette section comporte les actions permettant d'effectuer des boucles de la même manière que les mots-clef for ou while du langage Java.

2.3.1. Attributs standards des boucles

Les tags d'itérations de la JSTL sont basés sur la classe javax.servlet.jsp.jstl.core.LoopTagSupport. Ainsi, les tags de cette section possèdent en commun les attributs suivants :

Attribut	Req.	Type	Description
var		String	Nom d'une variable de scope qui comportera l'élément courant de l'itération (visible à l'intérieur du corps du tag seulement).
varStatus		String	Nom d'une variable de scope qui comportera des informations sur le status de l'itération (visible à l'intérieur du corps du tag seulement).
begin		int	Spécifie l'index de départ de l'itération.
end		int	Spécifie l'index de fin de l'itération.
step		int	L'itération s'effectuera sur les N éléments de la collection. N correspondant à la valeur de step.

L'attribut varStatus permet d'utiliser un objet de type LoopTagStatus qui possèdent les propriétés suivantes :

Nom	Type	Description
begin	Integer	Valeur de l'attribut begin du tag (null si absent).
end	Integer	Valeur de l'attribut end du tag (null si absent).
step	Integer	Valeur de l'attribut step du tag (null si absent).
count	int	Comptabilise le nombre de tour de l'itération.
current	Object	L'élément courant de l'itération.
index	int	L'index de l'élément courant dans la collection.
first	booleen	Indique que la boucle courante est la première de l'itération.
last	booleen	Indique que la boucle courante est la dernière de l'itération.

Attention : count et index ne sont pas forcément identique...

Toutes ces fonctionnalités sont implémentées par la classe abstraite javax.servlet.jsp.jstl.core.LoopTagSupport. Elle peut donc être utilisée afin de créer ses propres tags itératifs...

<c:forEach/> : Itérer sur une collection

Permet d'effectuer simplement des itérations sur plusieurs types de collection de données.

Attribut	Req.	Type	Description
items		Object	La collection d'éléments qui contient les éléments de l'itération (Voir la "Liste des types supportés").
Ainsi que les attributs standards des boucles (Voir la liste des attributs standards).

Corps du tag : Le code qui sera évalué à chaque itération sur la collection.

L'attribut items accepte les éléments suivant comme collection :

• Les tableaux d'objets ou de types primaires (ils seront alors englobés dans la classe wrapper correspondante).
• Une implémentation de java.util.Collection en utilisant la méthode iterator().
• Une implémentation de java.util.Iterator.
• Une implémentation de java.util.Enumeration.
• Une implémentation de java.util.Map, en utilisant les méthodes entrySet().iterator().
• [Deprecated] Une String dont les différents éléments sont séparés par des virgules (mais il est préférable d'utiliser <c:forTokens/> à la place).
• Une valeur null sera considérée comme une collection vide (pas d'itération).
• Si l'attribut items est absent, les attributs begin et end permettent d'effectuer une itération entre deux nombres entiers.

L'utilisation d'une String dans le tag <c:forEach/> est dépréciée et ne devrait plus être utilisée. Cette fonctionnalité reste présente pour des raisons de compatibilité avec la JSTL 1.0, mais il est fortement conseillé d'utiliser le tag <c:forTokens/> à la place...

Exemple

<!-- Afficher tous les éléments d'une collection dans le request--> <c:forEach var="entry" items="${requestScope['myCollection']}" > ${entry}<br/> </c:forEach> <!-- Afficher seulement les 10 premiers éléments --> <c:forEach var="entry" items="${requestScope['myCollection']}" begin="0" end="9"> ${entry}<br/> </c:forEach> <!-- Afficher les nombres de 1 à 10 --> <c:forEach var="entry" begin="1" end="10"> ${entry}, </c:forEach>

Lors de l'itération sur une Map, l'élément courant de chaque itération est du type java.util.Map.Entry, et possède donc les propriétés suivantes :

Nom	Type	Description
key	Object	La clef utilisée pour stocker l'élément dans la Map.
value	Object	La valeur correspondante à la clef.

Exemple

<!-- Afficher tous les paramètres de la requête HTTP (param est une Map)--> <c:forEach var="entry" items="${param}" > Le paramètre "${entry.key}" vaut "${entry.value}".<br/> </c:forEach>

<c:forTokens/> : Itérer sur des éléments d'une String

Permet de découper des chaînes de caractères selon un ou plusieurs délimiteurs. Chaque marqueur ainsi obtenu sera traité dans une boucle de l'itération.

Attribut	Req.	Type	Description
items	oui	String	La chaîne de caractère qui sera découpé.
delims	oui	String	La liste des caractères qui serviront de délimiteurs.
Ainsi que les attributs standard des boucles (Voir la liste des attributs standards).

Corps du tag : Le code qui sera évalué pour chaque marqueur de la chaîne.

Exemple

<!-- Afficher séparément des mots séparés par un point-virgule --> <c:forTokens var="p" items="mot1;mot2;mot3;mot4" delims=";"> ${p}<br/> </c:forTokens>

2.4. Les URLs

Cette section décrit quelques tags utiles pour la gestion des URLs :

• Création d'URLs complexes
• Redirection vers une URLs
• Import de ressources locales ou distantes

<c:param/> : Ajouter un paramètre à une URL

Permet d'ajouter simplement un paramètre à une URL représentée par le tag parent.
Cette balise doit avoir comme balise parent une balise <c:url/>, <c:import/> ou <c:redirect/> (mais pas forcement comme parent direct).

Attribut	Req.	Type	Description
name	oui	String	Le nom du paramètre de l'URL.
value		String	La valeur du paramètre de l'URL.

Le Corps du tag peut être utilisé à la place de l'attribut value afin de définir la valeur du paramètre.

Le nom et la valeur du paramètre de l'URL est automatiquement encodé afin de respecter le format des URLs (les 'espaces' sont remplacés par des '+',...).

Exemple

<!-- La forme suivante : --> <c:url value="/mapage.jsp?paramName=paramValue"/> <!-- est equivalente à : --> <c:url value="/mapage.jsp"> <c:param name="paramName" value="paramValue"/> </c:url><br/>

<c:url/> : Créer une URL

Permet de créer des URLs absolues, relatives au contexte, ou relatives à un autre contexte.

Attribut	Req.	Type	Description
value	oui	String	L'URL à traiter (absolue, relative à l'application ou à la page courante).
context		String	Spécifie le chemin du contexte de l'application locale à utiliser (débute obligatoirement par le caractère '/'). Par défaut, il prend la valeur du contexte de l'application courante tel qu'il est renvoyé par request.getContextPath().
var		String	Le nom de la variable de scope qui contiendra la String représentant l'URL. Si absent, l'URL sera écrite dans la page JSP.
scope		String	Nom du scope qui contiendra l'attribut var (page, request, session ou application) (défaut : page).

Contrairement au tag <c:choose/> qui n'accepte que les tags <c:when/> et <c:otherwise/>, le corps du tag <c:url/> accepte tout type de code JSP. Toutefois, le corps du tag est bufférisé et tout ce qui est écrit à l'intérieur n'est pas reporté sur la page JSP mais ignoré. Cela permet d'utiliser des balises itérations ou conditionnels pour créer la liste des paramètres :

Exemple

<!-- Création d'un lien dont les paramètres viennent d'une MAP --> <c:url value="/index.jsp" var="variableURL"> <c:forEach items="${parameterMap}" var="entry"> <c:param name="${entry.key}" value="${entry.value}"/> </c:forEach> </c:url> <a href="${variableURL}">Mon Lien</a>

Les URLs sont réécrite de la manière suivante :

• Le chemin du contexte est ajouté aux URLs relatives à une application locale (URLs qui commencent par '/').
• Les URLs relatives à l'application courante sont encodées afin de rajouter le jsessionid si nécessaire (cookies absent,...).
• Les paramètres ajoutés avec les balises <c:param/> sont ajoutés à l'URL.

Exemple

<!-- Ainsi le code suivant : --> <c:url value="/page.jsp?param=value"> <!-- Affichera pour le contexte "contextPath" : /contextPath/page.jsp?param=value ou si les cookies sont désactivé : /contextPath/page.jsp;jsessionid=XXXXXXXXXX?param=value --> <!-- Et le code suivant créera une variable "url" dans le scope page --> <c:url var="url" scope="page" value="/page.jsp?param=value"> <c:param name="id" value="1"/> </c:url> <!-- La variable de scope "url" contiendra donc : /contextPath/page.jsp?param=value&id=1 ou si les cookies sont désactivé : /contextPath/page.jsp;jsessionid=XXXXXXXXXX?param=value&id=1 -->

Afin de pouvoir être utilisées dans d'autres tags (notamment <jsp:include/>), les URLs ne sont pas