Referenshandbok för komponenter

Komponenterna utgör kärnan i AEM. The Kärnkomponenter och AEM Project Archetype gör det enkelt att komma igång med en verktygsuppsättning med färdiga, robusta komponenter. The WKND - självstudiekurs tar utvecklaren igenom hur dessa verktyg används och hur man bygger anpassade komponenter för att skapa en ny AEM.

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.

Översikt

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

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

• Vad behöver du den nya komponenten till?
• Behöver du skapa komponenten från grunden, eller kan du ärva grunderna från en befintlig komponent?
• Kommer din komponent att behöva logik för att markera/ändra innehållet?
  • Logiken ska hållas åtskild från användargränssnittets lager. HTML är utformat för att säkerställa att detta sker.
• Behöver komponenten CSS-formatering?
  • CSS-formateringen ska hållas åtskild från komponentdefinitionerna. Definiera konventioner för att namnge elementen i HTML så att du kan ändra dem via externa CSS-filer.
• Vilka säkerhetsåtgärder kan den nya komponenten ge upphov till?

Återanvända befintliga komponenter

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

Utöka kärnkomponenter

Core Components erbjuder också rensa anpassningsmönster som ni kan använda för att anpassa dem till era egna behov.

Ersätta komponenter

Komponenter kan också definieras om med en övertäckning baserat på sökvägslogiken. I sådana fall gäller dock att Samla resurser kommer inte att aktiveras och /apps måste definiera hela övertäckningen.

Utöka komponentdialogrutor

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

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 som det behövs, både i författarmiljön och i publiceringsmiljön.

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.

Denna filosofi stöds av HTL, ett mallspråk som är avsiktligt begränsat för att säkerställa att ett verkligt 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:

• Använda Java - HTL Java Use-API I kan en HTML-fil få åtkomst till hjälpmetoder i en anpassad Java-klass. På så sätt kan du använda Java-kod för att implementera logiken för att välja och konfigurera komponentinnehållet.
• Använda JavaScript - HTL JavaScript Use-API aktiverar en HTML-fil för att komma åt hjälpkod som skrivits i JavaScript. På så sätt kan du använda JavaScript-kod för att implementera logiken för att välja och konfigurera komponentinnehållet.
• Använda bibliotek på klientsidan - Moderna webbplatser är starkt beroende av bearbetning på klientsidan som styrs av komplex JavaScript- och CSS-kod. Se dokumentet Använda bibliotek på klientsidan på AEM as a Cloud Service för mer information.

Komponentstruktur

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

• Resurstyp
• Komponentdefinition
• Egenskaper och underordnade noder för en komponent
• Dialogrutor
• Designdialogrutor

Resurstyp

Ett nyckelelement i strukturen är resurstypen.

• Innehållsstrukturen deklarerar avsikter.
• Resurstypen implementerar dem.

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

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

• AEM baseras på Sling.
• AEM finns under /libs/core/wcm/components.
• Projekt-/platsspecifika komponenter finns under /apps/<myApp>/components.
• AEM standardkomponenter definieras som cq:Component och har de viktigaste elementen:
  • jcr Properties - En lista med jcr-egenskaper. Dessa är variabla och vissa kan vara valfria genom att grundstrukturen för en komponentnod, dess egenskaper och undernoder definieras av cq:Component definition.
  • Resurser - Dessa definierar statiska element som används av komponenten.
  • Skript - Dessa används för att implementera beteendet för den resulterande instansen av komponenten.

Viktiga egenskaper

• Rotnod:
  • <mycomponent> (cq:Component) - Komponentens hierarkiska nod.
• Viktiga egenskaper:
  • jcr:title - Komponenttitel; används till exempel som en etikett när komponenten finns med i Komponentbläddraren och Komponentkonsol
  • jcr:description - Beskrivning av komponenten. används som muspekningstips i komponentwebbläsaren och komponentkonsolen
  • Se avsnittet Komponentikon för mer information
• Vitala underordnade noder:
  • cq:editConfig (cq:EditConfig) - Definierar redigeringsegenskaperna för komponenten och aktiverar komponenten så att den visas i komponentwebbläsaren
    • Om komponenten har en dialogruta visas den automatiskt i komponentwebbläsaren eller i Sidekick, även om cq:editConfig inte finns.
  • cq:childEditConfig (cq:EditConfig) - Styr gränssnittsaspekter för författare för underordnade komponenter som inte definierar sina egna cq:editConfig.
  • cq:dialog (nt:unstructured) - Dialog för den här komponenten. Definierar gränssnittet som tillåter användaren att konfigurera komponenten och/eller redigera innehåll.
  • cq:design_dialog (nt:unstructured) - Designredigering för den här komponenten

Komponentikon

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.

1. cq:icon - String-egenskap som pekar på en standardikon i Coral UI-bibliotek som visas i komponentwebbläsaren
   • Använd värdet för HTML-attributet för ikonen Koral.
2. abbreviation - String-egenskap för att anpassa förkortningen av komponentnamnet i komponentwebbläsaren
   • Förkortningen ska vara begränsad till två tecken.
   • Om du anger en tom sträng byggs förkortningen av de två första tecknen i jcr:title -egenskap.
     • Exempel:"Im" för"Bild"
     • Den lokaliserade titeln används för att skapa förkortningen.
   • Förkortningen översätts bara om komponenten har en abbreviation_commentI18n -egenskapen, som sedan används som översättningstips.
3. cq:icon.png eller cq:icon.svg - Ikon för den här komponenten, som visas i komponentwebbläsaren
   • 20 x 20 pixlar är storleken på ikonerna för standardkomponenter.
     • Storleken på större ikoner kommer att minskas (klientsidan).
   • Den rekommenderade färgen är rgb(112, 112, 112) > #707070
   • Bakgrunden för standardkomponentikoner är genomskinlig.
   • Endast .png och .svg filer stöds.
   • Om du importerar från filsystemet via plugin-programmet Eclipse måste filnamnen escape-konverteras som _cq_icon.png eller _cq_icon.svg till exempel.
   • .png tar över sitt prejudikat .svg om båda finns.

Om ingen av ovanstående egenskaper (cq:icon, abbreviation, cq:icon.png eller cq:icon.svg) finns på komponenten:

• Systemet söker efter samma egenskaper i de överordnade komponenterna efter sling:resourceSuperType -egenskap.
• Om inget eller en tom förkortning hittas på den överordnade komponentnivån, kommer systemet att skapa förkortningen från de första bokstäverna i jcr:title den aktuella komponentens egenskap.

Om du vill avbryta arvet av ikoner från superkomponenter anger du ett tomt värde abbreviation -egenskapen för komponenten återställs till standardbeteendet.

The Komponentkonsol visar hur ikonen för en viss komponent definieras.

Exempel på SVG-ikon

<?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

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 vi tittar på Text kan vi se ett antal av dessa element:

Egenskaper av särskilt intresse är:

• jcr:title - Det här är titeln på komponenten som används för att identifiera komponenten i komponentwebbläsaren.
• jcr:description - Det här är beskrivningen för komponenten.
• sling:resourceSuperType - Detta anger arvets sökväg när en komponent utökas (genom att en definition åsidosätts).

Underordnade noder av särskilt intresse är:

• cq:editConfig - Detta styr visuella aspekter av komponenten vid redigering.
• cq:dialog - Här definieras dialogrutan för redigering av innehåll i den här komponenten.
• cq:design_dialog - Detta anger designredigeringsalternativen för den här komponenten.

Dialogrutor

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. Se redigeringsdokumentation om du vill ha mer information om hur innehållsförfattare interagerar med komponenter.

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

Dialogrutor för AEM:

• är cq:dialog noder av typen nt:unstructured.
• Finns under deras cq:Component noder och bredvid deras komponentdefinitioner.
• Definiera dialogrutan för att redigera innehåll i den här komponenten.
• Definieras med GRE-komponenter.
• Renderas på serversidan (som Sling-komponenter), baserat på deras innehållsstruktur och sling:resourceType -egenskap.
• Innehåller en nodstruktur som beskriver fälten i dialogrutan
  • Dessa noder är nt:unstructured med sling:resourceType -egenskap.

I dialogrutan definieras enskilda fält:

Designdialogrutor

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. Se malldokumentation om du vill ha mer information om hur mallar skapas.

Designdialogrutor används när du redigerar en sidmalltrots att de inte behövs för alla komponenter. Till exempel Titel och Bildkomponenter båda har designdialogrutor, medan Delningskomponent för sociala medier inte.

Gränssnittet för korall och GRENITE

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

• Coral UI ger ett konsekvent användargränssnitt för alla molnlösningar.
• Granite-gränssnitt innehåller Coral UI-kod inkapslad i Sling-komponenter för att skapa UI-konsoler och dialogrutor.

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:

• Struktur för AEM

Anpassa dialogrutefält

Om du vill skapa en ny widget som ska användas i en komponentdialogruta måste du skapa en ny GRI-fältkomponent.

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. Om du skapar ett nytt formulärfält måste du skapa en resurstyp; motsvarar att skapa en ny komponent. För att du ska få hjälp med den uppgiften erbjuder Granite 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 skapa en instans av fältet genom att lägga till en ny nod i dialogrutan med egenskapen sling:resourceType refererar till den resurstyp som du just har introducerat.

Åtkomst till dialogrutefält

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

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

Använda komponenter

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

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.

Se malldokumentation om du vill ha mer information om hur mallar skapas.

Komponenter och det innehåll de skapar

Om vi skapar och konfigurerar en instans av Titel 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:

• Innehållet innehåller en jcr:title -egenskapen som innehåller den faktiska texten i titeln som författaren angav.
• Den innehåller även en sling:resourceType -referens till komponentdefinitionen.

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

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

Se avsnittet Återanvända komponenter för mer information.

Redigera beteende

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.

En komponents redigeringsbeteende konfigureras genom att en cq:editConfig nod av typen cq:EditConfig nedanför komponentnoden (av typen cq:Component) och genom att lägga till specifika egenskaper och underordnade noder. Följande egenskaper och underordnade noder är tillgängliga:

• cq:editConfig nodegenskaper
• cq:editConfig underordnade noder:
  • cq:dropTargets (nodtyp nt:unstructured): definierar en lista med släppmål som kan acceptera en släppning från en resurs i innehållshanteraren (ett enskilt släppmål tillåts)
  • cq:inplaceEditing (nodtyp cq:InplaceEditingConfig): definierar en redigeringskonfiguration på plats för komponenten
  • cq:listeners (nodtyp cq:EditListenersConfig): definierar vad som händer före eller efter en åtgärd inträffar för komponenten

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

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 isEmpty är en variabel som bara är true när komponenten inte har något innehåll och som ä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 föregående exempel model.text är variabeln som är true bara när innehållet har innehåll och är synlig.

Ett exempel på hur den här mallen används finns i Core Components, som i komponenten Title.

Konfigurera med cq:EditConfig-underordnade noder

Släpp resurser i en dialogruta - cq:dropTargets

The cq:dropTargets nod (nodtyp) 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

Med en lokal redigerare kan användaren redigera innehåll direkt i innehållsflödet utan att behöva öppna någon dialogruta. Standardvärdet Text och Titel -komponenter har båda en redigerare på insidan.

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

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

Följande konfiguration aktiverar redigering på komponentens avstånd och definierar plaintext som redigeringstyp:

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

Hantera fälthändelser - cq:avlyssnare

Metoden för att hantera händelser i dialogrutefält görs med avlyssnare i en anpassad klientbibliotek.

För att lägga in logik i fältet bör du:

• Låt fältet vara markerat med en viss CSS-klass (kroken).
• I klientbiblioteket definierar du en JS-avlyssnare som är kopplad till det CSS-klassnamnet (detta garanterar att din anpassade logik endast omfattar fältet och inte påverkar andra fält av samma typ).

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

The cq:listeners nod (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. Till exempel project.customerAction är en statisk metod):

afteredit = "project.customerAction"

Följande exempel motsvarar REFRESH_INSERTED konfiguration:

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

Fältvalidering i GRÄNSSNITTET för Granite och GRÄNSSNITTET för Granite görs med foundation-validation API. Se foundation-valdiation Granite-dokumentation för mer information.

Dialogrutans tillgänglighet identifieras

Om du har ett anpassat JavaScript som bara behöver köras när dialogrutan är tillgänglig och klar bör du avlyssna dialog-ready -händelse.

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

The WCM-läge cookie 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 baseras på värdet för cookien.

Dokumentera komponenter

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

• Beskrivning
• Avsedd användning
• Innehållsstruktur och egenskaper
• Exponerade API:er och tilläggspunkter
• osv.

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 i komponentstrukturen.

Den här markeringen visas i dialogrutan Komponentkonsol.

Den kod som stöds är densamma som den som Innehållsfragment.

Resurser för Business.Adobe.com