Balisage, sections, blocs et blocage automatique

Pour concevoir des sites web et créer des fonctionnalités, les équipes de développement utilisent les balises et le modèle DOM qui est rendu dynamiquement à partir du contenu. Les balises et le modèle DOM sont construits de manière à permettre une manipulation et un style flexibles. En même temps, ils offrent des fonctionnalités prêtes à l’emploi afin que l’équipe de développement n’ait pas à se soucier de certains aspects des sites web modernes.

Structure d’un document

L’aspect le plus important lors de la structure d’un document est de le rendre simple et intuitif pour les auteurs qui contribueront au contenu.

Cela signifie qu’il est vivement recommandé d’impliquer les auteurs très tôt dans le processus. Dans de nombreux cas, il est recommandé de laisser les auteurs placer le contenu qui doit passer à une page dans un document Google Doc ou Word sans avoir la notion de blocs et de sections, puis d’essayer d’apporter de petites modifications structurelles et d’introduire des sections et des blocs uniquement si nécessaire.

Un document suit la structure suivante dans l’abstrait.

Une page telle qu’elle est créée dans un document Word ou Google Doc utilise le modèle sémantique bien compris comme les en-têtes, le corps de texte, les listes, les images, les liens, etc. qui est partagé entre HTML, Markdown et Google Doc/Word. Nous appelons cela contenu par défaut. Dans une situation idéale, vous devriez laisser autant de contenu créé que possible comme contenu par défaut, car il s’agit de la manière naturelle pour les auteurs de traiter les documents.

Outre le contenu par défaut, nous avons un concept de pages sections, séparées par des règles horizontales ou --- pour regrouper certains éléments d’une page. Le regroupement de contenu peut avoir des raisons sémantiques et de conception. Par exemple, une section d’une page peut avoir une couleur d’arrière-plan différente.

En outre, il existe un concept de blocs qui sont créés sous la forme d’un tableau avec un en-tête comme première ligne qui identifie le type de bloc. Ce concept est l’approche la plus simple pour composer votre code.

Les sections peuvent contenir plusieurs blocs. Les blocs ne doivent jamais être imbriqués, car cela rend les éléments très difficiles à utiliser pour les auteurs.

DOM ou balisage

AEM produit un balisage sémantique propre et facilement lisible à partir du contenu qui lui est fourni. Vous pouvez y accéder facilement à l’aide de la fonction Afficher la source et consulter les balises de la page que vous êtes en train de lire.

La bibliothèque JavaScript utilisée dans scripts.js prend le balisage et l’améliore en un DOM qui est ensuite utilisé pour la plupart des tâches de développement, en particulier pour créer des blocs. Pour créer un DOM facile à utiliser pour le code de projet personnalisé, il est préférable de l’afficher comme un processus en deux étapes.

Dans la première étape, nous créons le balisage avec des sections, des blocs et du contenu par défaut qui ressembleront à ceci.

Dans la deuxième étape, la balise ci-dessus est augmentée dans l’exemple de DOM suivant, qui peut ensuite être utilisé pour mettre en forme et ajouter des fonctionnalités. Les différences entre le balisage fourni à partir du serveur et le DOM augmenté utilisé pour la plupart des tâches de développement sont mises en évidence ci-dessous.

Il consiste principalement à introduire un <div> wrapper pour les blocs et le contenu par défaut et à ajouter dynamiquement des classes CSS et des attributs de données supplémentaires utiles utilisés par le chargeur de blocs d’AEM.

Sections

Les sections permettent de regrouper le contenu et les blocs par défaut par l’auteur. La plupart du temps, les sauts de section sont introduits en fonction des différences visuelles entre les sections, par exemple une couleur d’arrière-plan différente pour une partie d’une page.

Du point de vue du développement, il n’y a généralement pas beaucoup d’interaction avec les sections en dehors du style CSS.
Les sections peuvent contenir un bloc spécial appelé Section Metadata, qui génère des attributs de données pour une section. Les noms des attributs de données peuvent être choisis par les auteurs, et la seule propriété de métadonnées de section bien connue est Style, qui sera transformée en classes CSS supplémentaires ajoutées à l’élément de section conteneur.

Les blocs et le contenu par défaut sont toujours placés dans une section, même si l’auteur n’introduit pas spécifiquement de sauts de section.

Contenu par défaut

Il existe un large éventail de sémantiques partagées entre les documents Word, Google Docs, Markdown et HTML. Par exemple, il existe des en-têtes de différents niveaux (p. ex. <h1> - <h6>), images, liens, listes (<ul>, <ol>), accentuation (<em>, <strong>), etc.

Nous tirons parti de la compréhension intuitive que les auteurs ont de la façon d'utiliser ces sémantiques dans les outils qu'ils connaissent (p ex. Documents Word/Google) et les mappe à Markdown, puis les effectue dans le balisage HTML.

Tous les mappages doivent être relativement simples et intuitifs pour le développeur. Un domaine dans lequel nous allons un peu plus loin que la traduction la plus simple possible est celui de la gestion des images. Au lieu d’une simple balise <img>, une balise <picture> complète est générée avec plusieurs résolutions différentes nécessaires à l’affichage sur les ordinateurs de bureau et les appareils mobiles, ainsi que différents formats pour les navigateurs modernes qui prennent en charge les navigateurs web et plus anciens qui ne le font pas.

Blocs

La plupart des fichiers CSS et JavaScript spécifiques au projet se trouvent dans des blocs. Les auteurs créent des blocs dans leurs documents et les développeurs écrivent le code correspondant qui définit le style des blocs avec CSS et/ou décore 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 JavaScript 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.

Tous les CSS au niveau du bloc doivent être inclus dans le bloc pour vous assurer qu’il n’y a aucun effet secondaire pour d’autres parties de votre projet, ce qui signifie que tous les sélecteurs d’un bloc doivent être précédés du préfixe de la classe de bloc correspondante. Dans certains cas, il est logique d’utiliser également le wrapper du bloc ou la section contenant pour le sélecteur.

Il existe un équilibre entre la manipulation DOM dans JavaScript et la complexité des sélecteurs CSS. Les sélecteurs CSS fragiles complexes ne sont pas recommandés et, en même temps, l’ajout de classes à chaque élément rend votre code plus complexe et ignore la sémantique des éléments.

L’un des principes les plus importants d’un projet est de garder les choses simples et intuitives pour les auteurs. Les blocs complexes rendent difficile la création de contenu. Il est donc important que les développeurs absorbent la complexité de traduire une expérience de création intuitive dans le DOM nécessaire à la logique de mise en page ou d’application. Il est souvent tentant de déléguer de la complexité à l’auteur. Au lieu de cela, les développeurs doivent s’assurer que les blocs ne deviennent pas difficiles à créer pour les auteurs. Un auteur doit toujours être en mesure de copier/coller un bloc et de comprendre intuitivement de quoi il s’agit.

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.

Les blocs peuvent être très simples ou contenir des composants d’application complets ou des widgets. Ils permettent également au développeur ou à la développeuse de structurer leur base de code en petits blocs de code qui peuvent être gérés facilement et chargés sur les pages web selon les besoins.

Le contenu d’un bloc est rendu dans le balisage sous la forme de balises <div> imbriquées pour les lignes et colonnes saisies par l’auteur. Dans le cas le plus simple, un bloc ne comporte qu'une seule cellule.

<div class=”blockname”>
  <div>
     <div>
      <p>Hello, World.</p>
     </div>
  </div>
</div>

Les auteurs peuvent ajouter des blocs à leurs pages de manière ad hoc en ajoutant simplement un tableau avec le nom du bloc dans la première ligne ou l’en-tête du tableau. Certains blocs sont également chargés automatiquement. Les blocs de header et de footer qui doivent être présents sur chaque page d’un site en sont un bon exemple.

Options de bloc

Si vous avez besoin qu’un bloc ait une apparence ou un comportement légèrement différent selon les circonstances, mais pas suffisamment différent pour devenir un nouveau bloc en lui-même, vous pouvez laisser les auteurs ajouter des options de bloc aux blocs entre parenthèses. Ces options ajoutent des classes modifiées au bloc . Par exemple, une Columns (wide) dans un en-tête de tableau générera le balisage suivant.

<div class=”columns wide”>

Les options de bloc peuvent également contenir plusieurs mots. Par exemple, les Columns (super wide) seront concaténées à l’aide de tirets.

<div class=”columns super-wide”>

Si les options de bloc sont séparées par des virgules, comme Columns (dark, wide), elles sont ajoutées en tant que classes distinctes.

<div class=”columns dark wide”>

Blocage automatique

Dans un scénario idéal, la majorité du contenu est créée en dehors des blocs, car l’introduction de tableaux dans un document le rend plus difficile à lire et à modifier. Inversement, les blocs fournissent un excellent mécanisme pour que les développeurs conservent leur code organisé.

Un mécanisme fréquemment utilisé pour obtenir le meilleur des deux mondes est appelé blocage automatique. Le blocage automatique transforme le contenu et les métadonnées par défaut en blocs sans que l’auteur ait à les créer physiquement. Le blocage automatique se produit très tôt dans le processus de décoration de la page avant le chargement des blocs. Il s’agit d’une pratique qui crée par programmation la structure DOM d’un bloc comme elle le ferait pour les balises du serveur.

Le blocage automatique est souvent utilisé en combinaison avec les métadonnées, en particulier la propriété template. Si les pages ont un modèle commun, c’est-à-dire qu’elles partagent une conception ou une fonctionnalité de page spécifique, il s’agit généralement d’une bonne occasion pour le blocage automatique.

Un bon exemple est l’en-tête d’article d’un article de blog. Il peut contenir des informations sur l'auteur, le titre de l'article de blog, une image de héros, ainsi que la date de publication. Au lieu de demander à l’auteur de rassembler un bloc contenant toutes ces informations, un bloc automatique (par exemple, bloc article-en-tête) serait ajouté par programmation à la page en fonction de l’élément <h1>, de la première image, de l’auteur du blog et des métadonnées de la date de publication.

Cela permet à l’auteur du contenu de conserver les informations à leur emplacement naturel, la structure du document, à l’extérieur d’un bloc. En même temps, le développeur peut conserver toutes les informations de mise en page et de style dans un bloc.

Un autre cas d’utilisation très courant consiste à encapsuler des blocs autour de liens dans un document. Prenons l’exemple d’un auteur qui crée un lien vers une vidéo YouTube en incluant simplement un lien, tandis que le développeur souhaite conserver l’intégralité du code de la vidéo en ligne dans un bloc de embed.

Ce mécanisme peut également être utilisé de manière flexible pour inclure des applications externes et des références internes à la vidéo, aux fragments de contenu, aux modèles, aux formulaires et à d’autres éléments d’application.

Le code de blocage automatique de vos projets réside en buildAutoBlocks() dans votre scripts.js.

Consultez les exemples suivants de blocage automatique.