Les bibliothèques de balises Granite, CQ et Sling vous donnent accès à des fonctions spécifiques à utiliser dans le script JSP de vos modèles et composants.
La bibliothèque de balises Granite comporte des fonctions bien utiles.
Lorsque vous développez le script JSP d’un composant d’IU Granite, il est recommandé d’inclure le code suivant au début du script :
<%@include file="/libs/granite/ui/global.jsp"%>
Le fichier global déclare également la bibliothèque Sling.
<%@taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling" %>
La balise <ui:includeClientLib>
comprend une bibliothèque cliente html AEM, qui peut être un fichier js, un fichier CSS ou une bibliothèque de thèmes. Pour plusieurs inclusions de types différents, par exemple js et css, cette balise doit être utilisée plusieurs fois dans le fichier jsp. Cette balise est une enveloppe dite de commodité (convenience wrapper) utilisée autour de l’interface de service [com.adobe.granite.ui.clientlibs.HtmlLibraryManager](https://helpx.adobe.com/fr/experience-manager/6-5/sites/developing/using/reference-materials/javadoc/com/adobe/granite/ui/clientlibs/HtmlLibraryManager.html)
.
Elle présente les attributs suivants :
catégories - liste de catégories de lib client séparées par des virgules. Cela inclut toutes les bibliothèques JavaScript et CSS pour les catégories données. Le nom du thème est extrait de la requête.
Equivalent à: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeIncludes
thème - liste de catégories de lib client séparées par des virgules. Cela inclut toutes les bibliothèques (CSS et JS) relatives au thème pour les catégories données. Le nom du thème est extrait de la requête.
Equivalent à: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeThemeInclude
js - liste de catégories de lib client séparées par des virgules. Cela inclut toutes les bibliothèques JavaScript et CSS pour les catégories données.
Equivalent à: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeJsInclude
css - liste de catégories de lib client séparées par des virgules. Cela inclut toutes les bibliothèques CSS pour les catégories données.
Equivalent à: com.adobe.granite.ui.clientlibs.HtmlLibraryManager#writeCssInclude
thème - Un indicateur indiquant uniquement les bibliothèques thématiques ou non devrait être inclus. Si cet attribut est omis, les deux ensembles sont inclus. S’applique uniquement aux inclusions JS et CSS pures (pas aux catégories ni aux inclusions de thème).
La balise <ui:includeClientLib>
peut être utilisée comme suit dans un fichier jsp :
<%-- all: js + theme (theme-js + css) --%>
<ui:includeClientLib categories="cq.wcm.edit" />
<%-- only js libs --%>
<ui:includeClientLib js="cq.collab.calendar, cq.security" />
<%-- theme only (theme-js + css) --%>
<ui:includeClientLib theme="cq.collab.calendar, cq.security" />
<%-- css only --%>
<ui:includeClientLib css="cq.collab.calendar, cq.security" />
La bibliothèque de balises CQ comporte des fonctions bien utiles.
Pour utiliser la bibliothèque de balises CQ dans votre script, ce dernier doit commencer par le code suivant :
<%@taglib prefix="cq" uri="https://www.day.com/taglibs/cq/1.0" %>
Lorsque le fichier /libs/foundation/global.jsp
est inclus dans le script, la bibliothèque taglib est automatiquement déclarée.
Lorsque vous développez le script jsp d’un composant AEM, il est recommandé d’inclure le code en début de script :
<%@include file="/libs/foundation/global.jsp"%>
Il déclare les balises sling, CQ et jstl et expose les objets de script régulièrement utilisés définis par la balise <cq:defineObjects />
. Cela raccourcit et simplifie le code jsp de votre composant.
La balise <cq:text>
est une balise pratique qui génère le texte du composant dans un JSP.
Il présente les attributs facultatifs ci-dessous :
property - Nom de la propriété à utiliser. Le nom est relatif à la ressource actuelle.
valeur - Valeur à utiliser pour la sortie. Si cet attribut est présent, il annule l’utilisation de l’attribut property.
oldValue : valeur à utiliser pour la sortie diff. Si cet attribut est présent, il annule l’utilisation de l’attribut property.
escapeXml - Définit si les caractères <>, &, ' et " de la chaîne résultante doivent être convertis en codes d'entité de caractères correspondants. La valeur par défaut est false. Notez que l’échappement est appliqué après la mise en forme facultative.
format - Facultatif java.text.Format à utiliser pour le formatage du texte.
noDiff - Supprime le calcul d'une sortie diff, même si une information diff est présente.
tagClass - nom de classe CSS d’un élément qui entoure une sortie non vide. Si elle est vide, aucun élément n’est ajouté.
tagName : nom de l’élément qui entoure une sortie non vide. Cet attribut est défini, par défaut, sur DIV.
espace réservé : valeur par défaut à utiliser pour le texte vide ou nul en mode d’édition, c’est-à-dire l’espace réservé. Notez que la vérification par défaut est effectuée après l’échappement et la mise en forme facultatifs ; en d’autres termes, elle est écrite telle quelle dans la sortie. Elle est définie par défaut sur :
<div><span class="cq-text-placeholder">¶</span></div>
par défaut : valeur par défaut à utiliser pour le texte vide ou nul. Notez que la vérification par défaut est effectuée après l’échappement et la mise en forme facultatifs ; en d’autres termes, elle est écrite telle quelle dans la sortie.
Voici quelques exemples d’utilisation de la balise <cq:text>
dans un JSP :
<cq:text property="jcr:title" tagName="h2"/>
<cq:text property="jcr:description" tagName="p"/>
<cq:text value="<%= listItem.getTitle() %>" tagName="h4" placeholder="" />
<cq:text value="<%= listItem.getDescription() %>" tagName="p" placeholder=""/>
<cq:text property="jcr:title" value="<%= title %>" tagName="h3"/><%
} else if (type.equals("link")) {
%><cq:text property="jcr:title" value="<%= "\u00bb " + title %>" tagName="p" tagClass="link"/><%
} else if (type.equals("extralarge")) {
%><cq:text property="jcr:title" value="<%= title %>" tagName="h1"/><%
} else {
%><cq:text property="jcr:title" value="<%= title %>" tagName="h2"/><%
<cq:text property="jcr:description" placeholder="" tagName="small"/>
<cq:text property="tableData"
escapeXml="false"
placeholder="<img src=\"/libs/cq/ui/resources/0.gif\" class=\"cq-table-placeholder\" alt=\"\">"
/>
<cq:text property="text"/>
<cq:text property="image/jcr:description" placeholder="" tagName="small"/>
<cq:text property="text" tagClass="text"/>
La balise <cq:setContentBundle>
crée un contexte de localisation i18n et le stocke dans la variable de configuration javax.servlet.jsp.jstl.fmt.localizationContext
.
Elle présente les attributs suivants :
langue - Langue du paramètre régional pour laquelle récupérer le regroupement de ressources.
source : source à partir de laquelle le paramètre régional doit être pris. Les valeurs définies peuvent être les suivantes :
statique : le paramètre régional est extrait de l’ language
attribut si disponible, sinon du paramètre régional par défaut du serveur.
page - le paramètre régional est extrait de la langue de la page ou de la ressource active si elle est disponible, sinon de l’ language
attribut si disponible, sinon du paramètre régional par défaut du serveur.
request - le paramètre régional est extrait du paramètre régional de la demande ( request.getLocale()
).
auto : le paramètre régional est extrait de l’ language
attribut si disponible, sinon de la langue de la page ou de la ressource active si disponible, sinon de la requête.
Si l’attribut source
n’est pas défini :
Si l'attribut language
est défini, l'attribut source
prend par défaut la valeur "static
.
Si l'attribut language
n'est pas défini, l'attribut source
prend par défaut la valeur auto
.
Le "lot de contenu" peut être simplement utilisé par les balises JSTL <fmt:message>
standard. La recherche des messages par clés est une opération en deux temps :
SlingHttpServletRequest.getResourceBundle(Locale)
). La langue ou le paramètre régional de ce lot est défini par la langue et les attributs source de la balise <cq:setContentBundle>
.La balise <cq:setContentBundle>
peut être utilisée comme suit dans un fichier jsp.
Pour les pages qui définissent leur langue :
... %><cq:setContentBundle source="page"/><% %>
<div class="error"><fmt:message key="Hello"/>
</div> ...
Pour les pages personnalisées par l’utilisateur :
... %><cq:setContentBundle scope="request"/><% %>
<div class="error"><fmt:message key="Hello"/>
</div> ...
La balise <cq:include>
inclut une ressource dans la page active.
Elle présente les attributs suivants :
flush
path
resourceType
script
ignoreComponentHierarchy
Exemple:
<%@taglib prefix="cq" uri="https://www.day.com/taglibs/cq/1.0" %><%
%><div class="center">
<cq:include path="trail" resourceType="foundation/components/breadcrumb" />
<cq:include path="title" resourceType="foundation/components/title" />
<cq:include script="redirect.jsp"/>
<cq:include path="par" resourceType="foundation/components/parsys" />
</div>
Devriez-vous utiliser <%@ include file="myScript.jsp" %>
ou <cq:include script="myScript.jsp" %>
pour inclure un script ?
<%@ include file="myScript.jsp" %>
informe le compilateur JSP d’inclure un fichier complet dans le fichier actif. C’est comme si le contenu du fichier inclus était collé directement dans le fichier d’origine.<cq:include script="myScript.jsp">
, le fichier est inclus au moment de l’exécution.Devriez-vous utiliser <cq:include>
ou <sling:include>
?
<cq:include>
.<cq:include>
vous permet d’inclure directement des fichiers de script en fonction de leur nom lors de l’utilisation de l’attribut script. L’héritage du type de composant et de ressource est alors pris en compte. Généralement, cela s’avère plus simple que d’observer une stricte conformité avec la résolution de script de Sling à l’aide de sélecteurs et d’extensions.<cq:includeClientLib>
a été abandonné depuis AEM 5.6. <ui:includeClientLib>
devrait être utilisé à la place.
La balise <cq:includeClientLib>
comprend une bibliothèque cliente html AEM, qui peut être un js, un css ou une bibliothèque de thèmes. Pour plusieurs inclusions de types différents, par exemple js et css, cette balise doit être utilisée plusieurs fois dans le fichier jsp. Cette balise est une enveloppe dite de commodité (convenience wrapper) utilisée autour de l’interface de service com.day.cq.widget.HtmlLibraryManager
.
Elle présente les attributs suivants :
catégories - liste de catégories de lib client séparées par des virgules. Cela inclut toutes les bibliothèques JavaScript et CSS pour les catégories données. Le nom du thème est extrait de la requête.
Equivalent à: com.day.cq.widget.HtmlLibraryManager#writeIncludes
thème - liste de catégories de lib client séparées par des virgules. Cela inclut toutes les bibliothèques (CSS et JS) relatives au thème pour les catégories données. Le nom du thème est extrait de la requête.
Équivalent à : com.day.cq.widget.HtmlLibraryManager#
writeThemeInclude
js - liste de catégories de lib client séparées par des virgules. Cela inclut toutes les bibliothèques JavaScript et CSS pour les catégories données.
Equivalent à: com.day.cq.widget.HtmlLibraryManager#writeJsInclude
css - liste de catégories de lib client séparées par des virgules. Cela inclut toutes les bibliothèques CSS pour les catégories données.
Equivalent à: com.day.cq.widget.HtmlLibraryManager#writeCssInclude
thème - Un indicateur indiquant uniquement les bibliothèques thématiques ou non devrait être inclus. Si cet attribut est omis, les deux ensembles sont inclus. S’applique uniquement aux inclusions JS et CSS pures (pas aux catégories ni aux inclusions de thème).
La balise <cq:includeClientLib>
peut être utilisée comme suit dans un fichier jsp :
<%-- all: js + theme (theme-js + css) --%>
<cq:includeClientLib categories="cq.wcm.edit" />
<%-- only js libs --%>
<cq:includeClientLib js="cq.collab.calendar, cq.security" />
<%-- theme only (theme-js + css) --%>
<cq:includeClientLib theme="cq.collab.calendar, cq.security" />
<%-- css only --%>
<cq:includeClientLib css="cq.collab.calendar, cq.security" />
La balise <cq:defineObjects>
expose les objets de script suivants, régulièrement utilisés, qui peuvent être référencés par le développeur. Il expose également les objets définis par la balise <sling:defineObjects>
.
componentContext
component
currentDesign
currentPage
currentStyle
designer
editContext
pageManager
pageProperties
propriétés
resourceDesign
resourcePage
requestName
responseName
resourceName
nodeName
logName
resourceResolverName
slingName
componentContextName
editContextName
propertiesName
pageManagerName
currentPageName
resourcePageName
pagePropertiesName
componentName
designerName
currentDesignName
resourceDesignName
currentStyleName
Exemple
<%@page session="false" contentType="text/html; charset=utf-8" %><%
%><%@ page import="com.day.cq.wcm.api.WCMMode" %><%
%><%@taglib prefix="cq" uri="https://www.day.com/taglibs/cq/1.0" %><%
%><cq:defineObjects/>
Lorsque le fichier /libs/foundation/global.jsp
est inclus dans le script, la balise <cq:defineObjects />
est automatiquement incluse.
La balise <cq:requestURL>
écrit l’URL de requête actuelle à JspWriter. Les deux balises <cq:addParam>
et <cq:removeParam>
peuvent être utilisées dans le corps de cette balise pour modifier l’URL de requête active avant qu’elle ne soit écrite.
Cela vous permet de créer des liens vers la page en cours avec des paramètres variables. Cela vous permet, par exemple, de transformer la requête :
mypage.html?mode=view&query=something
en mypage.html?query=something
.
L'utilisation de addParam
ou removeParam
ne modifie que l'occurrence du paramètre donné, tous les autres paramètres ne sont pas affectés.
<cq:requestURL>
n’a aucun attribut.
Exemples :
<a href="<cq:requestURL><cq:removeParam name="language"/></cq:requestURL>">remove filter</a>
<a title="filter results" href="<cq:requestURL><cq:addParam name="language" value="${bucket.value}"/></cq:requestURL>">${label} (${bucket.count})</a>
La balise <cq:addParam>
ajoute un paramètre de requête avec le nom et la valeur donnés à la balise <cq:requestURL>
qui l'entoure.
Elle présente les attributs suivants :
name
value
Exemple:
<a title="filter results" href="<cq:requestURL><cq:addParam name="language" value="${bucket.value}"/></cq:requestURL>">${label} (${bucket.count})</a>
La balise <cq:removeParam>
supprime un paramètre de requête avec le nom et la valeur donnés de la balise <cq:requestURL>
qui l'entoure. Si aucune valeur n’est indiquée, tous les paramètres portant le nom spécifié sont supprimés.
Elle présente les attributs suivants :
name
Exemple :
<a href="<cq:requestURL><cq:removeParam name="language"/></cq:requestURL>">remove filter</a>
La bibliothèque de balises Sling comporte des fonctions Sling bien utiles.
Lorsque vous utilisez la bibliothèque de balises Sling dans votre script, ce dernier doit commencer par le code suivant :
<%@ taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling/1.0" %>
Lorsque le fichier /libs/foundation/global.jsp
est inclus dans le script, la bibliothèque sling taglib est automatiquement déclarée.
La balise <sling:include>
inclut une ressource dans la page active.
Elle présente les attributs suivants :
vider
ressource
chemin
resourceType
replaceSelectors
addSelectors
replaceSuffix
La résolution de la ressource et du script inclus avec la balise <sling:include>
est identique à celle d’une résolution d’URL sling normale. Par défaut, les sélecteurs, l’extension, etc. de la requête en cours sont également utilisés pour le script inclus. Ils peuvent être modifiés à l’aide des attributs de balise : par exemple, replaceSelectors="foo.bar"
vous permet de remplacer les sélecteurs.
Exemples :
<div class="item"><sling:include path="<%= pathtoinclude %>"/></div>
<sling:include resource="<%= par %>"/>
<sling:include addSelectors="spool"/>
<sling:include resource="<%= par %>" resourceType="<%= newType %>"/>
<sling:include resource="<%= par %>" resourceType="<%= newType %>"/>
<sling:include replaceSelectors="content" />
La balise <sling:defineObjects>
expose les objets de script suivants, régulièrement utilisés, qui peuvent être référencés par le développeur :
slingRequest
slingResponse
resourceResolver
.sling
ressource
currentNode
log
Fournit un enregistreur SLF4J pour consigner des événements dans le système de journalisation Sling depuis des scripts, par exemple : log.info("Exécution de mon script").
Il possède les attributs suivants :
requestName
responseName
nodeName
l ogName resourceResolverName
slingName
Exemple :
<%@page session="false" %><%
%><%@page import="com.day.cq.wcm.foundation.forms.ValidationHelper"%><%
%><%@taglib prefix="sling" uri="https://sling.apache.org/taglibs/sling/1.0" %><%
%><sling:defineObjects/>
La bibliothèque de balises standard des pages JavaServer contient beaucoup de balises utiles et standard. Les balises de base, de formatage et de fonctions sont définies par /libs/foundation/global.jsp
comme le montre le fragment de code suivant.
<%@taglib prefix="c" uri="https://java.sun.com/jsp/jstl/core" %>
<%@taglib prefix="fmt" uri="https://java.sun.com/jsp/jstl/fmt" %>
<%@taglib prefix="fn" uri="https://java.sun.com/jsp/jstl/functions" %>
Après avoir importé le fichier /libs/foundation/global.jsp
comme décrit précédemment, vous pouvez utiliser les préfixes c
, fmt
et fn
pour accéder à ces balises. La documentation officielle de la JSTL est disponible ici.