Bibliothèques clientes et processus front-end

Découvrez comment les bibliothèques côté client ou clientlibs sont utilisées pour déployer et gérer CSS et JavaScript pour une mise en oeuvre de sites Adobe Experience Manager (AEM). Ce tutoriel explique également comment ui.frontend module, un découplé webpack , peut être intégré au processus de génération de bout en bout.

Prérequis

Examinez les outils et les instructions requis pour configurer une environnement de développement local.

Il est également recommandé de consulter la section Principes de base des composants tutoriel pour comprendre les principes de base des bibliothèques et AEM côté client.

Projet de démarrage

Consultez le code de ligne de base sur lequel le tutoriel s’appuie :

1. Consultez la section tutorial/client-side-libraries-start branche à partir de GitHub

   $ cd aem-guides-wknd
   $ git checkout tutorial/client-side-libraries-start
   

2. Déployez la base de code sur une instance d’AEM locale à l’aide de vos compétences Maven :

   $ mvn clean install -PautoInstallSinglePackage
   

   REMARQUE

   Si vous utilisez AEM version 6.5 ou 6.4, ajoutez la variable classic profile à n’importe quelle commande Maven.

   $ mvn clean install -PautoInstallSinglePackage -Pclassic
   

Vous pouvez toujours afficher le code terminé sur GitHub ou extraire le code localement en passant à la branche tutorial/client-side-libraries-solution.

Objectifs

1. Découvrez comment les bibliothèques côté client sont incluses sur une page via un modèle modifiable.
2. Découvrez comment utiliser le ui.frontend et un serveur de développement webpack pour le développement front-end dédié.
3. Comprenez le workflow de bout en bout de la diffusion de code CSS et JavaScript compilé sur une implémentation de Sites.

Ce que vous allez construire

Dans ce chapitre, vous ajoutez quelques styles de ligne de base pour le site WKND et le modèle de page d’article afin de rapprocher l’implémentation de la Modèles de conception d’interface utilisateur. Vous utilisez un workflow front-end avancé pour intégrer un projet webpack dans une bibliothèque cliente AEM.

Page d’article avec des styles de ligne de base appliqués

Contexte

Les bibliothèques côté client offrent un mécanisme d’organisation et de gestion des fichiers CSS et JavaScript nécessaires à une mise en oeuvre AEM Sites. Les objectifs de base des bibliothèques côté client ou clientlibs sont les suivants :

1. Stocker les fichiers CSS/JS dans des petits fichiers discrets pour faciliter le développement et la maintenance
2. Gestion organisée des dépendances des structures tierces
3. Réduisez le nombre de requêtes côté client en concaténant CSS/JS en une ou deux requêtes.

Vous trouverez plus d’informations sur l’utilisation des bibliothèques côté client ici.

Les bibliothèques côté client présentent certaines limites. Le plus notable est une prise en charge limitée des langages front-end populaires tels que Sass, LESS et TypeScript. Dans le tutoriel, regardons comment le ui.frontend peut vous aider à résoudre ce problème.

Déployez la base de code de démarrage sur une instance d’AEM locale et accédez à http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html. Cette page n’a pas de style. Implémentons des bibliothèques côté client pour la marque WKND afin d’ajouter du code CSS et JavaScript à la page.

Organisation des bibliothèques côté client

Explorons ensuite l’organisation des clientlibs générées par la variable AEM Archétype de projet.

Diagramme de haut niveau Organisation de la bibliothèque côté client et inclusion de page

1. À l’aide de VSCode ou d’un autre IDE, ouvrez le ui.apps module .

2. Développer le chemin /apps/wknd/clientlibs pour afficher les bibliothèques clientes générées par l’archétype.

   

   Dans la section ci-dessous, ces clientlibs sont examinées plus en détail.

3. Le tableau suivant résume les bibliothèques clientes. Plus d’informations sur y compris les bibliothèques clientes se trouvent ici.

   Nom	Description	Remarques
   clientlib-base	Niveau de base du code CSS et JavaScript nécessaire au fonctionnement du site WKND	incorpore les bibliothèques clientes des composants principaux.
   clientlib-grid	Génère le CSS nécessaire pour Mode Mise en page au travail.	Les points d’arrêt pour mobiles/tablettes peuvent être configurés ici.
   clientlib-site	Contient un thème spécifique au site WKND	Générée par le ui.frontend module
   clientlib-dependencies	Incorpore toutes les dépendances tierces.	Générée par le ui.frontend module

4. Observez que clientlib-site et clientlib-dependencies sont ignorées du contrôle source. Cela se fait par conception, car elles sont générées au moment de la création par la variable ui.frontend module .

Mise à jour des styles de base

Mettez ensuite à jour les styles de base définis dans le ui.frontend module . Les fichiers de la variable ui.frontend générer le module clientlib-site et clientlib-dependecies bibliothèques qui contiennent le thème Site et toutes les dépendances tierces.

Les bibliothèques côté client ne prennent pas en charge les langues plus avancées telles que Sass ou TypeScript. Il existe plusieurs outils open source, tels que NPM et webpack qui accélèrent et optimisent le développement front-end. L’objectif de la variable ui.frontend est de pouvoir utiliser ces outils pour gérer la plupart des fichiers source front-end.

1. Ouvrez le ui.frontend et accédez à src/main/webpack/site.

2. Ouvrez le fichier main.scss

   

   main.scss est le point d’entrée des fichiers Sass dans la variable ui.frontend module . Il comprend la variable _variables.scss qui contient une série de variables de marque à utiliser dans différents fichiers Sass du projet. Le _base.scss est également inclus et définit certains styles de base pour les éléments de HTML. Une expression régulière inclut les styles pour les styles de composants individuels sous src/main/webpack/components. Une autre expression régulière inclut les fichiers sous src/main/webpack/site/styles.

3. Inspectez le fichier main.ts. Elle comprend main.scss et une expression régulière pour collecter n’importe quelle .js ou .ts fichiers du projet. Ce point d’entrée est utilisé par la variable fichiers de configuration webpack comme point d’entrée pour l’ensemble ui.frontend module .

4. Inspect des fichiers situés sous src/main/webpack/site/styles:

   

   Ces styles de fichiers pour les éléments globaux du modèle, tels que le conteneur En-tête, Pied de page et contenu principal. Les règles CSS de ces fichiers ciblent différents éléments de HTML. header, main, et footer. Ces éléments de HTML ont été définis par des stratégies dans le chapitre précédent. Pages et modèles.

5. Développez l’objet components Dossier sous src/main/webpack et inspectez les fichiers.

   

   Chaque fichier est mappé à un composant principal comme Composant d’accordéon. Chaque composant principal est créé avec Block Element Modifier ou notation BEM pour faciliter le ciblage de classes CSS spécifiques avec des règles de style. Les fichiers sous /components ont été bloqués par l’archétype de projet AEM avec les différentes règles BEM pour chaque composant.

6. Téléchargement des styles de base WKND wknd-base-styles-src-v3.zip et unzip le fichier .

   

   Pour accélérer le tutoriel, plusieurs fichiers Sass qui implémentent la marque WKND en fonction des composants principaux et de la structure du modèle de page d’article sont fournis.

7. Remplacer le contenu de ui.frontend/src avec les fichiers de l’étape précédente. Le contenu du fichier zip doit remplacer les dossiers suivants :

   /src/main/webpack
            /components
            /resources
            /site
            /static
   

   

   Inspect les fichiers modifiés pour afficher les détails de l’implémentation du style WKND.

Inspect de l’intégration ui.frontend

Élément d’intégration clé intégré à ui.frontend module, aem-clientlib-generator prend les artefacts CSS et JS compilés d’un projet webpack/npm et les transforme en bibliothèques côté client AEM.

L’archétype de projet AEM configure automatiquement cette intégration. Ensuite, découvrez comment cela fonctionne.

1. Ouvrez un terminal de ligne de commande et installez le ui.frontend à l’aide du module npm install command :

   $ cd ~/code/aem-guides-wknd/ui.frontend
   $ npm install
   

   REMARQUE

   npm install run n’est nécessaire qu’une seule fois, comme après un nouveau clone ou une nouvelle génération du projet.

2. Démarrez le serveur de développement webpack dans watch en exécutant la commande suivante :

   $ npm run watch
   

3. Cette opération compile les fichiers sources à partir de la fonction ui.frontend et synchronise les modifications avec AEM à l’adresse http://localhost:4502

   + jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js
   + jcr_root/apps/wknd/clientlibs/clientlib-site/js
   + jcr_root/apps/wknd/clientlibs/clientlib-site
   + jcr_root/apps/wknd/clientlibs/clientlib-dependencies/css.txt
   + jcr_root/apps/wknd/clientlibs/clientlib-dependencies/js.txt
   + jcr_root/apps/wknd/clientlibs/clientlib-dependencies
   http://admin:admin@localhost:4502 > OK
   + jcr_root/apps/wknd/clientlibs/clientlib-site/css
   + jcr_root/apps/wknd/clientlibs/clientlib-site/js/site.js
   http://admin:admin@localhost:4502 > OK
   

4. La commande npm run watch renseigne finalement la variable clientlib-site et clientlib-dependencies dans le ui.apps qui est ensuite synchronisé automatiquement avec AEM.

   REMARQUE

   Il y a également un npm run prod qui minimise les éléments JS et CSS. Il s’agit de la compilation standard chaque fois que la version de webpack est déclenchée via Maven. Plus d’informations sur module ui.frontend se trouve ici.

5. Inspect du fichier site.css sous ui.frontend/dist/clientlib-site/site.css. Il s’agit de la page CSS compilée basée sur les fichiers source Sass.

   

6. Inspectez le fichier ui.frontend/clientlib.config.js. Il s’agit du fichier de configuration d’un module externe npm, aem-clientlib-generator qui transforme le contenu de /dist dans une bibliothèque cliente et la déplace vers le ui.apps module .

7. Inspect du fichier site.css dans le ui.apps module à ui.apps/src/main/content/jcr_root/apps/wknd/clientlibs/clientlib-site/css/site.css. Il doit s’agir d’une copie identique de la variable site.css du fichier ui.frontend module . Maintenant qu'il est dans ui.apps il peut être déployé sur AEM.

   

   REMARQUE

   Depuis clientlib-site est compilé au cours de la création, à l’aide de l’une des méthodes suivantes : npm ou maven, il peut être ignoré en toute sécurité du contrôle source dans la variable ui.apps module . Inspect .gitignore fichier sous ui.apps.

8. Ouvrez l’article LA Skatepark dans AEM à l’adresse : http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html.

   

   Vous devriez maintenant voir les styles mis à jour pour l’article. Vous devrez peut-être effectuer une actualisation difficile afin d’effacer les fichiers CSS mis en cache par le navigateur.

   Ça commence à ressembler beaucoup plus aux maquettes !

   REMARQUE

   Les étapes ci-dessus pour créer et déployer le code ui.frontend vers AEM sont exécutées automatiquement lorsqu’une version Maven est déclenchée à la racine du projet. mvn clean install -PautoInstallSinglePackage.

Apporter un changement de style

Apportez ensuite une légère modification au ui.frontend pour afficher le module npm run watch Déployez automatiquement les styles sur l’instance d’AEM locale.

1. À partir de, la variable ui.frontend ouvrez le fichier : ui.frontend/src/main/webpack/site/_variables.scss.

2. Mettez à jour le $brand-primary variable de couleur :

   //== variables.css
   
   //== Brand Colors
   $brand-primary:          $pink;
   

   Enregistrez les modifications.

3. Revenez au navigateur et actualisez la page AEM pour afficher les mises à jour :

   

4. Rétablissement de la modification sur le $brand-primary coloration et arrêt de la création du webpack à l’aide de la commande CTRL+C.

Inclusion de page et de modèle

Examinons ensuite la manière dont les bibliothèques clientes sont référencées dans la page AEM. Une bonne pratique courante dans le développement web consiste à inclure CSS dans l’en-tête de HTML. <head> et JavaScript avant de fermer </body> balise .

1. Accédez au modèle Page d’article à l’adresse http://localhost:4502/editor.html/conf/wknd/settings/wcm/templates/article-page/structure.html

2. Cliquez sur le bouton Informations sur la page et dans le menu, sélectionnez Stratégie de page pour ouvrir le Stratégie de page boîte de dialogue.

   

   Informations sur la page > Stratégie de page

3. Notez que les catégories pour wknd.dependencies et wknd.site sont répertoriées ici. Par défaut, les clientlibs configurées via la stratégie de page sont fractionnées afin d’inclure le CSS dans l’en-tête de page et le JavaScript à la fin du corps. Vous pouvez lister explicitement le code JavaScript clientlib à charger dans l’en-tête de la page. C’est le cas pour wknd.dependencies.

   

   REMARQUE

   Il est également possible de référencer la variable wknd.site ou wknd.dependencies directement à partir du composant de page, à l’aide de la méthode customheaderlibs.html ou customfooterlibs.html script. L’utilisation du modèle offre une certaine flexibilité dans le sens où vous pouvez choisir les clientlibs utilisées par modèle. Par exemple, si vous disposez d’une bibliothèque JavaScript volumineuse qui ne sera utilisée que sur un modèle sélectionné.

4. Accédez au LA Skateparks page créée à l’aide de Modèle de page d’article: http://localhost:4502/editor.html/content/wknd/us/en/magazine/guide-la-skateparks.html.

5. Cliquez sur le bouton Informations sur la page et dans le menu, sélectionnez Afficher comme publié(e) pour ouvrir la page d’article en dehors de l’éditeur d’AEM.

   

6. Afficher la source de la page de http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled et vous devriez pouvoir voir les références clientlib suivantes dans le <head>:

   <head>
   ...
   <script src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.js"></script>
   <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.lc-d41d8cd98f00b204e9800998ecf8427e-lc.min.css" type="text/css">
   <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-78fb9cea4c3a2cc17edce2c2b32631e2-lc.min.css" type="text/css">
   ...
   </head>
   

   Notez que les clientlibs utilisent le proxy. /etc.clientlibs point de terminaison . Vous devriez également constater que la bibliothèque cliente suivante inclut au bas de la page :

   ...
   <script src="/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-7157cf8cb32ed66d50e4e49cdc50780a-lc.min.js"></script>
   <script src="/etc.clientlibs/wknd/clientlibs/clientlib-base.lc-53e6f96eb92561a1bdcc1cb196e9d9ca-lc.min.js"></script>
   ...
   </body>
   

   REMARQUE

   Pour AEM 6.5/6.4, les bibliothèques côté client ne sont pas automatiquement réduites. Consultez la documentation relative à la Gestionnaire de bibliothèques de HTMLs pour activer la minification (recommandé).

   AVERTISSEMENT

   Il est essentiel, du côté publication, que les bibliothèques clientes soient not servi depuis /apps car ce chemin d’accès doit être limité pour des raisons de sécurité à l’aide de la variable Section de filtrage de Dispatcher. Le allowProxy, propriété de la bibliothèque cliente s’assure que les fichiers CSS et JS sont diffusés à partir de /etc.clientlibs.

Étapes suivantes

Découvrez comment mettre en oeuvre des styles individuels et réutiliser les composants principaux à l’aide du système de style du Experience Manager. Développement avec le système de style couvre l’utilisation du système de style pour étendre les composants principaux avec des CSS spécifiques à la marque et des configurations de stratégie avancées de l’éditeur de modèles.

Afficher le code terminé sur GitHub ou revoir et déployer le code localement sur la branche Git tutorial/client-side-libraries-solution.

1. Cloner le github.com/adobe/aem-wknd-guides référentiel.
2. Consultez la section tutorial/client-side-libraries-solution branche.

Outils et ressources supplémentaires

Webpack DevServer - Markup statique

Dans les deux exercices précédents, plusieurs fichiers Sass dans la variable ui.frontend ont été mis à jour et, par le biais d’un processus de génération, voir que ces modifications se répercutent dans AEM. Examinons ensuite une technique qui utilise une webpack-dev-server pour développer rapidement les styles front-end par rapport à static HTML.

Cette technique est pratique si la plupart des styles et du code frontal sont effectués par un développeur front-end dédié qui n’a peut-être pas un accès facile à un environnement AEM. Cette technique permet également au FED d’apporter des modifications directement au HTML, qui peut ensuite être transféré à un développeur d’AEM pour implémenter en tant que composants.

1. Copiez la source de la page de l’article de LA skatepark à l’adresse http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled.

2. Ouvrez à nouveau votre IDE. Collez la balise copiée de l’AEM dans le index.html dans le ui.frontend module sous src/main/webpack/static.

3. Modifiez la balise copiée et supprimez toutes les références à clientlib-site et clientlib-dependencies:

   <!-- remove -->
   <script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.js"></script>
   <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-dependencies.css" type="text/css">
   <link rel="stylesheet" href="/etc.clientlibs/wknd/clientlibs/clientlib-site.css" type="text/css">
   ...
   <script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-site.js"></script>
   

   Supprimez ces références, car le serveur de développement webpack génère automatiquement ces artefacts.

4. Démarrez le serveur de développement webpack à partir d’un nouveau terminal en exécutant la commande suivante depuis l’ ui.frontend module :

   $ cd ~/code/aem-guides-wknd/ui.frontend/
   $ npm start
   
   > aem-maven-archetype@1.0.0 start code/aem-guides-wknd/ui.frontend
   > webpack-dev-server --open --config ./webpack.dev.js
   

5. Cela devrait ouvrir une nouvelle fenêtre de navigateur à l’adresse http://localhost:8080/ avec les balises statiques.

6. Modifier le fichier src/main/webpack/site/_variables.scss fichier . Remplacez la variable $text-color avec les éléments suivants :

   - $text-color:              $black;
   + $text-color:              $pink;
   

   Enregistrez les modifications.

7. Les modifications doivent automatiquement être répercutées dans le navigateur sur http://localhost:8080.

   

8. Consultez la section /aem-guides-wknd.ui.frontend/webpack.dev.js fichier . Contient la configuration webpack utilisée pour démarrer le serveur webpack-dev-server. Il effectue des proxys des chemins. /content et /etc.clientlibs à partir d’une instance d’AEM en cours d’exécution locale. Voici comment les images et autres clientlibs (non gérés par la variable ui.frontend (code) sont disponibles.

   ATTENTION

   La source d’image du balisage statique pointe vers un composant d’image dynamique sur une instance d’AEM locale. Les images apparaissent rompues si le chemin d’accès à l’image change, si AEM n’est pas démarré ou si le navigateur ne s’est pas connecté à l’instance AEM locale. En cas de remise à une ressource externe, il est également possible de remplacer les images par des références statiques.

9. Vous pouvez stop le serveur webpack à partir de la ligne de commande en saisissant CTRL+C.

aemfed

aemfed est un outil de ligne de commande Open Source qui peut être utilisé pour accélérer le développement frontal. Il est alimenté par aemsync, Browsersync, et Sling Log Tracer.

À un niveau élevé, la variable aemfedest conçu pour écouter les modifications apportées aux fichiers dans la variable ui.apps et les synchroniser automatiquement directement avec une instance AEM en cours d’exécution. En fonction des modifications, un navigateur local s’actualise automatiquement, accélérant ainsi le développement frontal. Il est également conçu pour fonctionner avec le traceur de journal Sling afin d’afficher automatiquement les erreurs côté serveur directement dans le terminal.

Si vous effectuez beaucoup de travail au sein de la variable ui.apps module, modification de scripts HTL et création de composants personnalisés, aemfed peut être un outil puissant à utiliser. La documentation complète se trouve ici.

Débogage des bibliothèques côté client

Utilisation de différentes méthodes de categories et incorpore pour inclure plusieurs bibliothèques clientes, le dépannage peut s’avérer fastidieux. AEM expose plusieurs outils pour faciliter cette tâche. L’un des outils les plus importants est Reconstruire les bibliothèques clientes qui force AEM à recompiler les fichiers LESS et à générer le fichier CSS.

• Effacer les bibliothèques - Répertorie les bibliothèques clientes enregistrées dans l’instance AEM. <host>/libs/granite/ui/content/dumplibs.html

• Test Output - permet à un utilisateur d’afficher la sortie de HTML attendue des inclusions clientlib en fonction de la catégorie. <host>/libs/granite/ui/content/dumplibs.test.html

• Validation des dépendances des bibliothèques - met en évidence les dépendances ou les catégories incorporées introuvables. <host>/libs/granite/ui/content/dumplibs.validate.html

• Reconstruire les bibliothèques clientes - permet à un utilisateur de forcer AEM à reconstruire les bibliothèques clientes ou d’invalider le cache des bibliothèques clientes. Cet outil est efficace lors du développement avec LESS, car il peut forcer AEM à recompiler le CSS généré. En règle générale, il est plus efficace d’invalider les caches, puis d’effectuer une actualisation de page plutôt que de recréer les bibliothèques. <host>/libs/granite/ui/content/dumplibs.rebuild.html

Ressources Business.Adobe.com