Anatomie d’un projet
Ce document indique à quoi doit ressembler un projet type du point de vue du code. Avant de lire ce document, familiarisez-vous avec le document Prise en main - Tutoriel pour les développeurs.
Git et GitHub
Une de nos philosophies déterminantes est qu'il est plus facile de permettre aux utilisateurs de travailler avec les outils qu'ils connaissent. La grande majorité des développeurs gèrent leur code dans des systèmes basés sur Git. Il est donc logique de permettre aux développeurs de travailler avec Git pour gérer et déployer leur code.
Nous utilisons une approche sans création qui s’exécute directement à partir de votre référentiel GitHub. Après l’installation du robot GitHub AEM sur votre référentiel, des sites web sont automatiquement créés pour chacune de vos branches pour l’aperçu du contenu sur https://<branch>--<repo>--<owner>.aem.page/ et le site d’exploitation sur https://<branch>--<repo>--<owner>.aem.live/ pour le contenu publié.
Chaque ressource que vous placez dans votre référentiel GitHub est disponible sur votre site web. Par conséquent, un fichier de votre référentiel GitHub sur la branche principale de /scripts/scripts.js sera disponible sur https://main--<repo>--<owner>.aem.page/scripts/scripts.js
Cela devrait être très intuitif. Il existe peu de fichiers « spéciaux » que Adobe Experience Manager utilise pour connecter le contenu à votre site web.
Nous recommandons vivement que les référentiels soient gardés publics sur GitHub, pour favoriser la communauté. Pour un site Web public, il n’est vraiment pas nécessaire de garder le code masqué, car il est diffusé dans les navigateurs de votre site Web.
Remarques importantes :
- La combinaison
<branch>--<repo>--<owner>ne doit pas dépasser 63 caractères (traits d’union/tirets inclus). Il s’agit d’une contrainte de nom de sous-domaine. branch,repoetownerne peuvent pas contenir de--.
Fichiers de configuration
Certains fichiers de votre référentiel GitHub ont une signification spéciale pour AEM et sont traités d’une manière spéciale. Ces fichiers se trouvent dans le répertoire racine du référentiel.
La connexion au contenu : fstab.yaml
Comme vous l'avez peut-être vu dans le guide de prise en main le fichier fstab.yaml sert de connexion à votre lecteur Google ou aux dossiers SharePoint qui contiennent votre contenu. Ce fichier est utilisé comme indicateur de la manière dont le code de votre référentiel GitHub est combiné au contenu de votre source de contenu.
En plus de fournir la connexion au contenu, le fstab.yaml fournit également une fonctionnalité de mappage de dossiers qui vous permet de mapper des « itinéraires » sans extension à un élément de contenu donné ou à une HTML statique.
Point d’entrée : head.html
Le fichier head.html est le point d’extension le plus important pour influencer le balisage du contenu. Le moyen le plus simple de l’envisager est d’injecter ce fichier côté serveur dans le cadre de la balise <head> HTML et de le combiner avec les métadonnées provenant du contenu.
Le head.html devrait rester en grande partie inchangé par rapport à la norme standard et il n'y a que très peu de raisons légitimes d'apporter des modifications dans un projet régulier. Il s’agit notamment du remappage de votre projet à une URL de base différente dans le but d’exposer votre projet dans un dossier différent du dossier racine de votre domaine sur votre réseau CDN ou de prendre en charge les navigateurs hérités qui nécessitent généralement des scripts qui ne sont pas chargés en tant que modules.
Il est vivement déconseillé d’ajouter des technologies marketing telles qu’Adobe Web SDK, Google Tag Manager ou d’autres scripts tiers à votre fichier head.html en raison de l’impact sur les performances. Il est également déconseillé d’ajouter des scripts ou des styles intégrés aux head.html pour des raisons de performances et de gestion du code. Consultez la section Scripts et styles ci-dessous pour plus d’informations sur la gestion des scripts et des styles.
Veuillez consulter les exemples suivants.
Introuvable : 404.html
Pour créer une réponse 404 personnalisée, placez un fichier 404.html à la racine de votre référentiel github. Elle est diffusée sur toute URL qui ne correspond pas à une ressource existante dans le contenu ou le code et remplace le corps de la réponse de 404 minimaliste prête à l’emploi.
Le 404 peut imiter le balisage d’une page existante, y compris le code du site, avec les pieds de page de navigation, etc., ou il peut avoir un aspect complètement différent.
Veuillez consulter les exemples suivants.
Ne pas servir : .hlxignore
Certains fichiers de votre référentiel ne doivent pas être diffusés à partir de votre site web, soit parce que vous souhaitez les garder privés, soit parce qu’ils ne sont pas pertinents pour la diffusion du site web (par exemple, tests, outils de création, artefacts de création, etc.) et qu’ils n’ont pas besoin d’être observés par le robot AEM. Vous pouvez les ajouter à un fichier .hlxignore au même format que le fichier .gitignore bien connu.
Veuillez consulter l’exemple suivant.
Apprivoiser les robots : robots.txt
Un fichier robots.txt est généralement un fichier ordinaire diffusé comme vous vous y attendez sur votre site web de production sur votre propre domaine. Pour protéger votre aperçu et votre site d’origine de l’indexation, vos sites .page et .live serviront un fichier robots.txt qui désautorise tous les robots au lieu du fichier robots.txt de votre référentiel.
Veuillez consulter les exemples suivants.
Requête et indexation : helix-query.yaml
Il existe une fonction d’indexation flexible qui vous permet de suivre facilement toutes vos pages de contenu sous forme de feuille de calcul. Cette fonctionnalité est souvent utilisée pour afficher les listes ou les flux des pages, ainsi que pour filtrer et trier le contenu sur un site web. Consultez le document Indexation pour plus d’informations.
Veuillez consulter les exemples suivants.
Automatisation de votre plan de site : helix-sitemap.yaml
Des plans de site complexes peuvent être automatiquement créés à chaque fois que les auteurs publient du nouveau contenu, y compris des mappages de hreflang flexibles si nécessaire. Cette fonctionnalité est généralement basée sur la fonction d’indexation .
Voir ce problème GitHub pour connaître les options de configuration du plan du site.
Veuillez consulter les exemples suivants.
Structure de fichiers et de dossiers couramment utilisée
Au-delà du fait que les fichiers sont traités comme des fichiers spéciaux ou de configuration, il existe une structure couramment utilisée qui est exprimée dans le référentiel standard.
Les dossiers communs ci-dessous se trouvent généralement dans le répertoire racine d’un référentiel de projet, mais dans les cas où seule une partie d’un site web est gérée par AEM, ils sont souvent déplacés vers un sous-dossier pour refléter le mappage de l’itinéraire de l’origine dans un réseau CDN.
Cela signifie que dans un cas où, par exemple, seul /en/blog/ est initialement mappé à AEM à partir du réseau CDN, toutes les structures de dossiers ci-dessous (par exemple, /scripts, /styles, /blocks etc.) sont déplacés dans le dossier /en/blog/ dans GitHub pour que le mappage CDN reste aussi simple que possible.
Avec un simple ajustement de la référence à scripts.js et styles.css dans head.html (voir ci-dessus), il est possible d'indiquer que tous les fichiers nécessaires sont chargés à partir du répertoire de base de code correspondant. Pour éviter la réécriture des URL, la structure de dossiers est également créée avec la source de contenu (par exemple, sharepoint ou google drive) en ayant une structure de répertoires de /en/blog/.
Dans de nombreux cas, lorsque l’empreinte AEM augmente sur un site, il arrive un moment où le code est redéplacé vers le dossier racine et les références head.html sont ajustées en conséquence.
Scripts et styles
Par convention, dans un projet AEM, le head.html fait référence aux styles.css, scripts.js et aem.js situés dans /scripts et /styles comme points d’entrée du code du projet.
scripts.js’est là que réside votre code javascript personnalisé global et c’est là que le code de chargement par bloc est déclenché. styles.css héberge les informations de style globales de votre site et contient au minimum les informations de mise en page globales nécessaires à l’affichage de la Largest Contentful Paint (LCP).
Comme les trois fichiers sont chargés avant que la page ne puisse être affichée, il est important qu’ils soient relativement petits et exécutés efficacement.
Au-delà de styles.css, un fichier lazy-styles.css est généralement utilisé, qui est chargé après l’événement LCP et peut donc contenir des informations CSS plus lentes/plus nombreuses. Il peut s’agir d’un emplacement idéal pour les polices ou le CSS global qui se trouve sous le pli.
En plus de scripts.js, il y a les delayed.js couramment utilisés. Il s’agit d’un fourre-tout pour les bibliothèques qui doivent être chargées sur une page, mais qui doivent être protégées pour ne pas interférer avec la diffusion de la page. Il s’agit d’un bon emplacement pour le code qui est hors du contrôle de votre projet et qui inclut généralement la pile SmartTech et d’autres bibliothèques.
Consultez le document Keeping it 100, Web Performance pour plus d’informations sur l’optimisation des performances de votre site.
Blocs
La plupart du code CSS et JavaScript spécifique au projet réside dans des blocs. Les auteurs créent des blocs dans leurs documents. Les développeurs écrivent ensuite le code correspondant qui définit le style des blocs avec CSS et/ou qui orne le DOM pour prendre le balisage d’un bloc et le transformer en la structure nécessaire ou pratique pour le style et la fonctionnalité souhaités.
Le nom du bloc est utilisé à la fois comme nom de dossier d’un bloc et comme nom de fichier pour les fichiers .css et .js chargés par le chargeur de blocs lorsqu’un bloc est utilisé sur une page.
Le nom du bloc est également utilisé comme nom de classe CSS du bloc pour permettre un style intuitif. Le javascript est chargé en tant que module (ESM) et exporte une fonction par défaut qui est exécutée dans le cadre du chargement du bloc.
Le bloc Colonnes en est un exemple simple. Il ajoute des classes supplémentaires dans JavaScript en fonction du nombre de colonnes de l’instance correspondante créée par l’auteur. Cela lui permet d’utiliser un style flexible du contenu qui se compose de deux colonnes au lieu de trois.
Icônes
La plupart des projets comportent des fichiers SVG qui sont généralement ajoutés au dossier /icons et peuvent être référencés par les auteurs à l’aide d’une notation :<iconname>:. Par défaut, les icônes sont insérées dans le DOM afin qu’elles puissent être mises en forme avec CSS, sans avoir à créer de symboles SVG.