Guida di riferimento dei componenti components-reference-guide

I componenti sono al centro della creazione di un’esperienza nell’AEM. Il Componenti core e Archetipo progetto AEM semplificate l'utilizzo di un set di strumenti con componenti robusti e pronti. Il Esercitazione WKND spiega allo sviluppatore come utilizzare questi strumenti e come creare componenti personalizzati per creare un sito AEM.

Poiché l’esercitazione WKND copre la maggior parte dei casi d’uso, questo documento è inteso solo come supplemento a tali risorse. Fornisce informazioni tecniche approfondite sulla struttura e la configurazione dei componenti in AEM e non intende essere una guida introduttiva.

Panoramica overview

Questa sezione descrive concetti e problemi chiave come introduzione ai dettagli necessari per lo sviluppo di componenti personalizzati.

Pianificazione planning

Prima di iniziare a configurare o codificare il componente, è necessario chiedere:

Riutilizzo dei componenti esistenti reusing-components

Prima di dedicare tempo alla creazione di un componente completamente nuovo, è consigliabile personalizzare o estendere i componenti esistenti. Componenti core offre una suite di componenti flessibili, robusti e testati pronti per la produzione.

Estensione dei Componenti core extending-core-components

I Componenti core offrono anche cancella modelli di personalizzazione che puoi utilizzare per adattarle alle esigenze del tuo progetto.

Sovrapposizione di componenti overlying-components

I componenti possono essere ridefiniti anche con sovrapposizione in base alla logica del percorso di ricerca. Tuttavia, in tal caso, Sling Resource Merger non verrà attivato e /apps deve definire l’intera sovrapposizione.

Estensione delle finestre di dialogo dei componenti extending-component-dialogs

È inoltre possibile modificare la finestra di dialogo di un componente utilizzando Sling Resource Merger e definendo la proprietà sling:resourceSuperType.

Ciò significa che è sufficiente ridefinire le differenze richieste, anziché ridefinire l’intera finestra di dialogo.

Logica dei contenuti e markup di rendering content-logic-and-rendering-markup

Viene eseguito il rendering del componente con HTML. Il componente deve definire il HTML necessario per acquisire il contenuto richiesto e quindi eseguirne il rendering come richiesto, sia nell’ambiente di authoring che in quello di pubblicazione.

Si consiglia di mantenere il codice responsabile del markup e del rendering separato dal codice che controlla la logica utilizzata per selezionare il contenuto del componente.

Questa filosofia è supportata da HTL: linguaggio per modelli appositamente limitato per garantire che venga utilizzato un linguaggio di programmazione reale per definire la logica di business sottostante. Questo meccanismo evidenzia il codice chiamato per una determinata vista e, se necessario, consente una logica specifica per diverse viste dello stesso componente.

Questa logica (facoltativa) può essere implementata in diversi modi e viene richiamata da HTL con comandi specifici:

Struttura dei componenti structure

La struttura di una componente AEM è potente e flessibile. Le parti principali sono:

Tipo risorsa resource-type

Un elemento chiave della struttura è il tipo di risorsa.

Si tratta di un’astrazione che aiuta a garantire che, anche quando l’aspetto cambia nel tempo, l’intenzione rimanga nel tempo.

Definizione componente component-definition

La definizione di un componente può essere suddivisa come segue:

Proprietà vitali vital-properties

Icona componente component-icon

L’icona o l’abbreviazione del componente viene definita tramite le proprietà JCR del componente quando questo viene creato dallo sviluppatore. Queste proprietà vengono valutate nell'ordine seguente e viene utilizzata la prima proprietà valida trovata.

Se nessuna delle proprietà precedenti (cq:icon, abbreviation, cq:icon.png o cq:icon.svg) si trovano nel componente:

Per annullare l’ereditarietà delle icone dai super componenti, imposta un valore vuoto abbreviation sul componente verrà ripristinato il comportamento predefinito.

Il Console Componenti mostra come viene definita l’icona di un particolare componente.

Esempio di icona SVG 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>

Proprietà e nodi figlio di un componente properties-and-child-nodes-of-a-component

Molti nodi/proprietà necessari per definire un componente sono comuni a entrambe le interfacce, con differenze che rimangono indipendenti in modo che il componente possa funzionare in entrambi gli ambienti.

Un componente è un nodo di tipo cq:Component e ha le seguenti proprietà e nodi secondari:

Osservando il Testo componente, puoi visualizzare diversi di questi elementi:

Le proprietà di particolare interesse comprendono:

I nodi figlio di particolare interesse includono:

Finestre di dialogo dialogs

Le finestre di dialogo sono un elemento chiave del componente in quanto forniscono un’interfaccia che consente agli autori di configurare il componente in una pagina di contenuto e fornire input per tale componente. Consulta la documentazione di authoring per informazioni dettagliate su come gli autori di contenuti interagiscono con i componenti.

A seconda della complessità del componente, la finestra di dialogo potrebbe richiedere una o più schede.

Finestre di dialogo per le componenti AEM:

Nella finestra di dialogo sono definiti i singoli campi:

Finestre di dialogo per progettazione design-dialogs

Le finestre di dialogo per progettazione sono simili alle finestre di dialogo utilizzate per modificare e configurare il contenuto, ma forniscono agli autori di modelli l’interfaccia per la pro-configurazione e i dettagli di progettazione per tale componente su un modello di pagina. I modelli di pagina vengono quindi utilizzati dagli autori dei contenuti per creare pagine di contenuto. Consulta la documentazione del modello per informazioni dettagliate sulla creazione dei modelli.

Le finestre di dialogo per progettazione vengono utilizzate quando si modifica un modello di pagina, anche se non sono necessari per tutti i componenti. Ad esempio, il Titolo e Componenti immagine entrambi dispongono di finestre di dialogo di progettazione, mentre Componente condivisione social media non lo fa.

Coral UI e Granite UI coral-and-granite

L’interfaccia utente Coral e Granite definiscono l’aspetto dell’AEM.

L’interfaccia utente Granite offre una vasta gamma di widget di base necessari per creare la finestra di dialogo nell’ambiente di authoring. Se necessario, puoi estendere questa selezione e creare un widget personalizzato.

Per ulteriori informazioni, consulta le seguenti risorse:

Personalizzazione dei campi della finestra di dialogo customizing-dialog-fields

Per creare un widget da utilizzare nella finestra di dialogo di un componente è necessario creare un componente campo dell’interfaccia utente Granite.

Se consideri la finestra di dialogo come un semplice contenitore per un elemento del modulo, puoi anche visualizzare il contenuto principale della finestra di dialogo come campi del modulo. La creazione di un nuovo campo modulo richiede la creazione di un tipo di risorsa, che equivale alla creazione di un componente. Per facilitare questa attività, l’interfaccia utente Granite offre un componente campo generico da cui ereditare (utilizzando sling:resourceSuperType):

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

Più precisamente, l’interfaccia utente Granite offre una serie di componenti di campo adatti all’utilizzo nelle finestre di dialogo o, più in generale, in moduli.

Dopo aver creato il tipo di risorsa, puoi creare un’istanza del campo aggiungendo un nuovo nodo nella finestra di dialogo, con la proprietà sling:resourceType facendo riferimento al tipo di risorsa appena introdotto.

Accesso ai campi della finestra di dialogo access-to-dialog-fields

È inoltre possibile utilizzare le condizioni di rendering (rendercondition) per controllare chi ha accesso a schede/campi specifici nella finestra di dialogo; ad esempio:

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

Utilizzo dei componenti using-components

Dopo aver creato un componente, devi abilitarlo per utilizzarlo. Il suo utilizzo mostra come la struttura del componente è correlata alla struttura del contenuto risultante nell’archivio.

Aggiunta del componente al modello adding-your-component-to-the-template

Una volta definito, il componente deve essere reso disponibile per l’uso. Per rendere un componente disponibile per l’utilizzo in un modello, devi abilitarlo nel criterio del Contenitore di layout del modello.

Consulta la documentazione del modello per informazioni dettagliate sulla creazione dei modelli.

Componenti e contenuti creati components-and-the-content-they-create

Se creiamo e configuriamo un’istanza di Titolo componente nella pagina: /content/wknd/language-masters/en/adventures/extreme-ironing.html

Quindi possiamo vedere la struttura del contenuto creato all’interno dell’archivio:

In particolare, se si considera il testo effettivo di un Componente Titolo:

Le proprietà definite dipendono dalle singole definizioni. Anche se possono essere più complesse di quanto sopra, seguono comunque gli stessi principi di base.

Gerarchia dei componenti ed ereditarietà component-hierarchy-and-inheritance

I componenti dell’AEM sono soggetti agli Gerarchia dei tipi di risorsa. Viene utilizzato per estendere i componenti utilizzando la proprietà sling:resourceSuperType. Questo consente al componente di ereditare da un altro componente.

Consulta la sezione Riutilizzo dei componenti per ulteriori informazioni.

Modifica comportamento edit-behavior

Questa sezione spiega come configurare il comportamento di modifica di un componente. Ciò include attributi quali le azioni disponibili per il componente, le caratteristiche dell’editor in.place e i listener relativi agli eventi sul componente.

Il comportamento di modifica di un componente viene configurato aggiungendo un cq:editConfig nodo di tipo cq:EditConfig sotto il nodo del componente (di tipo cq:Component) e aggiungendo proprietà e nodi secondari specifici. Sono disponibili le seguenti proprietà e nodi figlio:

Ci sono molte configurazioni esistenti nell'AEM. Puoi cercare facilmente proprietà specifiche o nodi secondari utilizzando lo strumento Query in CRXDE Liti.

Segnaposto Componente component-placeholders

I componenti devono sempre eseguire il rendering di alcuni HTML visibili all’autore, anche quando il componente non ha contenuto. In caso contrario, potrebbe scomparire visivamente dall’interfaccia dell’editor, rendendolo tecnicamente presente ma invisibile nella pagina e nell’editor. In questo caso, gli autori non potranno selezionare e interagire con il componente vuoto.

Per questo motivo, i componenti devono eseguire il rendering di un segnaposto, a condizione che non eseguano il rendering di alcun output visibile quando si esegue il rendering della pagina nell’editor di pagine (quando la modalità WCM è edit o preview).
Il markup HTML tipico per un segnaposto è il seguente:

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

HTML Il tipico script HTL che esegue il rendering del segnaposto sopra riportato è il seguente:

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

Nell’esempio precedente, isEmpty è una variabile che è true solo quando il componente non ha contenuto ed è invisibile all’autore.

Per evitare ripetizioni, l’Adobe consiglia agli implementatori di componenti di utilizzare un modello HTL per questi segnaposto, come quello fornito dai Componenti core.

L’utilizzo del modello nel collegamento precedente viene quindi eseguito con la seguente riga di HTL:

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

Nell’esempio precedente, model.text è la variabile che è true solo quando il contenuto ha contenuto ed è visibile.

Un esempio di utilizzo di questo modello è disponibile nei Componenti core, come nel componente Titolo.

Configurazione con i nodi secondari cq:EditConfig configuring-with-cq-editconfig-child-nodes

Eliminazione di risorse in una finestra di dialogo - cq:dropTargets cq-droptargets

Il cq:dropTargets nodo (tipo di nodo) nt:unstructured) definisce la destinazione di rilascio in grado di accettare un rilascio da una risorsa trascinata da content finder. È un nodo di tipo cq:DropTargetConfig.

Nodo figlio di tipo cq:DropTargetConfig definisce una destinazione di rilascio nel componente.

Modifica diretta - cq:inplaceEditing cq-inplaceediting

Un editor locale consente all’utente di modificare il contenuto direttamente nel flusso di contenuto, senza dover aprire una finestra di dialogo. Ad esempio, lo standard Testo e Titolo entrambi i componenti dispongono di un editor locale.

Non è necessario/significativo un editor locale per ogni tipo di componente.

Il cq:inplaceEditing nodo (tipo di nodo) cq:InplaceEditingConfig) definisce una configurazione di modifica diretta per il componente. Può avere le seguenti proprietà:

La seguente configurazione abilita la modifica diretta del componente e definisce plaintext come tipo di editor:

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

Gestione degli eventi dei campi - cq:listeners cq-listeners

Il metodo di gestione degli eventi sui campi della finestra di dialogo viene eseguito con i listener in un libreria client.

Per inserire la logica nel campo, è necessario:

A questo scopo, è necessario conoscere la libreria di widget sottostante con cui desideri interagire. Consulta la documentazione sull’interfaccia utente Coral per identificare a quale evento desideri reagire.

Il cq:listeners nodo (tipo di nodo) cq:EditListenersConfig) definisce cosa accade prima o dopo un’azione sul componente. La tabella seguente definisce le proprietà possibili.

Il gestore eventi può essere implementato con un’implementazione personalizzata. Ad esempio, (dove project.customerAction è un metodo statico):

afteredit = "project.customerAction"

L’esempio seguente è equivalente al REFRESH_INSERTED configurazione:

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

Con la seguente configurazione la pagina viene aggiornata dopo che il componente è stato eliminato, modificato, inserito o spostato:

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

Convalida campo field-validation

La convalida dei campi nell’interfaccia utente Granite e nei widget dell’interfaccia utente Granite viene eseguita utilizzando foundation-validation API. Consulta la foundation-valdiation Documentazione di Granite per i dettagli.

Rilevamento della disponibilità della finestra di dialogo dialog-ready

Se disponi di un JavaScript personalizzato che deve essere eseguito solo quando la finestra di dialogo è disponibile e pronta, è necessario ascoltare dialog-ready evento.

Questo evento viene attivato ogni volta che la finestra di dialogo viene caricata (o ricaricata) ed è pronta per l’uso, ovvero ogni volta che si verifica una modifica (creazione/aggiornamento) nel DOM della finestra di dialogo.

dialog-ready può essere utilizzato per hook nel codice personalizzato JavaScript che esegue personalizzazioni sui campi all’interno di una finestra di dialogo o attività simili.

Anteprima comportamento preview-behavior

Il Modalità WCM Il cookie viene impostato quando si passa alla modalità Anteprima anche quando la pagina non viene aggiornata.

Per i componenti con un rendering sensibili alla modalità WCM, è necessario definirli per aggiornarsi in modo specifico e quindi basarsi sul valore del cookie.

Documentazione dei componenti documenting-components

In qualità di sviluppatore, desideri poter accedere facilmente alla documentazione dei componenti per comprendere rapidamente i relativi:

Per questo motivo, è molto semplice creare qualsiasi markdown della documentazione esistente disponibile all’interno del componente stesso.

È sufficiente inserire un README.md nella struttura dei componenti.

Questo markdown verrà quindi visualizzato nel Console Componenti.

Il markdown supportato è lo stesso di Frammenti di contenuto.