AEM componenti sono utilizzati per conservare, formattare ed eseguire il rendering del contenuto reso disponibile sulle pagine Web.
In pagine di authoring, i componenti consentono agli autori di modificare e configurare il contenuto.
Quando si crea un sito Commerce, i componenti possono, ad esempio, raccogliere ed eseguire il rendering delle informazioni dal catalogo.
Per ulteriori informazioni, vedere Sviluppo di eCommerce.
Quando si crea un sito Communities, i componenti possono fornire informazioni e raccogliere informazioni dai visitatori.
Per ulteriori informazioni, vedere Sviluppo di community.
Nell’istanza di pubblicazione i componenti eseguono il rendering del contenuto, presentandolo come necessario ai visitatori del sito Web.
Questa pagina è una continuazione del documento Componenti AEM - The Basics.
I componenti sotto /libs/cq/gui/components/authoring/dialog
sono utilizzabili solo nell’editor (finestre di dialogo dei componenti in Authoring). Se vengono utilizzati altrove (ad esempio in una finestra di dialogo della procedura guidata), potrebbero non funzionare come previsto.
Questa pagina contiene la documentazione di riferimento (o i collegamenti alla documentazione di riferimento) necessaria per sviluppare nuovi componenti per AEM. Per alcuni esempi pratici, vedere Sviluppo di componenti AEM - Esempi di codice.
La struttura di base di un componente è riportata nella pagina AEM Componenti - The Basics. Questo documento copre sia l’interfaccia touch che quella classica. Anche se non è necessario utilizzare le impostazioni classiche nel nuovo componente, può essere utile conoscerle quando si eredita da componenti esistenti.
A seconda del componente che si desidera implementare, potrebbe essere possibile estendere o personalizzare un'istanza esistente, anziché definire e sviluppare da zero l'intera struttura.
Durante l’estensione o la personalizzazione di un componente o di una finestra di dialogo esistente, potete copiare o replicare l’intera struttura o la struttura necessaria per la finestra di dialogo prima di apportare le modifiche.
Per estendere un componente esistente è possibile utilizzare Gerarchia dei tipi di risorse e i relativi meccanismi di ereditarietà.
I componenti possono essere ridefiniti con una sovrapposizione basata sulla logica del percorso di ricerca. In questo caso, tuttavia, la fusione risorse Sling non verrà attivata e /apps
deve definire l'intera sovrapposizione.
Anche il componente frammento di contenuto può essere personalizzato ed esteso, anche se è necessario considerare la struttura e le relazioni complete con le risorse.
È inoltre possibile ignorare una finestra di dialogo componente utilizzando la Sling Resource Merger e definendo la proprietà sling:resourceSuperType
.
Ciò significa che è sufficiente ridefinire le differenze richieste, anziché ridefinire l'intera finestra di dialogo (utilizzando sling:resourceSuperType
). Metodo consigliato per l’estensione della finestra di dialogo di un componente
Per ulteriori informazioni, vedere Sling Resource Merger.
Il componente verrà rappresentato con HTML. Il componente deve definire l’HTML necessario per acquisire il contenuto richiesto e eseguirne il rendering come necessario, sia nell’ambiente di creazione che nell’ambiente di pubblicazione.
Il HTML Template Language (HTL), introdotto con AEM 6.0, sostituisce JSP (JavaServer Pages) come sistema di modelli lato server preferito e consigliato per HTML. Per gli sviluppatori Web che hanno bisogno di creare siti Web aziendali affidabili, HTL contribuisce a migliorare la sicurezza e l’efficienza dello sviluppo.
Sebbene sia HTL che JSP possano essere utilizzati per lo sviluppo di componenti, in questa pagina verrà illustrato lo sviluppo con HTL, in quanto è il linguaggio di script consigliato per AEM.
Questa logica facoltativa seleziona e/o calcola il contenuto di cui eseguire il rendering. Viene richiamato dalle espressioni HTL con il pattern Use-API appropriato.
Il meccanismo per separare la logica dall'aspetto aiuta a chiarire ciò che viene richiesto per una determinata vista. Consente inoltre logiche diverse per diverse viste della stessa risorsa.
L'API Use-API Java HTL consente a un file HTL di accedere ai metodi helper in una classe Java personalizzata. Questo consente di utilizzare il codice Java per implementare la logica di selezione e configurazione del contenuto del componente.
L'API Use-API JavaScript HTL consente a un file HTL di accedere al codice helper scritto in JavaScript. Questo consente di utilizzare il codice JavaScript per implementare la logica necessaria per selezionare e configurare il contenuto del componente.
I siti Web moderni si affidano in larga misura all'elaborazione sul lato client basata su codice JavaScript e CSS complessi. L'organizzazione e l'ottimizzazione della gestione di questo codice può essere un problema complicato.
Per risolvere il problema, AEM fornisce Cartelle libreria lato client che consentono di memorizzare il codice lato client nell'archivio, organizzarlo in categorie e definire quando e come ciascuna categoria di codice deve essere distribuita al client. Il sistema di libreria lato client si occupa quindi di generare i collegamenti corretti nella pagina Web finale per caricare il codice corretto.
Leggi Utilizzo di librerie HTML lato client per ulteriori informazioni.
È possibile configurare il comportamento di modifica di un componente con attributi quali le azioni disponibili per il componente, le caratteristiche dell’editor locale e i listener relativi agli eventi sul componente. La configurazione è comune sia all’interfaccia touch che all’interfaccia classica, anche se con alcune specifiche differenze.
Il comportamento di modifica di un componente è configurato aggiungendo un nodo cq:editConfig
di tipo cq:EditConfig
sotto il nodo del componente (di tipo cq:Component
) e aggiungendo proprietà e nodi secondari specifici.
Il cookie WCM Mode viene impostato quando si passa alla modalità Anteprima anche quando la pagina non viene aggiornata.
Per i componenti con un rendering sensibile alla modalità WCM, è necessario definirli per aggiornarsi in modo specifico, quindi basarsi sul valore del cookie.
Nell'interfaccia touch sono utilizzati solo i valori EDIT
e PREVIEW
per il cookie WCM Mode.
Le finestre di dialogo consentono all’autore di interagire con il componente. Utilizzando una finestra di dialogo gli autori e/o gli amministratori possono modificare il contenuto, configurare il componente o definire i parametri di progettazione (mediante una finestra di dialogo Progettazione)
L’ interfaccia utente Coral e l’ interfaccia utente Granite definiscono l’aspetto e il comportamento moderni delle AEM.
L’interfaccia utente Granite offre una vasta gamma di componenti di base (widget) necessari per creare una finestra di dialogo nell’ambiente di authoring. Se necessario potete estendere questa selezione e creare un widget personalizzato.
Per ulteriori informazioni sullo sviluppo di componenti con tipi di risorse Corallo e Granite, vedi: Creazione di componenti Experience Manager utilizzando i tipi di risorse Corallo/Granite.
Per maggiori dettagli, consulta:
Interfaccia utente Coral
Interfaccia Granite
A causa della natura dei componenti dell’interfaccia Granite (e delle differenze con i widget ExtJS), esistono delle differenze tra il modo in cui i componenti interagiscono con l’interfaccia touch e l’ interfaccia classica.
Finestre di dialogo per l’interfaccia touch:
sono denominati cq:dialog
.
sono definiti come un nodo nt:unstructured
con la proprietà sling:resourceType
impostata.
si trovano sotto il nodo cq:Component
e accanto alla definizione del componente.
viene eseguito il rendering sul lato server (come componenti Sling), in base alla struttura del contenuto e alla proprietà sling:resourceType
.
utilizzate il framework di interfaccia utente Granite.
contiene una struttura di nodi che descrive i campi all’interno della finestra di dialogo.
nt:unstructured
con la proprietà sling:resourceType
richiesta.Esempio di struttura del nodo:
newComponent (cq:Component)
cq:dialog (nt:unstructured)
content
layout
items
column
items
file
description
La personalizzazione di una finestra di dialogo è simile allo sviluppo di un componente, in quanto la finestra di dialogo è di per sé un componente (ad es. markup rappresentato da uno script di componente insieme al comportamento/stile fornito da una libreria client).
Per esempi, vedete:
/libs/foundation/components/text/cq:dialog
/libs/foundation/components/download/cq:dialog
Se per un componente non è definita alcuna finestra di dialogo per l’interfaccia touch, la finestra di dialogo dell’interfaccia classica viene utilizzata come fallback all’interno di un livello di compatibilità. Per personalizzare tale finestra di dialogo è necessario personalizzare la finestra di dialogo dell’interfaccia classica. Consultate AEM Componenti per l'interfaccia classica.
Consulta:
I widget per l’interfaccia touch sono implementati come componenti dell’interfaccia Granite.
Per creare un nuovo widget da usare in una finestra di dialogo di componenti per l’interfaccia touch, è necessario creare un nuovo componente Campo interfaccia Granite.
Per informazioni dettagliate sull'interfaccia utente Granite, consultate la documentazione Granite UI.
Se si considera la finestra di dialogo come un semplice contenitore per un elemento modulo, è anche possibile visualizzare il contenuto principale del contenuto della finestra di dialogo come campi modulo. La creazione di un nuovo campo modulo richiede la creazione di un tipo di risorsa; equivale a creare un nuovo componente. Per facilitare l'esecuzione di tale 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 per i campi che possono essere utilizzati nelle finestre di dialogo (o, più in generale, nei moduli).
Ciò è diverso dall'interfaccia classica, dove i widget sono rappresentati da cq:Widgets
nodi, ciascuno con un xtype
particolare per stabilire la relazione con il widget ExtJS corrispondente. Dal punto di vista dell’implementazione, questi widget sono stati sottoposti a rendering sul lato client dal framework ExtJS.
Dopo aver creato il tipo di risorsa, è possibile creare un'istanza del campo aggiungendo un nuovo nodo nella finestra di dialogo, con la proprietà sling:resourceType
che fa riferimento al tipo di risorsa appena introdotto.
Se desiderate definire lo stile e il comportamento del componente, potete creare una libreria client dedicata che definisca CSS/LESS e JS personalizzati.
Per fare in modo che la libreria client venga caricata solo per la finestra di dialogo del componente (ovvero non verrà caricata per un altro componente), è necessario impostare la proprietà extraClientlibs
della finestra di dialogo sul nome della categoria della libreria client appena creata. Questo è consigliabile se la libreria client è abbastanza grande e/o se il campo è specifico per tale finestra di dialogo e non sarà necessario in altre finestre di dialogo.
Per fare in modo che la libreria client venga caricata per tutte le finestre di dialogo, impostate la proprietà category della libreria client su cq.authoring.dialog
. Questo è il nome della categoria della libreria client che è inclusa per impostazione predefinita quando si esegue il rendering di tutte le finestre di dialogo. Se la libreria client è piccola e/o il campo è generico e può essere riutilizzato in altre finestre di dialogo,
Ad esempio, vedete:
cqgems/customizingfield/components/colorpicker/clientlibs
A seconda delle esigenze, potete:
sling:resourceSuperType
)Potete anche 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"]
Il metodo di gestione degli eventi nei campi di dialogo ora viene eseguito con listener in una libreria client personalizzata. Si tratta di una modifica rispetto al metodo precedente, che consiste nell'avere listener nella struttura del contenuto.
Per inserire la logica nel campo, è necessario:
Per ottenere questo risultato è necessario conoscere la libreria di widget sottostante con cui si desidera interagire. Consultate la documentazione Coral UI per identificare l'evento a cui desiderate reagire. Questa procedura è molto simile a quella che era necessario eseguire con ExtJS in passato: trova la pagina della documentazione di un determinato widget, quindi controlla i dettagli della relativa API evento.
Ad esempio, vedete:
cqgems/customizingfield/components/clientlibs/customizingfield
Nell’interfaccia classica con ExtJS, nella struttura del contenuto era solito inserire i listener per un determinato widget. La stessa procedura nell’interfaccia touch è diversa, in quanto il codice listener JS (o qualsiasi altro codice) non è più definito nel contenuto.
La struttura del contenuto descrive la struttura semantica; non deve implicare la natura del widget sottostante. Se il codice JS non è presente nella struttura del contenuto, potete modificare i dettagli di implementazione senza dover modificare la struttura del contenuto. In altre parole, potete modificare la libreria dei widget senza dover toccare la struttura del contenuto.
Se si dispone di un JavaScript personalizzato che deve essere eseguito solo quando la finestra di dialogo è disponibile e pronta, è necessario ascoltare l'evento dialog-ready
.
Questo evento viene attivato ogni volta che la finestra di dialogo viene caricata (o ricaricata) ed è pronta per l’uso, il che significa che ogni volta che si verifica una modifica (creazione/aggiornamento) nel DOM della finestra di dialogo.
dialog-ready
può essere utilizzato per collegare in JavaScript codice personalizzato che esegue personalizzazioni sui campi all'interno di una finestra di dialogo o attività simili.
Per contrassegnare un dato campo come obbligatorio, impostare la seguente proprietà sul nodo di contenuto del campo:
required
Boolean
Ad esempio, vedete:
/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title
La convalida dei campi nell'interfaccia utente Granite e nei componenti dell'interfaccia utente Granite (equivalenti ai widget) viene eseguita utilizzando l'API foundation-validation
. Per ulteriori informazioni, consulta la documentazione foundation-valdiation
Granite.
Per esempi, vedete:
cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js
/libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js
La finestra di dialogo Progettazione viene visualizzata quando un componente dispone di dettagli di progettazione che possono essere modificati in Modalità progettazione.
La definizione è molto simile a quella di una finestra di dialogo utilizzata per modificare i contenuti, con la differenza che è definita come nodo:
cq:design_dialog
nt:unstructured
Un editor interno consente all'utente di modificare il contenuto direttamente nel flusso di paragrafi, senza dover aprire una finestra di dialogo. Ad esempio, i componenti Testo standard e Titolo dispongono entrambi di un editor locale.
Un editor locale non è necessario/significativo per ogni tipo di componente.
Per ulteriori informazioni, consultate Estensione dell'authoring delle pagine - Aggiungi nuovo editor interno.
La barra degli strumenti del componente consente all'utente di accedere a una serie di azioni per il componente, come modificare, configurare, copiare ed eliminare.
Per ulteriori informazioni, consultate Estensione dell'authoring delle pagine - Aggiungi nuova azione a una barra degli strumenti di un componente.
Se il nuovo componente fa riferimento a contenuti provenienti da altre pagine, è possibile valutare se l'effetto delle sezioni Contenuto in prestito e Contenuto in prestito della Barra Riferimenti.
Il componente Riferimento viene AEM solo dal componente Predefinito. Per aggiungere il componente è necessario configurare il bundle OSGi Configurazione di riferimento per l’authoring WCM.
Create una nuova voce nella definizione, specificando il componente e la proprietà da controllare. Esempio:
/apps/<your-Project>/components/reference@parentPath
Quando lavorate con AEM esistono diversi metodi per gestire le impostazioni di configurazione per tali servizi. Per ulteriori informazioni e procedure consigliate, vedere Configurazione di OSGi.
Dopo che il componente è stato sviluppato, deve essere abilitato per l’uso in un sistema paragrafo appropriato, in modo che possa essere utilizzato nelle pagine richieste.
A tale scopo:
AEM offre la possibilità di configurare un sistema paragrafo sulla pagina in modo che un'istanza del nuovo componente venga creata automaticamente quando un utente trascina una risorsa (appropriata) su un'istanza della pagina (invece di dover sempre trascinare un componente vuoto sulla pagina).
Questo comportamento e la relazione tra risorse e componenti richiesta possono essere configurati:
Nella definizione di paragrafo della struttura della pagina. Esempio:
/etc/designs/<myApp>/page/par
Crea un nuovo nodo:
cq:authoring
nt:unstructured
In questa sezione, crea un nuovo nodo per contenere tutte le mappature asset-to-component:
assetToComponentMapping
nt:unstructured
Per ogni mappatura risorsa-componente, crea un nodo:
nt:unstructured
Ciascuno con le seguenti proprietà:
assetGroup
:
String
media
assetMimetype
:
String
image/*
droptarget
:
String
image
resourceType
:
String
foundation/components/image
type
:
String
Images
Per esempi, vedete:
/etc/designs/geometrixx/jcr:content/page/par/cq:authoring
/etc/designs/geometrixx-outdoors/jcr:content/page/par/cq:authoring
/etc/designs/geometrixx-media/jcr:content/article/article-content-par/cq:authoring
CODICE SU GITHUB
Puoi trovare il codice di questa pagina su GitHub
La creazione automatica di istanze di componenti ora può essere configurata facilmente nell'interfaccia utente quando si utilizzano Componenti di base e Modelli modificabili. Per ulteriori informazioni sulla definizione dei componenti automaticamente associati a determinati tipi di supporti, vedere Creazione di modelli di pagina.
L'estensione AEM parentesi quadre offre un flusso di lavoro fluido per la modifica AEM componenti e librerie client. Si basa sull'editor di codice Brackets.
L'estensione:
Le parentesi sono il meccanismo consigliato per la creazione di componenti. Sostituisce la funzionalità CRXDE Lite - Crea componente, progettata per l’interfaccia classica.
Durante la migrazione di un componente progettato per l’uso con l’interfaccia classica a un componente che può essere utilizzato con l’interfaccia touch (solo o insieme), devono essere considerati i seguenti problemi:
HTL
Componenti
cq:listener
che utilizza funzioni specifiche dell'interfaccia classicacq:listener
codice che utilizza funzioni specifiche dell’interfaccia classicaFinestre di dialogo
Se state eseguendo la migrazione di un progetto progettato per l'interfaccia classica, il codice cq:listener
(e i client correlati ai componenti) potrebbe utilizzare funzioni specifiche dell'interfaccia classica (ad esempio CQ.wcm.*
). Per la migrazione è necessario aggiornare tale codice utilizzando gli oggetti/le funzioni equivalenti nell’interfaccia touch.
Se il progetto viene migrato completamente nell’interfaccia touch, è necessario sostituire tale codice per utilizzare gli oggetti e le funzioni pertinenti all’interfaccia touch.
Tuttavia, se il progetto deve soddisfare sia l’interfaccia classica che l’interfaccia touch durante il periodo di migrazione (lo scenario più consueto), è necessario implementare uno switch per distinguere il codice separato che fa riferimento agli oggetti appropriati.
Questo meccanismo di commutazione può essere implementato come segue:
if (Granite.author) {
// touch UI
} else {
// classic UI
}
In qualità di sviluppatore, è necessario disporre di un accesso semplice alla documentazione del componente per comprendere rapidamente:
Per questo motivo, è abbastanza semplice rendere disponibile qualsiasi marcatura della documentazione esistente all’interno del componente stesso.
È sufficiente inserire un file README.md
nella struttura del componente. Questa sezione verrà visualizzata nella console dei componenti.
La riduzione supportata è la stessa di quella per frammenti di contenuto.