Balisage, sections, blocs et blocage automatique

Pour concevoir des sites web et créer des fonctionnalités, les développeurs utilisent les balises et le modèle DOM qui sont rendus 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, il fournit des fonctionnalités prêtes à l’emploi afin que le développeur n’ait pas à se soucier de certains aspects des sites web modernes.

Structure d’un document

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

Cela signifie qu’il est fortement recommandé d’impliquer les auteurs très tôt dans le processus. Dans de nombreux cas, il est recommandé de simplement laisser les auteurs placer le contenu qui doit accéder à une page dans un document Google Doc ou Word sans avoir aucune notion de blocs et de section, puis d’effectuer de petits changements structurels et d’introduire des sections et des blocs uniquement lorsque cela est nécessaire.

Un document suit la structure suivante en abstrait.

Une page telle qu’elle est créée dans Word ou un document Google Doc utilise un modèle sémantique bien compris, comme des en-têtes, du texte intégral, des listes, des images, des 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 laissez autant de contenu créé que possible par défaut, puisque c’est la manière naturelle pour les auteurs de traiter les documents.

Outre le contenu par défaut, nous disposons d’un concept de page. sections, séparés par des règles horizontales ou --- pour regrouper certains éléments d’une page. Il peut y avoir des raisons sémantiques et de conception pour regrouper le contenu. Un cas simple peut être qu’une section d’une page a une couleur d’arrière-plan différente.

En plus, il existe un concept : blocs qui sont créées 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 intégrer votre code.

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

DOM et balisage

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

La bibliothèque JavaScript utilisée dans scripts.js prend les balises et les améliore dans 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 sous la forme d’un processus en deux étapes.

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

Dans la seconde étape, le balisage ci-dessus est augmenté dans l’exemple DOM suivant, qui peut ensuite être utilisé pour le style et l’ajout de fonctionnalités. Les différences entre les balises fournies par le serveur et le DOM augmenté utilisé pour la plupart des tâches de développement sont présentées ci-dessous.

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

Sections

Les sections permettent de regrouper le contenu par défaut et les blocs par l’auteur. La plupart des sauts de section sont introduits en fonction des différences visuelles entre les sections, telles qu’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’interactions avec les sections en dehors du style CSS.
Les sections peuvent contenir un bloc spécial appelé Section Metadata, ce qui génère des attributs de données vers une section . Les auteurs peuvent choisir les noms des attributs de données, et la seule propriété de métadonnées de section bien connue est Style qui sera transformé en classes CSS supplémentaires ajoutées à l’élément de section contenant .

Les blocs et le contenu par défaut sont toujours encapsulé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 qui sont partagées entre des documents Word, des documents Google, des balises et des HTMLS. Par exemple, il existe des en-têtes de différents niveaux (par exemple, <h1> - <h6>), images, liens, listes (<ul>, <ol>), mise (<em>, <strong>), etc.

Nous profitons de la compréhension intuitive que les auteurs ont de la manière d’utiliser ces sémantiques dans les outils qu’ils connaissent (par exemple, Word/Google) et les mappe à Markdown puis les effectue dans le balisage de HTML.

Tous les mappages doivent être relativement simples et intuitifs pour le développeur. Un domaine où nous allons un peu plus loin que la traduction la plus simple possible est celui de la gestion des images. Au lieu d’une <img> balise, complète <picture> La balise est rendue avec un certain nombre de résolutions différentes nécessaires pour 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 les navigateurs plus anciens qui ne le font pas.

Blocs

La plupart des fichiers CSS et JavaScript spécifiques au projet résident dans des blocs. Les auteurs créent des blocs dans leurs documents et les développeurs écrivent le code correspondant qui style les 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 sur le bloc pour permettre un style intuitif.

Le code 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.

Toutes les feuilles CSS de niveau bloc doivent être incluses dans le bloc pour s’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 comporter le 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 complexes et fragile 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 compliqués rendent difficile la création de contenu. Il est donc important que les développeurs absorbent la complexité liée à la traduction d’une expérience de création intuitive dans le modèle DOM nécessaire à la mise en page ou à la logique de l’application. Il est souvent tentant de déléguer 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 pouvoir copier/coller un bloc et comprendre intuitivement de quoi il retourne.

Voici un exemple simple : Bloc de colonnes. Il ajoute des classes supplémentaires dans JavaScript en fonction du nombre de colonnes dans l’instance correspondante créée par l’auteur. Cela lui permet d’utiliser un style flexible de contenu qui se trouve en deux colonnes plutôt qu’en trois colonnes.

Les blocs peuvent être très simples ou contenir des composants ou des widgets d’application complets et fournir au développeur un moyen de composants de leur code base 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 comme imbriqué. <div> balises pour les lignes et les colonnes saisies par l’auteur. Dans le cas le plus simple, un bloc ne possède 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 le premier en-tête de ligne ou de tableau. Certains blocs sont également chargés automatiquement. header et footer les blocs qui doivent être présents sur chaque page d’un site en sont un bon exemple.

Options de bloc

Si vous avez besoin d’un bloc pour l’aspect ou le comportement légèrement différent selon certaines circonstances, mais pas assez différent pour devenir un nouveau bloc, vous pouvez permettre aux auteurs d’ajouter options de bloc aux blocs entre parenthèses. Ces options ajoutent des classes modifiées au bloc. Par exemple Columns (wide) dans un en-tête de tableau génère les balises suivantes.

<div class=”columns wide”>

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

<div class=”columns super-wide”>

Si les options de bloc sont séparées par des virgules, telles que Columns (dark, wide), ils seront ajoutés 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 rend la lecture et la modification plus difficiles. À l’inverse, les blocs offrent un excellent mécanisme permettant aux développeurs de conserver 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 survient très tôt dans le processus de décoration de page avant le chargement des blocs. C’est une pratique qui crée par programmation la structure DOM d’un bloc, car elle serait fournie comme balisage à partir du serveur.

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

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

Cela permet à l’auteur de contenu de conserver l’information à son emplacement naturel, c’est-à-dire 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. Un bon exemple est un auteur qui crée un lien vers une vidéo YouTube en incluant simplement un lien, tandis que le développeur souhaite que tout le code de la vidéo reste intégré dans une embed bloque.

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

Le code de vos projets bloque automatiquement des vies dans buildAutoBlocks() dans votre scripts.js.

Consultez les exemples suivants de blocage automatique.