Bibliothèques clientes et workflow front-end client-side-libraries

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

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

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

$ mvn clean install -PautoInstallSinglePackage

$ mvn clean install -PautoInstallSinglePackage -Pclassic

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

Développez 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 bibliothèques clientes sont examinées plus en détail.

Le tableau suivant résume les bibliothèques clientes. Plus d’informations sur l’inclusion des bibliothèques clientes se trouvent ici.

Observez que les éléments clientlib-site et clientlib-dependencies sont ignorés du contrôle de code source. Cela est tout à fait normal, car ces éléments sont générés au moment de la création par le module ui.frontend.

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

Ouvrez le fichier main.scss.

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

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

Inspectez les fichiers sous src/main/webpack/site/styles :

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

Développez le dossier components sous src/main/webpack et inspectez les fichiers.

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

Téléchargez les styles de base WKND wknd-base-styles-src-v3.zip et décompressez 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.

Remplacez 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

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

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

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

Ouvrez ui.frontend/package.json et, dans la commande scripts start, ajoutez --env writeToDisk=true.

{
  "scripts": {
    "start": "webpack-dev-server --open --config ./webpack.dev.js --env writeToDisk=true",
  }
}

Démarrez le serveur de développement webpack avec le mode watch en exécutant la commande suivante :

$ npm run watch

Cette opération compile les fichiers sources à partir du module 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

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

Inspectez le 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.

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

Inspectez le fichier site.css dans le module ui.apps à ui.apps/src/main/content/jcr_root/apps/wknd/clientlibs/clientlib-site/css/site.css. Il doit sagir d'une copie identique du fichier site.css du module ui.frontend. Il peut être déployé sur AEM maintenant qu'il est dans le module ui.apps.

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 complète pour effacer les fichiers CSS mis en cache par le navigateur.

Ça commence à ressembler beaucoup plus aux maquettes !

À partir de là, le module ui.frontend ouvre le fichier : ui.frontend/src/main/webpack/site/_variables.scss.

Mettez à jour la variable de couleur $brand-primary :

//== variables.css

//== Brand Colors
$brand-primary:          $pink;

Enregistrez les modifications.

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

Revenez sur la modification de la couleur $brand-primary et arrêtez la construction du webpack en utilisant la commande CTRL+C.

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

Cliquez sur l’icône Informations sur la page et dans le menu, sélectionnez Politique de page pour ouvrir la boîte de dialogue Politique de page.

Informations sur la page > Politique de page

Notez que les catégories pour wknd.dependencies et wknd.site sont répertoriées ici. Par défaut, les bibliothèques clientes configurées via la politique 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 répertorier explicitement le code JavaScript de la bibliothèque cliente à charger dans l’en-tête de la page. C’est le cas pour wknd.dependencies.

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

Cliquez sur l'icône Informations sur la page et dans le menu, sélectionnez Voir comme publié pour ouvrir la page de l’article sans l’éditeur AEM.

Affichez la source de la page de http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html?wcmmode=disabled pour voir les références de la bibliothèque cliente suivante 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 bibliothèques clientes utilisent le proxy de point d’entrée /etc.clientlibs. Vous devriez également voir que la bibliothèque cliente suivante est incluse 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>

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

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

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 webpack dev server génère automatiquement ces artefacts.

Démarrez le webpack dev server à partir d’un nouveau terminal en exécutant la commande suivante depuis le module ui.frontend  :

$ 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

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

Modifiez le fichier src/main/webpack/site/_variables.scss. Remplacez la règle $text-color par la suivante :

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

Enregistrez les modifications.

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

Consultez le fichier /aem-guides-wknd.ui.frontend/webpack.dev.js. Contient la configuration webpack utilisée pour lancer le webpack-dev-server. Il envoie par proxy les chemins /content et /etc.clientlibs à partir d’une instance d’AEM exécutée localement. Voici comment les images et autres bibliothèques clientes (non gérés par le code ui.frontend) sont disponibles.

Vous pouvez arrêter le webpack server à partir de la ligne de commande en saisissant CTRL+C.