Referentiehandleiding voor componenten components-reference-guide

Componenten vormen de kern van het opbouwen van een ervaring in AEM. De Componenten van de Kernen AEM Archetype van het Projectmaken het eenvoudig om met een hulpmiddelreeks kant-en-klare, robuuste componenten te beginnen. Het WKND Leerprogrammaneemt de ontwikkelaar door hoe te om deze hulpmiddelen te gebruiken en hoe te om douanecomponenten te bouwen om een AEM plaats tot stand te brengen.

Omdat de WKND-zelfstudie betrekking heeft op de meeste gevallen van gebruik, is dit document alleen bedoeld als aanvulling op deze bronnen. Het geeft diepgaande technische details over hoe de componenten in AEM gestructureerd en gevormd zijn en niet bedoeld als begonnen gids worden.

Overzicht overview

In deze sectie worden de belangrijkste concepten en kwesties behandeld als een inleiding op de details die nodig zijn voor het ontwikkelen van uw eigen componenten.

Planning planning

Voordat u begint met het configureren of coderen van uw component, moet u het volgende vragen:

Bestaande componenten opnieuw gebruiken reusing-components

Voordat u tijd investeert in het maken van een geheel nieuwe component, kunt u het aanpassen of uitbreiden van bestaande componenten overwegen. de Componenten van de Kernbieden een reeks van flexibele, robuuste, en goed-geteste productie-klaar componenten aan.

Uitbreiding van kerncomponenten extending-core-components

De Componenten van de Kern bieden ook duidelijke aanpassingspatronenaan die u kunt gebruiken om hen aan de behoeften van uw eigen project aan te passen.

Onderdelen bedekken overlying-components

De componenten kunnen ook met een bekledingworden opnieuw bepaald die op de logica van de onderzoekspad wordt gebaseerd. Nochtans in zulk geval, zal de Verschuivende Fusie van het Middelniet teweeggebracht worden en /apps moet de volledige bekleding bepalen.

Componentdialoogvensters uitbreiden extending-component-dialogs

Het is ook mogelijk om een componentendialoog met voeten te treden gebruikend de Verschuivende Fusie van het Middel en het bepalen van het bezit sling:resourceSuperType.

Dit betekent dat u alleen de vereiste verschillen opnieuw hoeft te definiëren in plaats van het volledige dialoogvenster opnieuw te definiëren.

Opmaak voor Content Logic en rendering content-logic-and-rendering-markup

Uw component wordt teruggegeven met HTML. Uw component moet de HTML definiëren die nodig is om de vereiste inhoud te nemen en deze vervolgens naar wens weer te geven, zowel in de auteur- als in de publicatieomgeving.

Het wordt aanbevolen de code die verantwoordelijk is voor opmaak en rendering, gescheiden te houden van de code die de logica regelt die wordt gebruikt om de inhoud van de component te selecteren.

Deze filosofie wordt gesteund door HTML, een het malplaatjetaal die opzettelijk wordt beperkt om een echte programmeertaal te verzekeren wordt gebruikt om de onderliggende bedrijfslogica te bepalen. Dit mechanisme benadrukt de code die voor een bepaalde mening wordt geroepen en, indien nodig, staat specifieke logica voor verschillende meningen van de zelfde component toe.

Deze (facultatieve) logica kan op verschillende manieren worden uitgevoerd en wordt aangehaald van HTML met specifieke bevelen:

Componentstructuur structure

De structuur van een AEM is krachtig en flexibel. De belangrijkste onderdelen zijn:

Resourcetype resource-type

Een zeer belangrijk element van de structuur is het middeltype.

Dit is een abstractie die helpt ervoor te zorgen dat zelfs wanneer de blik en het gevoel in tijd verandert, dat de intentie de tijd blijft.

Componentdefinitie component-definition

De definitie van een component kan als volgt worden uitgesplitst:

Vitale eigenschappen vital-properties

Pictogram Component component-icon

Het pictogram of de afkorting voor de component wordt gedefinieerd via JCR-eigenschappen van de component wanneer de component door de ontwikkelaar wordt gemaakt. Deze eigenschappen worden in de volgende volgorde geëvalueerd en de eerste geldige gevonden eigenschap wordt gebruikt.

Als geen van de bovenstaande eigenschappen (cq:icon, abbreviation, cq:icon.png of cq:icon.svg) worden gevonden in de component:

Als u de overerving van pictogrammen van supercomponenten wilt annuleren, wordt de standaardwerking hersteld wanneer u een lege eigenschap abbreviation voor de component instelt.

De Console van de Componenttoont hoe het pictogram voor een bepaalde component wordt bepaald.

Voorbeeld van SVG-pictogram 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>

Eigenschappen en onderliggende knooppunten van een component properties-and-child-nodes-of-a-component

Veel van de knopen/eigenschappen nodig om een component te bepalen zijn gemeenschappelijk voor beide UIs, met verschillen die onafhankelijk blijven zodat uw component in beide milieu's kan werken.

Een component is een knooppunt van het type cq:Component en heeft de volgende eigenschappen en onderliggende knooppunten:

Als u de component van de Tekst bekijkt, kunt u verscheidene van deze elementen zien:

Tot de eigenschappen van bijzonder belang behoren:

Onderliggende knooppunten die van bijzonder belang zijn, zijn onder meer:

Dialoogvensters dialogs

Dialoogvensters zijn een belangrijk element van uw component omdat ze een interface bieden waarmee auteurs de component op een inhoudspagina kunnen configureren en invoer voor die component kunnen leveren. Zie auteursdocumentatievoor details op hoe de inhoudsauteurs met componenten in wisselwerking staan.

Afhankelijk van de complexiteit van de component heeft uw dialoogvenster mogelijk een of meer tabbladen nodig.

Dialoogvensters voor AEM componenten:

In het dialoogvenster worden de afzonderlijke velden gedefinieerd:

Ontwerpdialoogvensters design-dialogs

De dialoogvensters van het ontwerp zijn gelijkaardig aan de dialogen die worden gebruikt om inhoud uit te geven en te vormen, maar zij verstrekken de interface voor malplaatjeauteurs om ontwerpdetails voor die component op een paginasjabloon pro-vormen en te verstrekken. Paginasjablonen worden vervolgens door de auteurs van de inhoud gebruikt om inhoudspagina's te maken. Zie de malplaatjedocumentatievoor details op hoe de malplaatjes worden gecreeerd.

de dialogen van het Ontwerp worden gebruikt wanneer het uitgeven van een paginamalplaatje, hoewel zij niet nodig voor alle componenten zijn. Bijvoorbeeld, hebben de Titel en Componenten van het Beeld allebei ontwerpdialogen, terwijl de Sociale Media die Component delen niet.

Gebruikersinterface voor koralen en graniet coral-and-granite

De interface van koralen en de interface van Granite bepalen het uiterlijk van AEM.

De graniet-interface biedt een groot aantal basiswidgets die nodig zijn om uw dialoogvenster in de ontwerpomgeving te maken. Indien nodig kunt u deze selectie uitbreiden en uw eigen widget maken.

Zie de volgende bronnen voor meer informatie:

Dialoogvenstervelden aanpassen customizing-dialog-fields

Als u een widget wilt maken voor gebruik in een componentdialoogvenster, moet u een graniet UI-veldcomponent maken.

Als u het dialoogvenster beschouwt als een eenvoudige container voor een formulierelement, kunt u ook de primaire inhoud van het dialoogvenster zien als formuliervelden. Voor het maken van een nieuw formulierveld moet u een brontype maken. Dit is hetzelfde als het maken van een component. Om u in die taak te helpen, biedt granite UI een generische gebiedscomponent aan om van (het gebruiken van sling:resourceSuperType) te erven:

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

Specifieker verleent UI een waaier van gebiedscomponenten die voor gebruik in dialogen geschikt zijn, of meer in het algemeen sprekend in vormen.

Zodra u uw middeltype hebt gecreeerd, kunt u uw gebied concretiseren door een nieuw knooppunt in uw dialoog toe te voegen, met het bezit sling:resourceType dat naar het middeltype verwijst u net hebt geïntroduceerd.

Toegang tot dialoogvelden access-to-dialog-fields

U kunt ook rendervoorwaarden (rendercondition) gebruiken om te bepalen wie toegang heeft tot specifieke tabbladen/velden in uw dialoogvenster, bijvoorbeeld:

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

Componenten gebruiken using-components

Nadat u een component hebt gecreeerd, moet u het toelaten om het te gebruiken. Het gebruiken van het toont hoe de structuur van de component op de structuur van de resulterende inhoud in de bewaarplaats betrekking heeft.

De component toevoegen aan de sjabloon adding-your-component-to-the-template

Nadat een component is gedefinieerd, moet deze beschikbaar worden gesteld voor gebruik. Als u een component beschikbaar wilt maken voor gebruik in een sjabloon, moet u de component inschakelen in het beleid van de lay-outcontainer van de sjabloon.

Zie de malplaatjedocumentatievoor details op hoe de malplaatjes worden gecreeerd.

Componenten en de inhoud die ze maken components-and-the-content-they-create

Als wij tot een geval van de component van de Titel op de pagina leiden en vormen: /content/wknd/language-masters/en/adventures/extreme-ironing.html

Dan kunnen wij de structuur zien van de inhoud die binnen de bewaarplaats wordt gecreeerd:

Met name, als u de daadwerkelijke tekst van de Component van de Titel van a bekijkt:

De gedefinieerde eigenschappen zijn afhankelijk van de afzonderlijke definities. Hoewel ze complexer kunnen zijn dan boven ze liggen, volgen ze nog steeds dezelfde basisbeginselen.

Componenthiërarchie en Overerving component-hierarchy-and-inheritance

De componenten binnen AEM zijn onderworpen aan de Hiërarchie van het Type van Middel. Dit wordt gebruikt om componenten uit te breiden gebruikend het bezit sling:resourceSuperType. Hierdoor kan de component overerven van een andere component.

Zie de sectie het Hergebruiken Componentenvoor meer informatie.

Gedrag bewerken edit-behavior

In deze sectie wordt uitgelegd hoe u het bewerkingsgedrag van een component kunt configureren. Dit omvat kenmerken zoals acties beschikbaar voor de component, kenmerken van de in.place redacteur, en de luisteraars met betrekking tot gebeurtenissen op de component.

Het bewerkgedrag van een component wordt geconfigureerd door het toevoegen van een cq:editConfig knooppunt van het type cq:EditConfig onder het componentknooppunt (van het type cq:Component ) en door het toevoegen van specifieke eigenschappen en onderliggende knooppunten. De volgende eigenschappen en onderliggende knooppunten zijn beschikbaar:

Er zijn vele bestaande configuraties in AEM. U kunt gemakkelijk naar specifieke eigenschappen of kindknopen zoeken gebruikend het hulpmiddel van de Vraag in CRXDE Lite.

Plaatsaanduidingen voor onderdelen component-placeholders

Componenten moeten altijd HTML renderen die zichtbaar is voor de auteur, zelfs als de component geen inhoud heeft. Anders zou het van de interface van de redacteur visueel kunnen verdwijnen, die het technisch aanwezig maar onzichtbaar maken op de pagina en in de redacteur. In een dergelijk geval zullen de auteurs de lege component niet kunnen selecteren en ermee werken.

Om deze reden, zouden de componenten placeholder moeten teruggeven zolang zij geen zichtbare output teruggeven wanneer de pagina in de paginaredacteur wordt teruggegeven (wanneer de wijze WCM edit of preview is).
De gebruikelijke HTML-markering voor een tijdelijke aanduiding is:

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

Het standaard HTML-script dat de bovenstaande tijdelijke aanduiding HTML rendert, is:

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

In het vorige voorbeeld is isEmpty een variabele die alleen waar is wanneer de component geen inhoud heeft en onzichtbaar is voor de auteur.

Om herhaling te vermijden, adviseert de Adobe dat de uitvoerders van componenten een malplaatje HTML voor deze placeholders gebruiken, als verstrekt door de Componenten van de Kern.

Het gebruik van het malplaatje in de vorige verbinding wordt dan gedaan met de volgende lijn van HTML:

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

In het vorige voorbeeld is model.text de variabele die alleen waar is wanneer de inhoud inhoud bevat en zichtbaar is.

Een voorbeeldgebruik van dit malplaatje kan in de Componenten van de Kern, zoals in de Component van de Titel worden gezien.

Configureren met cq:Onderliggende knooppunten EditConfig configuring-with-cq-editconfig-child-nodes

Assets neerzetten in een dialoogvenster - cq:dropTargets cq-droptargets

Het knooppunt cq:dropTargets (knooppunttype nt:unstructured ) definieert het doel voor neerzetten dat een neerzetbewerking kan accepteren vanuit een element dat vanuit de inhoudzoeker wordt gesleept. Het is een knooppunt van het type cq:DropTargetConfig .

Het onderliggende knooppunt van het type cq:DropTargetConfig definieert een neerzetdoel in de component.

Op plaats bewerken - cq:inplaceEditing cq-inplaceediting

Met een interne editor kan de gebruiker inhoud rechtstreeks in de inhoudsstroom bewerken, zonder dat een dialoogvenster hoeft te worden geopend. Bijvoorbeeld, hebben de standaard Tekst en Titel componenten allebei een op zijn plaats redacteur.

Een interne editor is niet nodig/zinvol voor elk componenttype.

Het knooppunt cq:inplaceEditing (knooppunttype cq:InplaceEditingConfig ) definieert een configuratie voor bewerken op locatie voor de component. Deze kan de volgende eigenschappen hebben:

In de volgende configuratie wordt het op locatie bewerken van de component ingeschakeld en wordt plaintext gedefinieerd als het editortype:

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

Veldgebeurtenissen verwerken - cq:listeners cq-listeners

De methode om gebeurtenissen op dialooggebieden te behandelen wordt gedaan met luisteraars in een douane cliëntbibliotheek.

Om logica in uw gebied te injecteren, zou u moeten:

Hiervoor moet u weten welke onderliggende widgetbibliotheek u wilt gebruiken. zie de documentatie van Coral UIom te identificeren aan welke gebeurtenis u wilt reageren.

Het knooppunt cq:listeners (knooppunttype cq:EditListenersConfig ) definieert wat er gebeurt voor of na een handeling op de component. In de volgende tabel worden de mogelijke eigenschappen gedefinieerd.

De gebeurtenishandler kan worden geïmplementeerd met een aangepaste implementatie. Bijvoorbeeld (waarbij project.customerAction een statische methode is):

afteredit = "project.customerAction"

Het volgende voorbeeld is gelijk aan de configuratie REFRESH_INSERTED :

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

Met de volgende configuratie wordt de pagina vernieuwd nadat de component is verwijderd, bewerkt, ingevoegd of verplaatst:

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

Veldvalidatie field-validation

Veldvalidatie in de gebruikersinterface van Granite en de widgets van de gebruikersinterface van Granite wordt uitgevoerd met de API van foundation-validation . Zie de foundation-valdiation documentatie van Granitevoor meer informatie.

Beschikbaarheid van dialoogvenster vaststellen dialog-ready

Als u een aangepaste JavaScript hebt die alleen moet worden uitgevoerd wanneer het dialoogvenster beschikbaar en gereed is, moet u luisteren naar de gebeurtenis dialog-ready .

Deze gebeurtenis wordt geactiveerd wanneer het dialoogvenster wordt geladen (of opnieuw wordt geladen) en klaar voor gebruik is. Dit houdt in dat telkens wanneer er een wijziging (maken/bijwerken) plaatsvindt in de DOM van het dialoogvenster.

dialog-ready kan worden gebruikt om in aangepaste JavaScript-code die aanpassingen uitvoert op de velden in een dialoogvenster of vergelijkbare taken, aan elkaar te koppelen.

Werking voorvertoning preview-behavior

Het 🔗 koekje van de Wijze WCM wordt geplaatst wanneer het schakelen naar de wijze van de Voorproef zelfs wanneer de pagina niet wordt verfrist.

Voor componenten met een teruggeven die voor de Wijze van WCM gevoelig zijn, moeten zij worden bepaald om zich specifiek te verfrissen, dan zich op de waarde van het koekje baseren.

Componenten documenteren documenting-components

Als ontwikkelaar wilt u eenvoudige toegang tot componentendocumentatie zodat u de component snel kunt begrijpen:

Daarom is het vrij gemakkelijk om het even welke bestaande documentatiemarkering te maken u binnen de component zelf beschikbaar hebt.

U hoeft alleen een README.md -bestand in de componentstructuur te plaatsen.

Deze prijsdaling zal dan in de Console van de Componentworden getoond.

De gesteunde prijsdaling is het zelfde als dat voor Fragmenten van de Inhoud.