Markeringar, avsnitt, block och automatisk blockering

För att designa webbplatser och skapa funktioner använder utvecklarna den kod och det DOM som återges dynamiskt från innehållet. Markeringen och DOM är uppbyggda på ett sätt som möjliggör flexibel redigering och formatering. Samtidigt innehåller det färdiga funktioner så att utvecklaren inte behöver bekymra sig om vissa aspekter av moderna webbplatser.

Dokumentets struktur

Den viktigaste aspekten när man strukturerar ett dokument är att göra det enkelt och intuitivt för författare som ska bidra med innehållet.

Det innebär att vi rekommenderar att författare är mycket involverade i processen. I många fall är det bra att bara låta författare placera det innehåll som ska gå vidare till en sida i ett Google-dokument eller Word-dokument utan att ha någon uppfattning om block och avsnitt, och sedan försöka göra små strukturella ändringar och bara införa avsnitt och block där det behövs.

Ett dokument följer följande struktur i det abstrakta dokumentet.

En sida som den har skapats i Word eller ett Google Doc-dokument använder den välkända semantiska modellen som rubriker, brödtext, listor, bilder, länkar osv. som delas mellan HTML, markdown och Google Doc / Word. Vi ringer det här standardinnehåll. I en idealisk situation lämnar man så mycket som möjligt av det innehåll som skapats som standardinnehåll, eftersom det är det naturliga sättet för författare att behandla dokument.

Förutom standardinnehåll har vi ett sidkoncept avsnitt, avgränsade med vågräta linjer eller --- om du vill gruppera vissa element på en sida tillsammans. Det kan finnas både semantiska och designrelaterade skäl att gruppera innehåll. Ett enkelt exempel är att ett avsnitt på en sida har en annan bakgrundsfärg.

Dessutom finns det block som är skapade som en tabell med en rubrik som den första raden som identifierar typen av block. Det här konceptet är det enklaste sättet att komponera koden.

Avsnitt kan innehålla flera block. Blocks ska aldrig kapslas eftersom det gör det väldigt svårt att använda för författare.

DOM kontra markering

AEM skapar en ren och lättläslig semantisk markering från innehållet som den får. Du kommer enkelt åt den via visningskälla och ta en titt på markeringen för sidan som du läser just nu.

Det JavaScript-bibliotek som används i scripts.js tar in koden och förbättrar den i en DOM som sedan används för de flesta utvecklingsuppgifter, särskilt för att bygga block. Om du vill skapa en DOM som är enkel att arbeta med för anpassad projektkod är det bäst att visa den i två steg.

I det första steget skapar vi markeringen med avsnitt, block och standardinnehåll som ser ut ungefär så här.

I det andra steget utökas markeringen ovan till följande exempel-DOM, som sedan kan användas för formatering och tillägg av funktioner. Skillnaderna mellan den kod som levereras från servern och den utökade DOM som används för de flesta utvecklingsuppgifter markeras nedan.

Det består huvudsakligen av att en wrapper läggs till <div> för block och standardinnehåll och lägga till ytterligare användbara CSS-klasser och dataattribut dynamiskt som används av AEM blockinläsare.

Avsnitt

Avsnitt är ett sätt att gruppera standardinnehåll och -block efter författaren. De flesta tidsavsnittsbrytningar infogas baserat på visuella skillnader mellan avsnitt, t.ex. en annan bakgrundsfärg för en del av en sida.

Ur ett utvecklingsperspektiv är det oftast inte så mycket interaktion med avsnitt utanför CSS-format.
Avsnitt kan innehålla ett speciellt block som kallas Section Metadata, vilket ger dataattribut till ett avsnitt. Namnen på dataattributen kan väljas av författarna, och den enda välkända egenskapen för avsnittsmetadata är Style som kommer att omvandlas till ytterligare CSS-klasser som läggs till i det innehållande avsnittselementet.

Block och standardinnehåll radbryts alltid i ett avsnitt, även om författaren inte särskilt lägger in avsnittsbrytningar.

Standardinnehåll

Det finns ett brett utbud av semantik som delas mellan Word-dokument, Google Docs, markdown och HTML. Det finns till exempel rubriker på olika nivåer (t.ex. <h1> - <h6>), bilder, länkar, listor (<ul>, <ol>), betoning (<em>, <strong>) osv.

Vi drar nytta av den intuitiva förståelse som författare har av hur de kan använda dessa semantik i de verktyg de är bekanta med (t.ex. Word/Google-dokument) och mappar dem till markeringar och återger dem sedan i HTML-koden.

Alla mappningar ska vara relativt enkla och intuitiva för utvecklaren. Ett område där vi går lite längre än den enklaste möjliga översättningen är att hantera bilder. Istället för en enkel <img> tagg, en fullständig <picture> -taggen återges med ett antal olika upplösningar som behövs för visning på stationära datorer och mobila enheter, samt olika format för moderna webbläsare som stöder webben och äldre webbläsare som inte gör det.

Block

De flesta projektspecifika CSS och JavaScript finns i block. Författare skapar block i sina dokument och utvecklare skriver motsvarande kod som formaterar blocken med CSS och/eller dekorerar DOM för att ta markeringen för ett block och omforma den till den struktur som behövs eller är lämplig för önskad formatering och funktionalitet.

Blocknamnet används både som mappnamn för ett block och som filnamn för CSS- och JavaScript-filer som läses in av blockinläsaren när ett block används på en sida. Blocknamnet används också som CSS-klassnamn i blocket för att tillåta intuitiv formatering.

JavaScript läses in som en modul (ESM) och exporterar en standardfunktion som körs som en del av blockinläsningen.

Alla CSS på blocknivå bör omfatta blocket för att säkerställa att det inte finns några biverkningar för andra delar av projektet, vilket innebär att alla väljare i ett block ska föregås av motsvarande blockklass. I vissa fall kan det vara bra att använda blockets wrapper eller innehållsavsnitt även för väljaren.

Det finns en balans mellan DOM-manipulering i JavaScript och CSS-väljarnas komplexitet. Du rekommenderas inte att använda komplicerade CSS-väljare, och samtidigt som du lägger till klasser i varje element blir koden mer komplex och elementens semantik ignoreras.

En av de viktigaste scenerna i ett projekt är att göra det enkelt och intuitivt för skribenterna. Komplexa block gör det svårt att skapa innehåll, så det är viktigt att utvecklare tar till sig komplexiteten i att översätta en intuitiv redigeringsupplevelse till DOM som behövs för layout eller programlogik. Det är ofta frestande att delegera komplexitet till författaren. I stället bör utvecklarna se till att blocken inte blir svårhanterliga för författare. En författare ska alltid kunna kopiera/klistra in ett block och intuitivt förstå vad det handlar om.

Ett enkelt exempel är Kolumnblock. Den lägger till ytterligare klasser i JavaScript baserat på hur många kolumner som finns i respektive instans som har skapats av författaren. På så sätt kan det använda flexibel formatering av innehåll i två kolumner jämfört med tre kolumner.

Blocken kan vara mycket enkla eller innehålla fullständiga programkomponenter eller widgetar och ge utvecklaren ett sätt att komponera kodbasen i små kodstycken som enkelt kan hanteras och som kan läsas in på webbsidorna efter behov.

Innehållet i ett block återges i koden som kapslat <div> -taggar för de rader och kolumner som författaren har angett. I det enklaste fallet har ett block bara en cell.

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

Författare kan lägga till block på sina sidor på ett ad hoc-sätt genom att helt enkelt lägga till en tabell med blocknamnet i den första raden eller tabellrubriken. Vissa block läses också in automatiskt. header och footer -block som måste finnas på varje sida på en webbplats är ett bra exempel på det.

Blockalternativ

Om du behöver ett block som ska se ut eller bete dig lite annorlunda beroende på vissa omständigheter, men inte tillräckligt annorlunda för att bli ett nytt block i sig, kan du låta författarna lägga till blockalternativ till block inom parentes. Dessa alternativ lägger till ändrade klasser i blocket. Till exempel Columns (wide) i en tabellrubrik genererar följande kod.

<div class=”columns wide”>

Blockalternativ kan även innehålla flera ord. Till exempel Columns (super wide) kommer att sammanfogas med bindestreck.

<div class=”columns super-wide”>

Om blockalternativen är kommaavgränsade, till exempel Columns (dark, wide)läggs de till som separata klasser.

<div class=”columns dark wide”>

Automatisk blockering

I ett idealiskt scenario skapas merparten av innehållet utanför blocken, eftersom det blir svårare att läsa och redigera tabeller när du lägger in tabeller i ett dokument. Omvänt fungerar block bra för utvecklare så att de kan hålla ordning på sin kod.

En mekanism som används ofta för att få det bästa av två världar kallas automatisk blockering. Automatisk blockering gör standardinnehåll och standardmetadata till block utan att författaren behöver skapa dem fysiskt. Automatisk blockering sker mycket tidigt i siddekorationsprocessen innan blocken läses in, och det är en metod som programmässigt skapar DOM-strukturen för ett block på samma sätt som den skulle komma som kod från servern.

Automatisk blockering används ofta i kombination med metadata, särskilt template -egenskap. Om sidorna har en gemensam mall, vilket innebär att de delar en viss siddesign eller funktion, är det vanligtvis en bra möjlighet att blockera automatiskt.

Ett bra exempel är en artikelrubrik för ett blogginlägg. Det kan innehålla information om författaren, titeln på blogginlägget, en hjältebild samt publiceringsdatumet. I stället för att författaren ska sätta ihop ett block som innehåller all den informationen, läggs ett automatiskt block (t.ex. artikel-header-block) till på sidan med hjälp av <h1>, den första bilden, bloggförfattaren och metadata för publiceringsdatumet.

Det gör att innehållsförfattaren kan behålla informationen på sin naturliga plats, dokumentstrukturen utanför ett block. Samtidigt kan utvecklaren behålla all layout- och formatinformation i ett block.

Ett annat mycket vanligt användningsområde är att radbryta blocken runt länkar i ett dokument. Ett bra exempel är en författare som länkar till en YouTube-video genom att helt enkelt inkludera en länk, medan utvecklaren vill behålla all kod för den infogade videon i en embed -block.

Den här mekanismen kan också användas som ett flexibelt sätt att inkludera både externa program och interna referenser till video, innehållsfragment, modaler, formulär och andra programelement.

Koden för dina projekt som blockerar automatiskt finns i buildAutoBlocks() i scripts.js.

Se följande exempel på automatisk blockering.