Referenshandbok för komponenter components-reference-guide

Komponenterna utgör kärnan i AEM. Kärnkomponenterna och AEM Project Archetype gör det enkelt att komma igång med en verktygsuppsättning med färdiga, robusta komponenter. WKND-självstudiekursen tar utvecklaren igenom hur de här verktygen används och hur du skapar anpassade komponenter för att skapa en AEM webbplats.

Eftersom WKND-självstudiekursen täcker de flesta användningsfall är det här dokumentet endast avsett som komplement till dessa resurser. Den innehåller detaljerade tekniska detaljer om hur komponenterna är strukturerade och konfigurerade i AEM och är inte avsedd som en guide för att komma igång.

Ökning overview

I det här avsnittet beskrivs viktiga koncept och problem som en introduktion till den information som behövs när du utvecklar egna komponenter.

Planering planning

Innan du börjar konfigurera eller koda komponenten bör du fråga:

Återanvända befintliga komponenter reusing-components

Innan du lägger tid på att skapa en helt ny komponent bör du överväga att anpassa eller utöka befintliga komponenter. Core Components innehåller en serie flexibla, robusta och väl testade produktionsklara komponenter.

Utöka kärnkomponenter extending-core-components

Core Components erbjuder även tydliga anpassningsmönster som du kan använda för att anpassa dem efter ditt eget projekt.

Ersätta komponenter overlying-components

Komponenter kan också definieras om med en övertäckning baserat på sökvägslogiken. I så fall aktiveras emellertid inte delningsresurssammanslagningen och /apps måste definiera hela övertäckningen.

Utöka komponentdialogrutor extending-component-dialogs

Det går också att åsidosätta en komponentdialogruta med Sling Resource Merger och definiera egenskapen sling:resourceSuperType.

Det innebär att du bara behöver definiera om skillnaderna, i stället för att definiera om hela dialogrutan.

Innehållslogik och återgivningsmarkeringar content-logic-and-rendering-markup

Komponenten återges med HTML. Komponenten måste definiera den HTML som behövs för att ta det önskade innehållet och sedan återge det efter behov, både i skribent- och publiceringsmiljöer.

Vi rekommenderar att koden som ansvarar för kod och återgivning hålls åtskild från koden som styr logiken som används för att markera komponentens innehåll.

Den här filosofin stöds av HTL, ett mallspråk som är avsiktligt begränsat för att säkerställa att ett riktigt programmeringsspråk används för att definiera den underliggande affärslogiken. Den här mekanismen markerar koden som anropas för en viss vy och, om det behövs, tillåter specifik logik för olika vyer av samma komponent.

Den här (valfria) logiken kan implementeras på olika sätt och anropas från HTML med specifika kommandon:

Komponentstruktur structure

Strukturen i en AEM är kraftfull och flexibel. Huvuddelarna är:

Resurstyp resource-type

Ett nyckelelement i strukturen är resurstypen.

Detta är en abstraktion som hjälper till att se till att avsikten stannar kvar även när utseendet och känslan förändras över tiden.

Komponentdefinition component-definition

Definitionen av en komponent kan delas upp enligt följande:

Viktiga egenskaper vital-properties

Komponentikon component-icon

Ikonen eller förkortningen för komponenten definieras via JCR-egenskaperna för komponenten när komponenten skapas av utvecklaren. Dessa egenskaper utvärderas i följande ordning och den första giltiga egenskapen som hittas används.

Om inga av ovanstående egenskaper (cq:icon, abbreviation, cq:icon.png eller cq:icon.svg) hittas i komponenten:

Om du vill avbryta arvet av ikoner från superkomponenter återställs standardbeteendet om du anger en tom abbreviation-egenskap för komponenten.

Komponentkonsolen visar hur ikonen för en viss komponent definieras.

Exempel på SVG-ikon svg-icon-example

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "https://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="https://www.w3.org/2000/svg" xmlns:xlink="https://www.w3.org/1999/xlink" x="0px" y="0px"
     width="20px" height="20px" viewBox="0 0 20 20" enable-background="new 0 0 20 20" xml:space="preserve">
    <ellipse cx="5" cy="5" rx="3" ry="3" fill="#707070"/>
    <ellipse cx="15" cy="5" rx="4" ry="4" fill="#707070"/>
    <ellipse cx="5" cy="15" rx="5" ry="5" fill="#707070"/>
    <ellipse cx="15" cy="15" rx="4" ry="4" fill="#707070"/>
</svg>

Egenskaper och underordnade noder för en komponent properties-and-child-nodes-of-a-component

Många av de noder/egenskaper som behövs för att definiera en komponent är gemensamma för båda gränssnitten, men skillnaderna är fortfarande oberoende så att komponenten kan fungera i båda miljöerna.

En komponent är en nod av typen cq:Component och har följande egenskaper och underordnade noder:

Om du tittar på komponenten Text kan du se flera av dessa element:

Egenskaper av särskilt intresse är:

Underordnade noder av särskilt intresse är:

Dialogrutor dialogs

Dialogrutor är ett nyckelelement i komponenten eftersom de tillhandahåller ett gränssnitt där författare kan konfigurera komponenten på en innehållssida och ange indata för den komponenten. Mer information om hur innehållsförfattare interagerar med komponenter finns i redigeringsdokumentationen.

Beroende på komponentens komplexitet kan din dialogruta behöva en eller flera flikar.

Dialogrutor för AEM:

I dialogrutan definieras enskilda fält:

Designdialogrutor design-dialogs

Designdialogrutor liknar dialogrutorna som används för att redigera och konfigurera innehåll, men de ger mallskaparna ett gränssnitt där de kan konfigurera och tillhandahålla designinformation för den komponenten på en sidmall. Sidmallar används sedan av innehållsförfattarna för att skapa innehållssidor. Mer information om hur mallar skapas finns i malldokumentationen.

Designdialogrutor används när du redigerar en sidmall, men de behövs inte för alla komponenter. Till exempel har både Rubrik och Bildkomponenter designdialogrutor, men inte Delningskomponenten för sociala medier.

Gränssnittet för korall och GRENITE coral-and-granite

Gränssnittet Coral och Granite definierar AEM utseende och känsla.

Granite-gränssnittet innehåller ett stort urval av de grundläggande widgetar som behövs för att skapa en dialogruta i redigeringsmiljön. Vid behov kan du utöka den här markeringen och skapa en egen widget.

Mer information finns i följande resurser:

Anpassa dialogrutefält customizing-dialog-fields

Om du vill skapa en widget som ska användas i en komponentdialogruta måste du skapa en del gränssnittskomponent.

Om du ser dialogrutan som en enkel behållare för ett formulärelement kan du även se det primära innehållet i dialogrutan som formulärfält. När du skapar ett nytt formulärfält måste du skapa en resurstyp. Det motsvarar att skapa en komponent. För att du ska få hjälp med den uppgiften erbjuder GRA UI en generisk fältkomponent att ärva från (med sling:resourceSuperType):

/libs/granite/ui/components/coral/foundation/form/field

Mer specifikt ger GRE UI ett antal fältkomponenter som är lämpliga att använda i dialogrutor, eller mer allmänt i formulär.

När du har skapat resurstypen kan du instansiera fältet genom att lägga till en ny nod i dialogrutan, där egenskapen sling:resourceType refererar till den resurstyp som du just har introducerat.

Åtkomst till dialogrutefält access-to-dialog-fields

Du kan också använda återgivningsvillkor (rendercondition) för att kontrollera vem som har åtkomst till specifika flikar/fält i dialogrutan, till exempel:

+ mybutton
  - sling:resourceType = granite/ui/components/coral/foundation/button
  + rendercondition
    - sling:resourceType = myapp/components/renderconditions/group
    - groups = ["administrators"]

Använda komponenter using-components

När du har skapat en komponent måste du aktivera den för att kunna använda den. När du använder den visas hur komponentens struktur förhåller sig till strukturen för det resulterande innehållet i databasen.

Lägga till komponenten i mallen adding-your-component-to-the-template

När en komponent har definierats måste den göras tillgänglig för användning. Om du vill göra en komponent tillgänglig för användning i en mall måste du aktivera komponenten i principen för mallens layoutbehållare.

Mer information om hur mallar skapas finns i malldokumentationen.

Komponenter och det innehåll de skapar components-and-the-content-they-create

Om vi skapar och konfigurerar en instans av komponenten Title på sidan: /content/wknd/language-masters/en/adventures/extreme-ironing.html

Sedan kan vi se strukturen för det innehåll som skapas i databasen:

Om du tittar på den faktiska texten i en titelkomponent:

De definierade egenskaperna är beroende av de enskilda definitionerna. Även om de kan vara mer komplexa än tidigare följer de fortfarande samma grundläggande principer.

Komponenthierarki och arv component-hierarchy-and-inheritance

Komponenter i AEM omfattas av Resurstyphierarkin. Detta används för att utöka komponenter med egenskapen sling:resourceSuperType. Detta gör att komponenten kan ärva från en annan komponent.

Mer information finns i avsnittet Återanvända komponenter.

Redigera beteende edit-behavior

I det här avsnittet beskrivs hur du konfigurerar redigeringsbeteendet för en komponent. Detta inkluderar attribut som åtgärder som är tillgängliga för komponenten, egenskaper för in.place-redigeraren och avlyssnare som relaterar till händelser för komponenten.

Redigeringsbeteendet för en komponent konfigureras genom att en cq:editConfig-nod av typen cq:EditConfig läggs till under komponentnoden (av typen cq:Component) och genom att specifika egenskaper och underordnade noder läggs till. Följande egenskaper och underordnade noder är tillgängliga:

Det finns många befintliga konfigurationer i AEM. Du kan enkelt söka efter specifika egenskaper eller underordnade noder med hjälp av frågeverktyget i CRXDE Lite.

Komponentplatshållare component-placeholders

Komponenter måste alltid återge viss HTML som är synlig för författaren, även när komponenten inte har något innehåll. I annat fall försvinner det visuellt från redigerarens gränssnitt, vilket gör det tekniskt möjligt men osynligt på sidan och i redigeraren. I så fall kan författarna inte markera och interagera med den tomma komponenten.

Därför bör komponenter återge en platshållare så länge de inte återger några synliga utdata när sidan återges i sidredigeraren (när WCM-läget är edit eller preview).
Den typiska HTML-koden för en platshållare är följande:

<div class="cq-placeholder" data-emptytext="Component Name"></div>

Det typiska HTL-skriptet som återger platshållaren HTML är följande:

<div class="cq-placeholder" data-emptytext="${component.properties.jcr:title}"
     data-sly-test="${(wcmmode.edit || wcmmode.preview) && isEmpty}"></div>

I föregående exempel är isEmpty en variabel som bara är true när komponenten inte har något innehåll och är osynlig för författaren.

För att undvika upprepningar rekommenderar Adobe att komponentimplementerare använder en HTML-mall för dessa platshållare, som den som finns i Core Components.

Mallen i den föregående länken används sedan med följande rad i HTML:

<sly data-sly-use.template="core/wcm/components/commons/v1/templates.html"
     data-sly-call="${template.placeholder @ isEmpty=!model.text}"></sly>

I det föregående exemplet är model.text variabeln som är sann bara när innehållet har innehåll och är synligt.

Ett exempel på hur den här mallen används visas i kärnkomponenterna, t.ex. i titelkomponenten.

Konfigurera med cq:EditConfig-underordnade noder configuring-with-cq-editconfig-child-nodes

Släpp Assets i en dialogruta - cq:dropTargets cq-droptargets

Noden cq:dropTargets (nodtypen nt:unstructured) definierar släppmålet som kan acceptera en släppning från en resurs som dras från innehållssökaren. Det är en nod av typen cq:DropTargetConfig.

Den underordnade noden av typen cq:DropTargetConfig definierar ett släppmål i komponenten.

lokal redigering - cq:inplaceEditing cq-inplaceediting

Med en lokal redigerare kan användaren redigera innehåll direkt i innehållsflödet utan att behöva öppna någon dialogruta. Standardkomponenterna Text och Title har till exempel båda en redigerare på plats.

En redigerare på plats är inte nödvändig/meningsfull för varje komponenttyp.

Noden cq:inplaceEditing (nodtyp cq:InplaceEditingConfig) definierar en redigeringskonfiguration på plats för komponenten. Den kan ha följande egenskaper:

Följande konfiguration aktiverar redigering på plats för komponenten och definierar plaintext som redigerartyp:

    <cq:inplaceEditing
        jcr:primaryType="cq:InplaceEditingConfig"
        active="{Boolean}true"
        editorType="plaintext"/>

Hantera fälthändelser - cq:avlyssnare cq-listeners

Metoden för att hantera händelser i dialogfält utförs med avlyssnare i ett anpassat klientbibliotek.

Om du vill mata in logik i fältet bör du:

För att uppnå detta måste du känna till det underliggande widgetbiblioteket som du vill interagera med. Se dokumentationen för det korallella användargränssnittet för att identifiera vilken händelse du vill reagera på.

Noden cq:listeners (nodtyp cq:EditListenersConfig) definierar vad som händer före eller efter en åtgärd på komponenten. I följande tabell definieras dess möjliga egenskaper.

Händelsehanteraren kan implementeras med en anpassad implementering. (där project.customerAction är en statisk metod):

afteredit = "project.customerAction"

Följande exempel motsvarar konfigurationen REFRESH_INSERTED:

afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"

Med följande konfiguration uppdateras sidan när komponenten har tagits bort, redigerats, infogats eller flyttats:

    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afterdelete="REFRESH_PAGE"
        afteredit="REFRESH_PAGE"
        afterinsert="REFRESH_PAGE"
        afterMove="REFRESH_PAGE"/>

Fältvalidering field-validation

Fältvalidering i GRENITUI och GRENITUI-widgetar görs med API:t foundation-validation. Mer information finns i foundation-valdiation Granite-dokumentationen.

Dialogrutans tillgänglighet identifieras dialog-ready

Om du har en anpassad JavaScript som endast måste köras när dialogrutan är tillgänglig och klar bör du lyssna efter händelsen dialog-ready.

Den här händelsen utlöses när dialogrutan läses in (eller läses in igen) och är klar att användas, vilket innebär när det finns en ändring (skapa/uppdatera) i DOM för dialogrutan.

dialog-ready kan användas för att koppla i anpassad JavaScript-kod som utför anpassningar av fälten i en dialogruta eller liknande åtgärder.

Förhandsvisningsbeteende preview-behavior

Cookien WCM-läge anges när du växlar till förhandsgranskningsläget även när sidan inte uppdateras.

Komponenter med en återgivning som är känslig för WCM-läget måste definieras så att de uppdateras specifikt och sedan förlitar sig på värdet för cookien.

Dokumentera komponenter documenting-components

Som utvecklare vill du ha enkel åtkomst till komponentdokumentation så att du snabbt kan förstå komponentens:

Därför är det ganska enkelt att göra befintliga dokumentationsmarkeringar tillgängliga i själva komponenten.

Allt du behöver göra är att placera en README.md-fil i komponentstrukturen.

Den här markeringen visas sedan i komponentkonsolen.

Den kod som stöds är densamma som den som används för innehållsfragment.