Utilisation des bibliothèques côté client dans AEM as a Cloud Service using-client-side-libraries

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 front-end dans l’archétype de projet AEM, la gestion de votre code front-end 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.

Que sont les bibliothèques côté client ? what-are-clientlibs

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 cliente un mécanisme de référence (par catégorie si nécessaire) et de diffusion de ces ressources.

AEM collecte le CSS et code 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.

Développement front-end pour AEM as a Cloud Service fed-for-aemaacs

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.

Structure du dossier de bibliothèques côté client clientlib-folders

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

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 :

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 :

Création de dossiers de bibliothèque côté client creating-clientlib-folders

Les bibliothèques clientes doivent être situées sous /apps. Cette règle 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.

Traitement des bibliothèques côté client serving-clientlibs

Une fois votre dossier de bibliothèques clientes configuré comme requis, vos bibliothèques clientes peuvent être demandées via proxy. Par exemple :

La propriété allowProxy vous permet de demander :

Chargement des bibliothèques clientes via HTL loading-via-htl

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.

Bibliothèques clientes dans l’instance de création et dans l’instance de publication clientlibs-author-publish

La plupart des bibliothèques clientes sont requises sur 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.

Gestion des bibliothèques clientes dans l’instance de création clientlibs-on-author

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.

Outils de débogage debugging-tools

AEM s’accompagne de plusieurs outils pour déboguer et tester des dossiers de bibliothèques clientes.

Détection de bibliothèques clientes discover-client-libraries

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 comprennent 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.

Affichage de la sortie générée see-generated-output

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.

Autres fonctionnalités du dossier de bibliothèque cliente additional-features

Il existe plusieurs autres fonctionnalités prises en charge par les dossiers de bibliothèques clientes 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.

Gestionnaire de bibliothèque HTML Adobe Granite html-library-manager

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.

Propriétés de dossier supplémentaires additional-folder-properties

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 :

Liaison vers des dépendances linking-to-dependencies

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">

Incorporation de code d’autres bibliothèques embedding-code-from-other-libraries

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 se révèle utile pour permettre l’accès aux bibliothèques stockées dans des zones sécurisées du référentiel.

Dossiers de bibliothèques clientes spécifiques à une application app-specific-client-library-folders

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 :

Utilisation de l’incorporation pour réduire les requêtes using-embedding-to-minimize-requests

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.

Chemins d’accès dans les fichiers CSS paths-in-css-files

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%;
}

Reportez-vous à la section Fichiers incorporés dans une sortie HTML see-embedded-files

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");

Utilisation de préprocesseurs using-preprocessors

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 :

Utilisation usage

Vous pouvez choisir de configurer les préprocesseurs par bibliothèque cliente ou à l’échelle du système.

La configuration d’un préprocesseur sur le nœud clientlibrary est prioritaire sur la configuration OSGI.

Format et exemples format-and-examples

Format format

config:= mode ":" processorName options*;
mode:= "default" | "min";
processorName := "none" | <name>;
options := ";" option;
option := name "=" value;

YUI Compressor pour la minification CSS et GCC pour JS yui-compressor-for-css-minification-and-gcc-for-js

cssProcessor: ["default:none", "min:yui"]
jsProcessor: ["default:none", "min:gcc;compilationLevel=advanced"]

Typescript pour le prétraitement, puis GCC pour la minification et l’obfuscation typescript-to-preprocess-and-then-gcc-to-minify-and-obfuscate

jsProcessor: [
   "default:typescript",
   "min:typescript",
   "min:gcc;obfuscate=true"
]

Options GCC supplémentaires additional-gcc-options

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 GCC.

Définition de l’outil de minification par défaut du système set-system-default-minifier

YUI est défini comme minificateur par défaut dans AEM. Pour modifier ce paramètre en GCC, procédez comme suit.