Markup, sezioni, blocchi e blocco automatico

Per progettare siti web e creare funzionalità, gli sviluppatori utilizzano il markup e il DOM renderizzati dinamicamente dal contenuto. Il markup e il DOM sono costruiti in modo da consentire una manipolazione e uno stile flessibili. Allo stesso tempo fornisce funzionalità pronte all’uso in modo che lo sviluppatore non debba preoccuparsi di alcuni degli aspetti dei siti web moderni.

Struttura di un documento

L'aspetto più importante nella strutturazione di un documento è quello di renderlo semplice e intuitivo per gli autori che contribuiranno al contenuto.

Ciò significa che si consiglia vivamente di coinvolgere gli autori nelle fasi iniziali del processo. In molti casi, è buona prassi consentire agli autori di inserire semplicemente il contenuto necessario per passare a una pagina in un documento Google Doc o Word senza avere alcuna nozione di blocchi e sezioni, quindi provare ad apportare piccole modifiche strutturali e introdurre sezioni e blocchi solo dove necessario.

Un documento segue la seguente struttura in astratto.

Una pagina creata in un documento Word o Google Doc utilizza il modello semantico noto come intestazioni, corpo del testo, elenchi, immagini, collegamenti e così via. condiviso tra HTML, markdown e Google Doc/Word. Questo lo chiamiamo contenuto predefinito. In una situazione ideale, si tratterebbe di lasciare la maggior parte dei contenuti creati come contenuti predefiniti possibile, in quanto questo è il modo naturale per gli autori di trattare i documenti.

Oltre al contenuto predefinito, abbiamo un concetto di pagina sezioni, separati da regole orizzontali o --- per raggruppare alcuni elementi di una pagina. Per raggruppare i contenuti possono essere necessari motivi semantici e di progettazione. Un caso semplice potrebbe essere che una sezione di una pagina abbia un colore di sfondo diverso.

Oltre a ciò, esiste il concetto di blocchi creati come tabella con un’intestazione come prima riga che identifica il tipo di blocco. Questo concetto è l’approccio più semplice per comporre il codice.

Le sezioni possono contenere più blocchi. I blocchi non devono mai essere nidificati, in quanto rende molto difficile l’utilizzo per gli autori.

DOM e markup

L’AEM produce un markup semantico chiaro e facilmente leggibile dal contenuto fornito. Puoi accedervi facilmente utilizzando visualizza origine e dare un'occhiata al markup della pagina che stai leggendo.

Libreria JavaScript utilizzata in scripts.js prende il markup e lo migliora in un DOM che viene quindi utilizzato per la maggior parte delle attività di sviluppo, in particolare per la creazione di blocchi. Per creare un DOM facile da usare con il codice di progetto personalizzato, è meglio visualizzarlo come un processo in due fasi.

Nel primo passaggio, creiamo il markup con sezioni, blocchi e contenuto predefinito simili a questo.

Nel secondo passaggio, il ricarico di cui sopra viene incrementato nel DOM di esempio seguente, che può quindi essere utilizzato per lo stile e l’aggiunta di funzionalità. Di seguito sono evidenziate le differenze tra il markup distribuito dal server e il DOM incrementato utilizzato per la maggior parte delle attività di sviluppo.

Si tratta principalmente di introdurre un involucro <div> per blocchi e contenuto predefinito e per aggiungere in modo dinamico utili classi CSS e attributi di dati aggiuntivi utilizzati dal caricatore di blocchi AEM.

Sezioni

Le sezioni sono un modo per raggruppare il contenuto predefinito e i blocchi dell’autore. La maggior parte delle interruzioni di sezione temporali viene introdotta in base alle differenze visive tra sezioni, ad esempio un colore di sfondo diverso per una parte di una pagina.

Dal punto di vista dello sviluppo, di solito non c’è molta interazione con le sezioni oltre lo stile CSS.
Le sezioni possono contenere un blocco speciale denominato Section Metadata, che genera attributi di dati per una sezione. I nomi degli attributi di dati possono essere scelti dagli autori e l’unica proprietà nota dei metadati della sezione è Style che verranno convertite in classi CSS aggiuntive aggiunte all’elemento della sezione contenitore.

I blocchi e il contenuto predefinito vengono sempre racchiusi in una sezione, anche se l’autore non introduce specificatamente interruzioni di sezione.

Contenuto predefinito

Esiste un'ampia gamma di semantiche condivise tra documenti di Word, documenti di Google, markdown e HTML. Ad esempio, ci sono intestazioni di diversi livelli (es. <h1> - <h6>), immagini, collegamenti, elenchi (<ul>, <ol>), enfasi (<em>, <strong>) ecc.

Approfittiamo della comprensione intuitiva che gli autori hanno di come utilizzare questa semantica negli strumenti che hanno familiarità con (p. es. Documenti Word/Google) e li associa a markdown e li riproduce nel markup HTML.

Tutte le mappature devono essere relativamente semplici e intuitive per lo sviluppatore. Un'area in cui andiamo un po' più in là della traduzione più semplice possibile è la gestione delle immagini. Invece di un semplice <img> tag, un tag completo <picture> viene eseguito il rendering del tag con una serie di diverse risoluzioni necessarie per la visualizzazione su dispositivi desktop e mobili, nonché diversi formati per i browser moderni che supportano webp e browser meno recenti che non lo supportano.

Blocchi

La maggior parte dei CSS e JavaScript specifici per il progetto risiede in blocchi. Gli autori creano blocchi nei loro documenti e gli sviluppatori scrivono il codice corrispondente che assegna ai blocchi uno stile CSS e/o decorano il DOM in modo da prendere il markup di un blocco e trasformarlo nella struttura necessaria o conveniente per lo stile e la funzionalità desiderati.

Il nome del blocco viene utilizzato sia come nome della cartella di un blocco che come nome del file per i file CSS e JavaScript caricati dal caricatore di blocchi quando un blocco viene utilizzato su una pagina. Il nome del blocco viene utilizzato anche come nome della classe CSS sul blocco per consentire uno stile intuitivo.

Il JavaScript viene caricato come modulo (ESM) ed esporta una funzione predefinita che viene eseguita come parte del caricamento del blocco.

Tutti i CSS a livello di blocco devono avere l’ambito del blocco per garantire che non vi siano effetti collaterali per altre parti del progetto, il che significa che tutti i selettori in un blocco devono essere preceduti dalla classe di blocco corrispondente. In alcuni casi è utile utilizzare anche l’involucro del blocco o la sezione contenitore per il selettore.

Esiste un equilibrio tra la manipolazione DOM in JavaScript e la complessità dei selettori CSS. I selettori CSS fragili e complessi non sono consigliati e allo stesso tempo l’aggiunta di classi a ogni elemento rende il codice più complesso e ignora la semantica degli elementi.

Uno dei principi più importanti di un progetto è quello di mantenere le cose semplici e intuitive per gli autori. I blocchi complicati rendono difficile l’authoring dei contenuti, pertanto è importante che gli sviluppatori assorbano la complessità di tradurre un’esperienza di authoring intuitiva nel DOM necessaria per la logica di layout o applicazione. Spesso si tende a delegare la complessità all’autore. Al contrario, gli sviluppatori devono assicurarsi che i blocchi non diventino ingombranti da creare per gli autori. Un autore dovrebbe sempre essere in grado di copiare/incollare semplicemente un blocco e di capirne intuitivamente la funzione.

Un semplice esempio è il Blocco colonne. Aggiunge classi aggiuntive in JavaScript in base al numero di colonne presenti nella rispettiva istanza creata dall’autore. Questo gli consente di utilizzare uno stile flessibile per contenuti composti da due colonne e tre colonne.

I blocchi possono essere molto semplici o contenere componenti o widget di applicazioni completi e consentono allo sviluppatore di comporre la base di codice in piccoli blocchi di codice che possono essere gestiti facilmente e caricati sulle pagine web in base alle esigenze.

Il contenuto di un blocco viene renderizzato nel markup come nidificato <div> tag per le righe e le colonne immesse dall’autore. Nel caso più semplice, un blocco ha una sola cella.

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

Gli autori possono aggiungere blocchi alle proprie pagine in modo ad hoc semplicemente aggiungendo una tabella con il nome del blocco nella prima riga o intestazione di tabella. Alcuni blocchi vengono inoltre caricati automaticamente. header e footer I blocchi che devono essere presenti in ogni pagina di un sito sono un buon esempio.

Opzioni di blocco

Se un blocco deve avere un aspetto o un comportamento leggermente diverso a seconda di determinate circostanze, ma non abbastanza diverso da diventare un nuovo blocco in sé, puoi consentire agli autori di aggiungere opzioni di blocco tra parentesi. Queste opzioni aggiungono classi modificate al blocco. Ad esempio Columns (wide) in un'intestazione di tabella genererà il seguente markup.

<div class=”columns wide”>

Le opzioni di blocco possono inoltre contenere più parole. Ad esempio Columns (super wide) verrà concatenato utilizzando i trattini.

<div class=”columns super-wide”>

Se le opzioni del blocco sono separate da virgole, ad esempio Columns (dark, wide), verranno aggiunte come classi separate.

<div class=”columns dark wide”>

Blocco automatico

In uno scenario ideale, la maggior parte dei contenuti viene creata al di fuori dei blocchi, in quanto l’introduzione di tabelle in un documento rende più difficile la lettura e la modifica. Al contrario, i blocchi forniscono un ottimo meccanismo agli sviluppatori per mantenere organizzato il proprio codice.

Un meccanismo utilizzato di frequente per ottenere il meglio da entrambi i mondi è chiamato blocco automatico. Il blocco automatico trasforma il contenuto e i metadati predefiniti in blocchi senza che l’autore debba crearli fisicamente. Il blocco automatico si verifica molto presto nel processo di decorazione della pagina prima che i blocchi vengano caricati ed è una pratica che crea a livello di programmazione la struttura DOM di un blocco, come avverrebbe come markup dal server.

Il blocco automatico viene spesso utilizzato in combinazione con i metadati, in particolare template proprietà. Se le pagine hanno un modello comune, il che significa che condividono una certa struttura o funzionalità di pagina, in genere si tratta di una buona opportunità per il blocco automatico.

Un buon esempio è l'intestazione di un articolo di un post di blog. Potrebbe contenere informazioni sull'autore, il titolo del post del blog, un'immagine protagonista, così come la data di pubblicazione. Invece di creare un blocco contenente tutte queste informazioni, un blocco automatico (ad esempio un blocco intestazione articolo) verrebbe aggiunto alla pagina a livello di programmazione in base al valore <h1>, la prima immagine, l’autore del blog e i metadati della data di pubblicazione.

Questo consente all’autore di contenuto di mantenere le informazioni al loro posto naturale, ovvero la struttura del documento al di fuori di un blocco. Allo stesso tempo, lo sviluppatore può mantenere tutte le informazioni di layout e stile in un blocco.

Un altro caso d’uso molto comune è quello di disporre i blocchi attorno ai collegamenti in un documento. Un buon esempio è l’autore che collega a un video di YouTube semplicemente includendo un collegamento, mentre lo sviluppatore desidera mantenere tutto il codice del video in linea incorporato in un embed blocco.

Questo meccanismo può essere utilizzato anche come modo flessibile per includere sia applicazioni esterne che riferimenti interni a video, frammenti di contenuto, modali, moduli e altri elementi applicativi.

Il codice per il blocco automatico dei progetti risiede in buildAutoBlocks() nel tuo scripts.js.

Vedi i seguenti esempi di blocco automatico.