Marcação, Seções, Blocos e Bloqueio automático

Para projetar sites e criar funcionalidades, os desenvolvedores usam a marcação e o DOM renderizados dinamicamente a partir do conteúdo. A marcação e o DOM são construídos de forma a permitir manipulação e estilo flexíveis. Ao mesmo tempo, ele fornece funcionalidade pronta para uso para que o desenvolvedor não tenha que se preocupar com alguns dos aspectos dos sites modernos.

Estrutura de um documento

O único aspecto mais importante ao estruturar um documento é torná-lo simples e intuitivo para os autores que contribuirão com o conteúdo.

Isso significa que é altamente recomendável envolver os autores muito cedo no processo. Em muitos casos, é uma boa prática permitir que os autores coloquem o conteúdo necessário para ir para uma página em um documento Google Doc ou Word sem ter qualquer noção de blocos e seção. Em seguida, tente fazer pequenas alterações estruturais e introduzir seções e blocos somente quando necessário.

Um documento segue a seguinte estrutura em abstrato.

Uma página criada no Word ou em um documento do Google Doc usa o modelo semântico bem entendido, como cabeçalhos, corpo de texto, listas, imagens, links etc. que é compartilhado entre o HTML, o Markdown e o Google Doc/Word. Nós chamamos isso de conteúdo padrão. Em uma situação ideal, deixaria o máximo possível do conteúdo criado como conteúdo padrão, já que essa é a maneira natural de os autores tratarem os documentos.

Além do conteúdo padrão, temos um conceito de página seções, separados por réguas horizontais ou --- para agrupar determinados elementos de uma página. Pode haver motivos semânticos e de design para agrupar o conteúdo. Um caso simples pode ser uma seção de uma página com uma cor de fundo diferente.

Além disso, existe o conceito de blocos que são criados como uma tabela com um cabeçalho como a primeira linha que identifica o tipo de bloco. Esse conceito é a abordagem mais fácil para componentizar seu código.

As seções podem conter vários blocos. Os blocos nunca devem ser aninhados, pois dificulta muito o uso para autores.

DOM versus Marcação

O AEM produz uma marcação semântica limpa e facilmente legível a partir do conteúdo que é fornecido a ele. Você pode acessá-lo facilmente usando o exibir origem e observe a marcação da página que você está lendo no momento.

A biblioteca JavaScript do usada no scripts.js A pega a marcação e a aprimora em um DOM que é usado para a maioria das tarefas de desenvolvimento, especificamente para criar blocos. Para criar um DOM fácil de trabalhar com para código de projeto personalizado, é melhor visualizá-lo como um processo de duas etapas.

Na primeira etapa, criamos a marcação com seções, blocos e conteúdo padrão que serão semelhantes a este.

Na segunda etapa, a marcação acima é aumentada para o seguinte exemplo de DOM, que pode ser usado para estilizar e adicionar funcionalidade. As diferenças entre a marcação entregue pelo servidor e o DOM aumentado usado para a maioria das tarefas de desenvolvimento estão destacadas abaixo.

Consiste principalmente em introduzir um invólucro <div> para blocos e conteúdo padrão e adição dinâmica de classes CSS úteis e atributos de dados adicionais que são usados pelo carregador de bloco AEM.

Seções

As seções são uma maneira de agrupar o conteúdo e os blocos padrão pelo autor. Na maioria das vezes, as quebras de seção são introduzidas com base em diferenças visuais entre seções, como uma cor de fundo diferente para uma parte de uma página.

De uma perspectiva de desenvolvimento, geralmente não há muita interação com seções além do estilo CSS.
As seções podem conter um bloco especial chamado Section Metadata, que resulta em atributos de dados para uma seção. Os nomes dos atributos de dados podem ser escolhidos pelos autores, e a única propriedade de metadados de seção conhecida é Style que será transformada em classes CSS adicionais adicionadas ao elemento da seção que as contém.

Os blocos e o conteúdo padrão são sempre envolvidos em uma seção, mesmo se o autor não introduzir especificamente quebras de seção.

Conteúdo padrão

Há uma ampla variedade de semânticas que são compartilhadas entre documentos do Word, documentos do Google, markdown e HTML. Por exemplo, há cabeçalhos de diferentes níveis (por exemplo, <h1> - <h6>), imagens, links, listas (<ul>, <ol>), ênfase (<em>, <strong>) etc.

Aproveitamos a compreensão intuitiva que os autores têm de como usar essa semântica nas ferramentas com as quais estão familiarizados (p. ex., documentos do Word/Google), mapeia-os para marcação e os renderiza na marcação HTML.

Todos os mapeamentos devem ser relativamente simples e intuitivos para o desenvolvedor. Uma área em que vamos um pouco além da tradução mais simples possível é manusear imagens. Em vez de um simples <img> tag, uma chamada completa <picture> A tag do é renderizada com várias resoluções diferentes necessárias para exibição em dispositivos móveis e de desktop, bem como formatos diferentes para navegadores modernos que oferecem suporte a navegadores da web e navegadores mais antigos que não.

Blocos

A maioria do CSS e do JavaScript específicos do projeto vive em blocos. Os autores criam blocos em seus documentos e os desenvolvedores escrevem o código correspondente que estimula os blocos com CSS e/ou decora o DOM para pegar a marcação de um bloco e transformá-lo na estrutura necessária ou conveniente para o estilo e a funcionalidade desejados.

O nome do bloco é usado como o nome da pasta de um bloco, bem como o nome do arquivo CSS e JavaScript que são carregados pelo carregador de bloco quando um bloco é usado em uma página. O nome do bloco também é usado como o nome da classe CSS no bloco para permitir o estilo intuitivo.

O JavaScript é carregado como um Módulo (ESM) e exporta uma função padrão que é executada como parte do carregamento do bloco.

Todos os CSS de nível de bloco devem ter o escopo definido para o bloco para garantir que não haja efeitos colaterais para outras partes do projeto, o que significa que todos os seletores em um bloco devem ter o prefixo da classe de bloco correspondente. Em certos casos, faz sentido usar também o invólucro do bloco ou a seção que contém o seletor.

Há um equilíbrio entre a manipulação de DOM em JavaScript e a complexidade dos seletores de CSS. Seletores de CSS frágeis complexos não são recomendados e, ao mesmo tempo, adicionar classes a cada elemento torna seu código mais complexo e ignora a semântica dos elementos.

Um dos princípios mais importantes de um projeto é manter as coisas simples e intuitivas para os autores. Blocos complicados dificultam a criação de conteúdo, portanto, é importante que os desenvolvedores absorvam a complexidade de traduzir uma experiência de criação intuitiva no DOM, necessária para o layout ou a lógica do aplicativo. Geralmente é tentador delegar complexidade ao autor. Em vez disso, os desenvolvedores devem se certificar de que os blocos não se tornem difíceis de criar para os autores. Um autor deve sempre ser capaz de simplesmente copiar/colar um bloco e entender intuitivamente sobre o que se trata.

Um exemplo simples é o Bloco de colunas. Ele adiciona classes adicionais no JavaScript com base no número de colunas na respectiva instância criada pelo autor. Isso permite usar um estilo flexível de conteúdo em duas colunas, em vez de três colunas.

Os blocos podem ser muito simples ou conter componentes ou widgets completos do aplicativo e fornecem uma maneira para o desenvolvedor componentizar sua base de código em pequenos blocos de código que podem ser gerenciados facilmente e carregados nas páginas da Web, conforme necessário.

O conteúdo de um bloco é renderizado na marcação como aninhado <div> marcas para as linhas e colunas inseridas pelo autor. No caso mais simples, um bloco tem apenas uma única célula.

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

Os autores podem adicionar blocos a suas páginas de maneira ad-hoc simplesmente adicionando uma tabela com o nome do bloco na primeira linha ou no cabeçalho da tabela. Alguns blocos também são carregados automaticamente. header e footer Os blocos que precisam estar presentes em cada página de um site são um bom exemplo disso.

Opções de bloco

Se você precisar de um bloco para ter aparência ou comportamento um pouco diferente com base em determinadas circunstâncias, mas não diferente o suficiente para se tornar um novo bloco em si, é possível permitir que os autores adicionem opções de bloqueio para blocos entre parênteses. Essas opções adicionam classes modificadas ao bloco. Por exemplo Columns (wide) em um cabeçalho de tabela gerará a seguinte marcação.

<div class=”columns wide”>

As opções de Bloqueio também podem conter várias palavras. Por exemplo Columns (super wide) serão concatenados usando hifens.

<div class=”columns super-wide”>

Se as opções de bloco forem separadas por vírgulas, como Columns (dark, wide), elas serão adicionadas como classes separadas.

<div class=”columns dark wide”>

Bloqueio automático

Em um cenário ideal, a maioria do conteúdo é criada fora dos blocos, pois introduzir tabelas em um documento dificulta a leitura e a edição. Por outro lado, os blocos fornecem um ótimo mecanismo para os desenvolvedores manterem seus códigos organizados.

Um mecanismo usado com frequência para obter o melhor dos dois mundos é chamado de bloqueio automático. O bloqueio automático transforma o conteúdo padrão e os metadados em blocos sem que o autor precise criá-los fisicamente. O bloqueio automático ocorre muito cedo no processo de decoração da página, antes que os blocos sejam carregados, e é uma prática que cria programaticamente a estrutura DOM de um bloco, como ela viria como marcação do servidor.

O bloqueio automático geralmente é usado em combinação com metadados, especialmente o template propriedade. Se as páginas tiverem um modelo comum, o que significa que elas compartilham um determinado design ou funcionalidade de página, geralmente é uma boa oportunidade para o bloqueio automático.

Um bom exemplo é um cabeçalho de artigo de uma publicação do blog. Ele pode conter informações sobre o autor, o título da publicação do blog, uma imagem herói, bem como a data de publicação. Em vez de o autor reunir um bloco que contém todas essas informações, um bloco automático (por exemplo, bloco do cabeçalho do artigo) seria adicionado programaticamente à página com base no <h1>, a primeira imagem, o autor do blog e os metadados de data de publicação.

Isso permite que o autor de conteúdo mantenha as informações em seu lugar natural, a estrutura do documento fora de um bloco. Ao mesmo tempo, o desenvolvedor pode manter todas as informações de layout e estilo em um bloco.

Outro caso de uso muito comum é envolver blocos ao redor de links em um documento. Um bom exemplo é um autor vinculando a um vídeo do YouTube simplesmente incluindo um link, enquanto o desenvolvedor gostaria de manter todo o código do vídeo incorporado em uma embed bloco.

Esse mecanismo também pode ser usado como uma maneira flexível de incluir aplicativos externos e referências internas a vídeo, fragmentos de conteúdo, modais, formulários e outros elementos do aplicativo.

O código do bloqueio automático de seus projetos reside em buildAutoBlocks() no seu scripts.js.

Consulte os seguintes exemplos de bloqueio automático.