Bibliothèques côté client 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 implémentation 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

REMARQUE

Si vous avez terminé avec succès le chapitre précédent, vous pouvez réutiliser le projet et ignorer les étapes d’extraction du 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 module 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 créer

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

Styles terminés

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

Arrière-plan

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. Gérer les dépendances sur les structures tierces de manière organisée
  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, nous allons examiner la manière dont 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 actuellement pas de style. Nous allons ensuite mettre en oeuvre 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

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

Organisation de bibliothèque cliente de haut niveau

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

REMARQUE

L’organisation de bibliothèque côté client suivante est générée par AEM Project Archetype, mais ne représente qu’un point de départ. La manière dont un projet gère et diffuse finalement du code CSS et JavaScript vers une implémentation de sites peut varier considérablement en fonction des ressources, des compétences et des exigences.

  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.

    Clientlibs dans ui.apps

    Nous examinerons ces clientlibs plus en détail ci-dessous.

  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 seront 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ère la variable 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 présentent certaines limites en ce qui concerne la prise en charge de langues telles que Sass ou TypeScript. Il existe un certain nombre d'outils open source comme 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 une majorité de fichiers source front-end.

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

  2. Ouvrez le fichier main.scss

    main.scss - entrypoint
    bibliothèques côté client/main-scss

    main.scss est le point d’entrée de tous les fichiers Sass dans la variable ui.frontend module . Elle 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 comprend tous les styles pour les styles de composants individuels sous src/main/webpack/components. Une autre expression régulière inclut tous 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 sera 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:

    Fichiers de style

    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.

    Fichiers Sass de composant

    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 .

    Styles de base WKND

    Pour accélérer le tutoriel, nous avons fourni 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.

  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
    

    Fichiers modifiés

    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.

Intégration de l’architecture ui.frontend

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 ne doit être exécuté qu’une seule fois, à la suite d’un nouveau clone ou d’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 compilera la variable src dans le fichier ui.frontend et synchroniser 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.

    CSS du site distribué

  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.

    ui.apps clientlib-site

    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.

    Mise à jour des styles de base de l’article

    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 seront 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. Dans le 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 :

    Bibliothèques côté client

  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.

ATTENTION

L’utilisation de la variable ui.frontend n’est peut-être pas nécessaire pour tous les projets. Le ui.frontend ajoute une complexité supplémentaire ; s’il n’est pas nécessaire ou souhaité d’utiliser certains de ces outils front-end avancés (Sass, webpack, npm…), cela peut ne pas être nécessaire.

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.

    Règle de page du modèle de page Article

    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. Si vous le souhaitez, vous pouvez indiquer explicitement que le code JavaScript clientlib doit être chargé dans l’en-tête de la page. C’est le cas pour wknd.dependencies.

    Règle de page du modèle de page Article

    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 , comme nous l’avons vu plus tôt pour la fonction wknd.base clientlib. 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 très lourde 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.

    Afficher comme publié(e)

  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 voir les inclusions clientlib suivantes 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

    Si vous suivez la version 6.5/6.4, les bibliothèques côté client ne seront pas automatiquement réduites. Consultez la documentation relative à la Gestionnaire de bibliothèques de HTMLs pour activer la minfication (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 passer en revue 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, nous avons pu mettre à jour plusieurs fichiers Sass dans la variable ui.frontend et, par le biais d’un processus de génération, voir ces modifications répercutées dans AEM. Ensuite, nous allons examiner des techniques qui tirent parti d’une webpack-dev-server pour développer rapidement nos 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>
    

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

  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.

    Modifications du serveur de développement webpack local

  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. Notez qu’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. Si vous transférez à 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é aemfed est conçu pour écouter les modifications apportées aux fichiers dans la variable ui.apps et les synchronise automatiquement directement sur 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 ui.apps module, modification des scripts HTL et création de composants personnalisés, aemfed peut être un outil très puissant à utiliser. Vous trouverez la documentation complète ici ..

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

Avec différentes méthodes 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 CSS.

  • Effacer les bibliothèques - Répertorie toutes 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 à recréer toutes les bibliothèques clientes ou d’invalider le cache des bibliothèques clientes. Cet outil est particulièrement efficace lors du développement avec LESS, car cela 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 toutes les bibliothèques. <host>/libs/granite/ui/content/dumplibs.rebuild.html

reconstruire la bibliothèque cliente

Sur cette page