Les expériences digitales reposent largement sur un traitement côté client piloté par un code JavaScript et CSS complexe. Les bibliothèques côté client (clientlibs) vous permettent d’organiser et de stocker de manière centrale ces bibliothèques côté client dans le référentiel. Associée au processus de génération frontale dans l’archétype de projet AEM, la gestion de votre code frontal pour votre projet AEM devient simple.
Les avantages de l’utilisation de bibliothèques clientlibs dans AEM incluent les suivants :
Les bibliothèques côté client sont la solution intégrée pour la diffusion de code CSS et JavaScript à partir d’AEM.
Les développeurs front-end qui créent du code CSS et JavaScript pour les projets AEM doivent également se familiariser avec l’archétype de projet AEM et son processus de création frontale automatisé.
Les sites requièrent du code JavaScript et CSS, ainsi que des ressources statiques telles que des icônes et des polices web, pour être traités côté client. Une bibliothèque client constitue le mécanisme d’AEM utilisé pour référencer (par catégorie si nécessaire) et traiter ces ressources.
AEM collecte le code CSS et JavaScript du site dans un seul fichier, à un emplacement central, afin de s’assurer qu’une seule copie d’une ressource est incluse dans la sortie HTML. Cela optimise l’efficacité de la diffusion et permet à ces ressources d’être conservées de façon centralisée dans le référentiel par le biais d’un proxy, en assurant la sécurité de l’accès.
Toutes les ressources JavaScript, CSS et autres ressources front-end doivent être conservées dans le module ui.frontend de l’archétype de projet AEM. La flexibilité de l’archétype vous permet d’utiliser vos outils web modernes de choix pour créer et gérer ces ressources.
L’archétype peut ensuite compiler les ressources dans des fichiers CSS et JS uniques, en les incorporant automatiquement dans un cq:clientLibraryFolder
dans le référentiel.
Un dossier de bibliothèques côté client est un nœud de référentiel de type cq:ClientLibraryFolder
. Sa définition au format CND est :
[cq:ClientLibraryFolder] > sling:Folder
- dependencies (string) multiple
- categories (string) multiple
- embed (string) multiple
- channels (string) multiple
cq:ClientLibraryFolder
peuvent être placés n’importe où dans la sous-arborescence /apps
du référentiel.categories
du nœud pour identifier les catégories de bibliothèque auxquelles il appartient.Chaque dossier cq:ClientLibraryFolder
est rempli avec un jeu de fichiers JS et/ou CSS, ainsi que quelques fichiers annexes (voir ci-dessous). Les propriétés importantes du dossier cq:ClientLibraryFolder
sont configurées comme suit :
allowProxy
: étant donné que toutes les bibliothèques clientes doivent être stockées sous apps
, cette propriété permet d’accéder aux bibliothèques clientes par le biais d’un servlet proxy. Consultez la section Rechercher un dossier de bibliothèques clientes et utiliser le servlet des bibliothèques clientes du proxy ci-dessous.categories
: identifie les catégories dans lesquelles se trouve le jeu de fichiers JS et/ou CSS de ce dossier cq:ClientLibraryFolder
. La propriété categories
comportant plusieurs valeurs, elle permet à un dossier de bibliothèques d’appartenir à plusieurs catégories (voir ci-dessous pour savoir en quoi cela peut se révéler utile).Si le dossier de bibliothèques clientes contient un ou plusieurs fichiers sources qui, à l’exécution, sont fusionnés en un seul fichier JS et/ou CSS. Le nom du fichier généré est le nom de nœud avec l’extension .js
ou .css
. Par exemple, le nœud de bibliothèque nommé cq.jquery
donne le nom de fichier généré cq.jquery.js
ou cq.jquery.css
.
Les dossiers de bibliothèques clientes contiennent les éléments suivants :
js.txt
et/ou un fichier css.txt
qui identifie les fichiers sources à fusionner dans les fichiers JS et/ou CSS générésLes bibliothèques clientes doivent être situées sous /apps
. Cela permet en effet de mieux isoler le code du contenu et de la configuration.
Pour que les bibliothèques clientes situées sous /apps
soient accessibles, un servlet proxy est utilisé. Les listes de contrôle d’accès (ACL) sont toujours appliquées sur le dossier de bibliothèques clientes, mais le servlet permet la lecture du contenu via /etc.clientlibs/
si la propriété allowProxy
est définie sur true
.
https://<host>:<port>/crx/de
)./apps
et cliquez sur Créer > Créer un nœud.cq:ClientLibraryFolder
. Cliquez sur OK, puis sur Enregistrer tout.cq:ClientLibraryFolder
, ajoutez la propriété suivante, puis cliquez sur Enregistrer tout :
categories
/etc.clientlibs
, sélectionnez le nœud cq:ClientLibraryFolder
, ajoutez la propriété suivante, puis cliquez sur Enregistrer tout :
allowProxy
true
resources
sous le dossier de bibliothèques clientes.
resources
, elles ne peuvent pas être référencées sur une instance de publication.js.txt
: utilisez ce nom de fichier pour générer un fichier JavaScript.css.txt
: utilisez ce nom de fichier pour générer une feuille de style en cascade (CSS).#base=*[root]*
[root]
par le chemin d’accès au dossier contenant les fichiers sources, par rapport au fichier TXT. Utilisez, par exemple, le texte suivant lorsque les fichiers sources se trouvent dans le même dossier que le fichier TXT :
#base=.
cq:ClientLibraryFolder
:
#base=mobile
#base=[root]
, indiquez les chemins d’accès des fichiers sources par rapport à la racine. Placez chaque nom de fichier sur une ligne distincte.Une fois votre dossier de bibliothèques clientes configuré comme requis, vos bibliothèques clientes peuvent être demandées via proxy. Par exemple :
/apps/myproject/clientlibs/foo
./apps/myprojects/clientlibs/foo/resources/icon.png
.La propriété allowProxy
vous permet de demander :
/etc.clientlibs/myprojects/clientlibs/foo.js
./etc.clientlibs/myprojects/clientlibs/foo/resources/icon.png
.Une fois que vos bibliothèques clientes sont stockées et gérées dans leur dossier de bibliothèques clientes, il est possible d’y accéder via HTL.
Les bibliothèques clientes sont chargées à l’aide d’un modèle d’assistance fourni par AEM, accessible via data-sly-use
. Des modèles d’assistance sont disponibles dans ce fichier, qui peut être appelé via data-sly-call
:
Chaque modèle d’assistance exige une option categories
pour référencer les bibliothèques clientes souhaitées. Cette option peut être un tableau de valeurs de chaîne ou une chaîne contenant une liste de valeurs séparées par des virgules.
Pour plus d’informations sur le chargement de bibliothèques clientes via HTL, consultez la documentation HTL.
La plupart des bibliothèques clientes sont requises dans l’instance de publication AEM. En d’autres termes, la plupart d’entre elles ont pour objectif de produire l’expérience de l’utilisateur final par rapport au contenu. Pour les bibliothèques clientes dans les instances de publication, les outils de création front-end peuvent être utilisés et déployés via des dossiers de bibliothèque cliente, comme décrit ci-dessus.
Cependant, il peut arriver que des bibliothèques clientes soient nécessaires pour personnaliser l’expérience de création. Par exemple, la personnalisation d’une boîte de dialogue peut nécessiter le déploiement de petits fragments de code CSS ou JS dans l’instance de création AEM.
Si vous devez utiliser des bibliothèques clientes dans l’instance de création, vous pouvez créer vos bibliothèques clientes sous /apps
en utilisant les mêmes méthodes que pour la publication, mais créez-les directement sous /apps/.../clientlibs/foo
au lieu de créer un projet entier pour les gérer.
Vous pouvez ensuite vous « rattacher » à l’instance JS de création en ajoutant vos bibliothèques clientes à une catégorie de bibliothèque cliente prête à l’emploi.
AEM s’accompagne de plusieurs outils pour déboguer et tester des dossiers de bibliothèques clientes.
Le composant /libs/cq/granite/components/dumplibs/dumplibs
génère une page d’informations sur tous les dossiers de bibliothèques clientes du système. Le nœud /libs/granite/ui/content/dumplibs
contient le composant comme type de ressource. Pour ouvrir la page, utilisez l’URL suivante (en changeant l’hôte et le port selon les besoins) :
https://<host>:<port>/libs/granite/ui/content/dumplibs.test.html
Les informations incluent le chemin et le type de bibliothèque (CSS ou JS), ainsi que les valeurs des attributs de bibliothèque, tels que les catégories et les dépendances. Les tableaux suivants de la page affichent les bibliothèques dans chaque catégorie et canal.
Le composant dumplibs
comprend un sélecteur de test qui affiche le code source généré pour les balises ui:includeClientLib
. La page contient du code pour différentes combinaisons des attributs js, css et themed.
dumplibs.html
, cliquez sur le lien sous Cliquez ici pour les résultats du test.http://<host>:<port>/libs/granite/ui/content/dumplibs.html
categories
de la bibliothèque cliente, puis cliquez sur Envoyer la requête.D’autres fonctionnalités sont prises en charge par les dossiers de bibliothèque cliente dans AEM. Toutefois, ces fonctionnalités ne sont pas requises dans AEM as a Cloud Service et, par conséquent, leur utilisation est découragée. À des fins d’exhaustivité, elles sont répertoriées ici.
Ces fonctionnalités supplémentaires des dossiers de bibliothèque cliente ne sont pas requises dans AEM as a Cloud Service et leur utilisation est donc déconseillée. À des fins d’exhaustivité, elles sont répertoriées ici.
D’autres paramètres de bibliothèque cliente peuvent être contrôlés par le biais du panneau du Gestionnaire de bibliothèque HTML Adobe Granite de la console système à l’adresse https://<host>:<port>/system/console/configMgr
.
Les autres propriétés de dossier permettent entre autres de contrôler les dépendances et les incorporations, mais ne sont généralement plus nécessaires et leur utilisation est déconseillée :
dependencies
: il s’agit d’une liste d’autres catégories de bibliothèques clientes dont dépend ce dossier de catégories. Par exemple, étant donné deux nœuds cq:ClientLibraryFolder
, F
et G
, si un fichier du nœud F
nécessite un autre fichier du nœud G
pour fonctionner correctement, au moins l’une des propriétés categories
de G
doit figurer parmi les propriétés dependencies
de F
.embed
: utilisé pour incorporer du code d’autres bibliothèques. Si le nœud F
incorpore les nœuds G
et H
, le code HTML qui en résulte est une concentration du contenu des nœud G
et H
.Lorsque le code de votre dossier de bibliothèques clientes fait référence à d’autres bibliothèques, identifiez ces dernières en tant que dépendances. La balise ui:includeClientLib
qui fait référence à votre dossier de bibliothèques clientes fait en sorte que le code HTML contienne un lien vers le fichier de bibliothèque généré, ainsi que les dépendances.
Les dépendances doivent être un autre nœud cq:ClientLibraryFolder
. Pour identifier les dépendances, ajoutez une propriété à votre nœud cq:ClientLibraryFolder
avec les attributs suivants :
Par exemple, /etc/clientlibs/myclientlibs/publicmain
comporte une dépendance sur la bibliothèque cq.jquery
. La page qui fait référence à la bibliothèque cliente principale génère un fichier HTML qui comprend le code suivant :
<script src="/etc/clientlibs/foundation/cq.jquery.js" type="text/javascript">
<script src="/etc/clientlibs/mylibs/publicmain.js" type="text/javascript">
Vous pouvez incorporer du code d’une bibliothèque cliente dans une autre bibliothèque cliente. Au moment de l’exécution, les fichiers JS et CSS générés de la bibliothèque d’intégration incluent le code de la bibliothèque incorporée.
L’incorporation de code s’avère utile pour permettre l’accès aux bibliothèques stockées dans des zones sécurisées du référentiel.
Il est conseillé de conserver tous les fichiers associés à une application dans leur dossier d’application sous /apps
. Il est également recommandé d’empêcher les internautes d’accéder au dossier /apps
. Pour répondre à ces deux exigences, créez sous /etc
un dossier de bibliothèques clientes qui incorpore la bibliothèque cliente qui est située sous /apps
.
Utilisez la propriété categories pour identifier le dossier de bibliothèque cliente à incorporer. Pour incorporer la bibliothèque, ajoutez une propriété au nœud cq:ClientLibraryFolder
d’intégration à l’aide des attributs de propriété suivants :
cq:ClientLibraryFolder
à incorporer.Dans certains cas, il se peut que le code HTML final généré pour une page standard par votre instance de publication comporte un nombre relativement important d’éléments <script>
.
Dans ce cas, il peut être utile de combiner tout le code de bibliothèque cliente requis dans un seul fichier afin de réduire le nombre de requêtes aller-retour lors du chargement de la page. Pour ce faire, vous pouvez incorporer (embed
) les bibliothèques requises dans la bibliothèque cliente spécifique à l’application à l’aide de la propriété du nœud cq:ClientLibraryFolder
.
Lorsque vous incorporez des fichiers CSS, le code CSS généré utilise des chemins d’accès aux ressources qui sont relatifs à la bibliothèque d’intégration. Par exemple, la bibliothèque publiquement accessible /etc/client/libraries/myclientlibs/publicmain
incorpore la bibliothèque cliente /apps/myapp/clientlib
:
Le fichier main.css
contient le style suivant :
body {
padding: 0;
margin: 0;
background: url(images/bg-full.jpg) no-repeat center top;
width: 100%;
}
Le fichier CSS généré par le nœud publicmain
contient le style suivant, en utilisant l’URL de l’image d’origine :
body {
padding: 0;
margin: 0;
background: url(../../../apps/myapp/clientlib/styles/images/bg-full.jpg) no-repeat center top;
width: 100%;
}
Pour remonter à l’origine du code incorporé, ou vous assurer que les bibliothèques clientes incorporées produisent les résultats escomptés, vous pouvez afficher les noms des fichiers incorporés au moment de l’exécution. Pour afficher les noms de fichiers, ajoutez le paramètre debugClientLibs=true
à l’URL de votre page web. La bibliothèque générée contient des instructions @import
au lieu du code incorporé.
Dans l’exemple de la section Incorporation de code d’autres bibliothèques, le dossier de bibliothèques clientes /etc/client/libraries/myclientlibs/publicmain
intègre le dossier /apps/myapp/clientlib
. L’ajout du paramètre à la page web génère le lien suivant dans le code source de la page web :
<link rel="stylesheet" href="/etc/clientlibs/mycientlibs/publicmain.css">
L’ouverture du fichier publicmain.css
fait apparaître le code suivant :
@import url("/apps/myapp/clientlib/styles/main.css");
?debugClientLibs=true
AEM autorise les préprocesseurs enfichables et prend en charge YUI Compressor pour CSS et JavaScript, ainsi que Google Closure Compiler (GCC) pour JavaScript avec YUI défini comme préprocesseur par défaut d’AEM.
Les préprocesseurs enfichables permettent une utilisation flexible, notamment :
Par défaut, AEM utilise le YUI Compressor. Pour connaître la liste des problèmes connus, consultez la documentation GitHub de YUI Compressor. Le passage au compresseur GCC pour des clientlibs spécifiques peut résoudre certains problèmes observés lors de l’utilisation de YUI.
Ne placez pas de bibliothèque minimisée dans une bibliothèque cliente. Fournissez plutôt la bibliothèque brute et, si une minification est requise, utilisez les options des préprocesseurs.
Vous pouvez choisir de configurer les préprocesseurs par bibliothèque cliente ou à l’échelle du système.
cssProcessor
et jsProcessor
sur le nœud clientlibrary (bibliothèque cliente).La configuration d’un préprocesseur sur le nœud clientlibrary est prioritaire sur la configuration OSGI.
config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;
cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]
jsProcessor: [
"default:typescript",
"min:typescript",
"min:gcc;obfuscate=true"
]
failOnWarning (defaults to "false")
languageIn (defaults to "ECMASCRIPT5")
languageOut (defaults to "ECMASCRIPT5")
compilationLevel (defaults to "simple") (can be "whitespace", "simple", "advanced")
Pour plus d’informations sur les options GCC, consultez la documentation de GCC.
YUI est défini comme minificateur par défaut dans AEM. Pour modifier ce paramètre en GCC, procédez comme suit.
http://<host>:<portY/system/console/configMgr
.min:gcc
.
min:gcc;obfuscate=true
.