Show Menu
TOPICS×

Module ui.frontend de l’archétype de projet AEM

L’archétype de projet AEM comprend un mécanisme de génération front-end dédié et facultatif basé sur Webpack. Ainsi, le module ui.frontend devient l’emplacement central de toutes les ressources front-end du projet, y compris les fichiers JavaScript et CSS. Pour tirer pleinement parti de cette fonctionnalité utile et flexible, il est essentiel de savoir comment le développement front-end s’intègre à un projet AEM.

Projets AEM et développement front-end

En termes beaucoup plus simples, les projets AEM peuvent être considérés comme comprenant deux parties distinctes, mais connexes :
  • Développement principal générant la logique d’AEM et créant des bibliothèques Java, des services OSGi, etc.
  • Développement front-end permettant de gérer la présentation et le comportement du site Web obtenu, et de créer des bibliothèques JavaScript et CSS
Ces deux processus de développement étant axés sur différentes parties du projet, les développements front-end et back-end peuvent être réalisés en parallèle.
Toutefois, le projet obtenu doit utiliser les résultats de ces deux processus de développement, à savoir les développements front-end et back-end.
L’exécution de
npm run dev
permet de lancer le processus de génération front-end qui regroupe les fichiers JavaScript et CSS stockés dans le module ui.frontend, et qui crée deux bibliothèques client minifield,
clientlib-site
et
clientlib-dependencies
, et de les consigner dans le module ui.apps. Il est possible de déployer les bibliothèques client vers AEM. Ainsi, vous pouvez stocker votre code côté client dans le référentiel.
Si l’archétype complet de projet AEM est exécuté avec
mvn clean install -PautoInstallPackage
tous les artefacts de projet inclus, les bibliothèques client sont transmises à l’instance AEM.

Processus de développement front-end possibles

Le module de génération front-end est un outil utile et très flexible, mais n'impose aucun avis en particulier sur la manière dont il doit être utilisé. Vous trouverez ci-dessous deux exemples d’utilisation
possibles
, mais les besoins à satisfaire pour votre projet personnel peuvent exiger d’autres modèles d’utilisation.

Utilisation du serveur de développement statique Webpack

Grâce à Webpack, vous pouvez mettre en forme et développer vos contenus selon les résultats statiques des pages Web AEM dans le module ui.frontend.
  1. Aperçu de la page dans AEM à l’aide du mode d’aperçu de page ou transmission
    wcmmode=disabled
    de l’URL
  2. Affichage de la source de la page et enregistrement au format HTML statique dans le module ui.frontend
  3. Lancez Webpack , puis commencez à mettre en forme et à générer les codes JavaScript et CSS requis.
  4. Exécutez
    npm run dev
    pour générer les bibliothèques client.
Dans ce processus, un développeur AEM peut exécuter les première et deuxième étapes, puis transmettre le code HTML statique au développeur front-end qui se développe selon les résultats HTML AEM.
Vous pouvez également tirer parti de la bibliothèque de composants pour obtenir des exemples de résultats de balisage de chaque composant pour travailler sur le composant au lieu de la page.

Utilisation de Storybook

Avec Storybook , vous pouvez effectuer un développement front-end plus important. Même s'il ne fait pas partie de l’archétype de projet AEM, vous pouvez installer Storybook et stocker vos artefacts dans le module ui.frontend. Il est possible de les déployer en tant que bibliothèques client une fois prêts pour les tests dans AEM en exécutant
npm run dev
.
Storybook n’est pas fourni dans l’archétype de projet AEM. Si vous choisissez de l’utiliser, vous devez l’installer séparément.

Définition du balisage

Quel que soit le processus de développement front-end que vous décidez de mettre en œuvre pour votre projet, les développeurs front-end et back-end doivent avant tout s’entendre sur le balisage. En règle générale, AEM définit le balisage que les principaux composants fournissent. Vous pouvez toutefois le personnaliser, le cas échéant .

Le module ui.frontend

L’archétype de projet AEM comprend un mécanisme de génération front-end dédié facultatif basé sur Webpack avec les fonctionnalités suivantes.
  • Prise en charge complète de TypeScript, ES6 et ES5 (et des enveloppes Webpack applicables)
  • Peluchage TypeScript et JavaScript à l’aide d'un jeu de règles TSLint
  • Sortie ES5 pour la prise en charge des navigateurs hérités
  • Extension métacaractère
    • Inutile d'ajouter des importations
    • Tous les fichiers JS et CSS peuvent désormais être ajoutés à chaque composant
      • Les meilleures pratiques figurent sous
        /clientlib/js
        ,
        /clientlib/css
        ou
        /clientlib/scss
        .
    • Aucun fichier
      .content.xml
      ou
      js.txt
      /
      css.txt
      n’est requis, car tous les éléments sont exécutés via Webpack.
    • Extraction de tous les fichiers JS par l’application globale sous le dossier
      /component/
      .
      • Webpack permet aux fichiers CSS/SCSS d’être liés via des fichiers JS.
      • Ces fichiers sont extraits via les deux points d'entrée
        sites.js
        et
        vendors.js
        .
    • Les seuls fichiers consommés par AEM sont les fichiers de sortie
      site.js
      et
      site.css
      dans
      /clientlib-site
      , ainsi que
      dependencies.js
      et
      dependencies.css
      dans
      /clientlib-dependencies
  • Blocs
    • Principal (js/css de site)
    • Fournisseurs (js/css de dépendances)
  • Prise en charge complète de Sass/Scss (Sass est compilé dans CSS via Webpack)
  • Serveur de développement Webpack statique avec proxy intégré utilisé pour une instance locale AEM
Pour plus d’informations d’ordre technique sur le module ui.frontend, consultez la documentation sur GitHub .

Installation

  1. Installez globalement NodeJS (v10+). Cela installera également npm.
  2. Accédez à ui.frontend dans votre projet et exécutez
    npm install
    .
Vous devez avoir exécuté l’archétype avec l’option
-DoptionIncludeFrontendModule=y
pour renseigner le dossier ui.frontend.

Utilisation

Les scripts npm suivants orientent le flux de travail front-end :
  • npm run dev
     : version complète avec optimisation JS désactivée (shaking d’arborescence, etc.), cartes source activées et optimisation CSS désactivée.
  • npm run prod
     : version complète avec optimisation JS activée (shaking d’arborescence, etc.), cartes source désactivées et optimisation CSS activée.
  • npm run start
    :- Démarre un serveur de développement Webpack statique à des fins de développement local et avec une dépendance minimale d’AEM.

Sortie

Le module ui.frontend compile le code sous le dossier
ui.frontend/src
et génère les fichiers CSS et JS compilés, ainsi que les ressources sous un dossier dénommé
ui.frontend/dist
.
  • Site
     :
    site.js
    ,
    site.css
    et un dossier
    resources/
    correspondant aux images et polices dépendantes de la disposition sont créés dans un dossier
    dist/
    clientlib-site.
  • **Dépendances ** :
    dependencies.js
    et
    dependencies.css
    sont créés dans un dossier
    dist/clientlib-dependencies
    .

JavaScript

  • Optimisation : pour les versions de production, tous les JS qui ne sont pas utilisés ou appelés sont supprimés.

CSS

  • Indexation automatique : toutes les feuilles de style CSS sont exécutées via un pré-indexeur et les propriétés nécessitant une pré-indexation sont automatiquement ajoutées dans les feuilles de style CSS.
  • Optimisation : lors de la publication, toutes les feuilles de style CSS sont exécutées via un optimiseur (cssnano) qui les normalise selon les règles par défaut suivantes :
    • Réduit l’expression calc CSS chaque fois que possible, assurant à la fois la compatibilité du navigateur et la compression. Convertit entre des valeurs équivalentes de longueur, de temps et d’angle. Notez que, par défaut, les valeurs de longueur ne sont pas converties.
    • Supprime les commentaires dans les règles, les sélecteurs et les déclarations et autour de ceux-ci.
    • Supprime les doublons de règles, de règles at et de déclarations.
      • Notez que cela ne fonctionne que pour les doublons exacts.
    • Supprime les règles vides, les requêtes multimédias et les règles ayant des sélecteurs vides, car elles n’affectent pas la sortie.
    • Fusionne les règles adjacentes par sélecteurs et paires propriété/valeur se chevauchant.
    • Garantit qu’un seul @charset est présent dans le fichier CSS et le déplace en haut du document.
    • Remplace le mot-clé initial CSS par la valeur réelle, lorsque la sortie obtenue est plus petite.
    • Compresse les définitions SVG en ligne avec SVGO.
  • Nettoyage : comprend une tâche de nettoyage explicite pour effacer à la demande les fichiers CSS, JS et Map générés.
  • Mappage de source : version de développement uniquement
L’option de version front-end utilise des fichiers de configuration Webpack uniquement destinés au développement et à la production qui partagent un fichier de configuration commun. Les paramètres de développement et de production peuvent ainsi être modifiés indépendamment.

Génération de bibliothèques client

Le processus de génération du module ui.frontend tire parti du plug-in aem-clientlib-generator pour déplacer les fichiers CSS et JavaScript compilés, ainsi que les ressources utilisées dans le module ui.apps. La configuration aem-clientlib-generator est définie dans
clientlib.config.js
. Les bibliothèques client suivantes sont générées :
  • clientlib-site
    -
    ui.apps/src/main/content/jcr_root/apps/<app>/clientlibs/clientlib-site
  • clientlib-dependencies
    -
    ui.apps/src/main/content/jcr_root/apps/<app>/clientlibs/clientlib-dependencies

Ajout de bibliothèques client aux pages

Les catégories
clientlib-site
et
clientlib-dependencies
sont ajoutées aux pages via la configuration Règles de page dans le modèle par défaut. Pour afficher les règles, modifiez la ligne de commande
Modèle de page de contenu > Informations de page > Règles de page
.
L’ajout final de bibliothèques client à la page des sites est le suivant :
<HTML> <head> <link rel="stylesheet" href="clientlib-base.css" type="text/css"> <script type="text/javascript" src="clientlib-dependencies.js"></script> <link rel="stylesheet" href="clientlib-dependencies.css" type="text/css"> <link rel="stylesheet" href="clientlib-site.css" type="text/css"> </head> <body> .... <script type="text/javascript" src="clientlib-site.js"></script> <script type="text/javascript" src="clientlib-base.js"></script> </body> </HTML>
Vous pouvez naturellement modifier cet ajout en mettant à jour les règles de page et/ou en modifiant les catégories, et incorporer les propriétés des bibliothèques client concernées.

Serveur de développement Webpack statique

Le module ui.frontend comprend un serveur webpack-dev-server qui assure le rechargement en direct pour réaliser un développement front-end rapide en dehors d’AEM. La configuration tire parti du plug-in html-webpack-plugin pour intégrer automatiquement les fichiers CSS et JavaScript compilés à partir du module ui.frontend dans un modèle HTML statique.

Fichier important

  • ui.frontend/webpack.dev.js
    • Contient la configuration utilisée pour webpack-dev-server et pointe vers le modèle HTML à employer.
    • Il comprend également une configuration proxy utilisée pour une instance AEM s’exécutant sur localhost:4502.
  • ui.frontend/src/main/webpack/static/index.html
    • Il s’agit du code HTML statique sur lequel le serveur est exécuté.
    • Ainsi, les développeurs peuvent modifier les fichiers CSS et JavaScript, et voir ces modifications répercutées immédiatement dans le balisage.
    • On suppose que le balisage stocké dans ce fichier reproduit fidèlement le balisage généré par les composants AEM.
    • Le balisage de ce fichier n’est pas synchronisé automatiquement avec le balisage du composant AEM.
    • Ce fichier comporte également des références aux bibliothèques client stockées dans AEM, comme Core Component CSS et Responsive Grid CSS.
    • Le serveur de développement Webpack est configuré pour remplacer les fichiers CSS et JavaScript ajoutés depuis une instance locale AEM en cours d’exécution, selon la configuration disponible dans
      ui.frontend/webpack.dev.js
      .

Utilisation de

  1. Exécutez la commande
    mvn -PautoInstallSinglePackage clean install
    depuis la racine du projet pour l’installer dans son intégralité sur une instance AEM s’exécutant sur
    localhost:4502
    .
  2. Naviguez dans le dossier
    ui.frontend
    .
  3. Exécutez la commande suivante
    npm run start
    pour démarrer le serveur de développement Webpack. Une page de navigateur (
    localhost:8080
    ou le port disponible suivant) doit s’ouvrir.
Vous pouvez désormais modifier les fichiers CSS, JS, SCSS et TS, et voir ces modifications répercutées immédiatement sur le serveur de développement Webpack.