Sviluppo di componenti AEM

I componenti AEM vengono utilizzati per conservare, formattare ed eseguire il rendering del contenuto reso disponibile sulle pagine web.

  • Quando si creano pagine, 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, consulta Sviluppo di eCommerce .

    • Durante la costruzione di un sito Communities i componenti possono fornire informazioni ai visitatori e raccogliere informazioni da essi.
      Per ulteriori informazioni, consulta Sviluppo di community .

  • Nell’istanza di pubblicazione i componenti eseguono il rendering del contenuto, presentandolo come necessario ai visitatori del sito web.

NOTA

Questa pagina è una continuazione del documento Componenti AEM - Nozioni di base.

ATTENZIONE

I componenti riportati di seguito /libs/cq/gui/components/authoring/dialog devono essere utilizzati solo nell’editor (finestre di dialogo dei componenti nell’authoring). Se vengono utilizzati altrove (ad esempio in una finestra di dialogo della procedura guidata), potrebbero non comportarsi come previsto.

Esempi di codice

Questa pagina fornisce la documentazione di riferimento (o collegamenti alla documentazione di riferimento) necessaria per sviluppare nuovi componenti per AEM. Per alcuni esempi pratici, consulta Sviluppo di componenti AEM - Esempi di codice .

Struttura

La struttura di base di un componente viene illustrata nella pagina Componenti AEM - Nozioni di base. Questo documento tratta sia le interfacce touch che quelle classiche. Anche se non è necessario utilizzare le impostazioni classiche nel nuovo componente, può essere utile tenerne conto quando si ereditano da componenti esistenti.

Estensione dei componenti e delle finestre di dialogo esistenti

A seconda del componente che desideri implementare, potrebbe essere possibile estendere o personalizzare un'istanza esistente, anziché definire e sviluppare da zero l'intera struttura.

Quando estendete o personalizzate un componente o 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.

Estensione di un componente esistente

L'estensione di un componente esistente può essere ottenuta con Gerarchia dei tipi di risorsa e i relativi meccanismi di ereditarietà.

NOTA

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

NOTA

Anche il componente frammento di contenuto può essere personalizzato ed esteso, anche se è necessario considerare la struttura e le relazioni complete con Assets.

Personalizzazione di una finestra di dialogo del componente esistente

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

Questo significa che devi solo ridefinire le differenze richieste, invece di ridefinire l’intera finestra di dialogo (utilizzando sling:resourceSuperType). Metodo consigliato per l’estensione di una finestra di dialogo di un componente

Per ulteriori informazioni, consulta Sling Resource Merger .

Definizione del markup

Viene eseguito il rendering del componente con HTML. Il componente deve definire l’HTML necessario per prendere il contenuto richiesto e quindi eseguirne il rendering come necessario, sia negli ambienti di authoring che di pubblicazione.

Utilizzo di HTML Template Language

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 consente di ottenere maggiore sicurezza ed efficienza di sviluppo.

NOTA

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.

Sviluppo della logica dei contenuti

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. Permette anche di usare logiche diverse per diverse viste della stessa risorsa.

Utilizzo di Java

L’API di utilizzo Java HTL abilita un file HTL per accedere a metodi helper in una classe Java personalizzata. Questo consente di utilizzare il codice Java per implementare la logica necessaria per selezionare e configurare il contenuto del componente.

Uso di JavaScript

L’API di utilizzo JavaScript HTL abilita un file HTL per 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.

Utilizzo di librerie HTML lato client

I siti web moderni si basano fortemente sull’elaborazione lato client basata su codice JavaScript e CSS complessi. Organizzare e ottimizzare il servizio di questo codice può essere un problema complicato.

Per risolvere questo problema, AEM fornisce Cartelle libreria lato client, che ti consentono di memorizzare il codice lato client nell’archivio, organizzarlo in categorie e definire quando e come ogni categoria di codice deve essere trasmessa al client. Il sistema di libreria lato client si occupa quindi di produrre i collegamenti corretti nella pagina web finale per caricare il codice corretto.

Leggi Utilizzo di librerie HTML lato client per ulteriori informazioni.

Configurazione del comportamento di modifica

Puoi configurare il comportamento di modifica di un componente, compresi attributi come 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à specifiche e nodi figlio.

Configurazione del comportamento di anteprima

Il cookie WCM Mode viene impostato quando si passa alla modalità Preview 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.

NOTA

Nell’interfaccia touch sono utilizzati solo i valori EDIT e PREVIEW per il cookie WCM Mode .

Creazione e configurazione di una finestra di dialogo

Le finestre di dialogo consentono all’autore di interagire con il componente. L’utilizzo di una finestra di dialogo consente agli autori e/o agli amministratori di modificare il contenuto, configurare il componente o definire parametri di progettazione (mediante una finestra di dialogo Progettazione)

Interfaccia Coral e interfaccia Granite

L’ interfaccia Corale l’ interfaccia Granite definiscono l’aspetto moderno dell’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, puoi estendere questa selezione e creare un widget personalizzato.

Per ulteriori informazioni sullo sviluppo di componenti con tipi di risorse Coral e Granite, consulta: Creazione di componenti di Experience Manager utilizzando i tipi di risorse Coral/Granite.

Per maggiori dettagli consultare:

NOTA

A causa della natura dei componenti dell’interfaccia utente Granite (e delle differenze con i widget ExtJS), esistono alcune differenze tra il modo in cui i componenti interagiscono con l’interfaccia touch e l’ interfaccia classica.

Creazione di una nuova finestra di dialogo

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 relativa definizione del componente.

  • vengono sottoposti a rendering sul lato server (come componenti Sling), in base alla struttura del contenuto e alla proprietà sling:resourceType .

  • utilizza il framework dell'interfaccia utente Granite.

  • contiene una struttura di nodo che descrive i campi all’interno della finestra di dialogo.

    • questi nodi sono nt:unstructured con la proprietà sling:resourceType richiesta.

Un esempio di struttura del nodo potrebbe essere:

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 stessa è un componente (ad esempio, il markup rappresentato da uno script di un componente insieme al comportamento/stile fornito da una libreria client).

Per esempi, consulta:

  • /libs/foundation/components/text/cq:dialog
  • /libs/foundation/components/download/cq:dialog
NOTA

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. Consulta Componenti AEM per l'interfaccia classica.

Personalizzazione dei campi della finestra di dialogo

NOTA

Consulta:

Creazione di un nuovo campo

I widget per l’interfaccia touch sono implementati come componenti dell’interfaccia utente Granite.

Per creare un nuovo widget da utilizzare in una finestra di dialogo dei componenti per l’interfaccia utente touch, è necessario creare un nuovo componente per campi Granite UI.

NOTA

Per informazioni dettagliate sull'interfaccia utente Granite, consulta la documentazione Granite UI.

Se si considera la finestra di dialogo come un contenitore semplice 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

In modo più specifico, l’interfaccia utente Granite fornisce una serie di componenti per campi adatti alle finestre di dialogo (o, più in generale, nei moduli).

NOTA

Questa funzione è diversa dall’interfaccia classica, in cui i widget sono rappresentati dai nodi cq:Widgets, ciascuno con un particolare xtype per stabilire la relazione con il relativo widget ExtJS. Dal punto di vista dell'implementazione, questi widget sono stati resi sul lato client dal framework ExtJS.

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 che fa riferimento al tipo di risorsa appena introdotto.

Creazione di una libreria client per stile e comportamento

Se desideri definire stile e comportamento per il componente, puoi creare una libreria client dedicata che definisce i tuoi 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 caricare la libreria client per tutte le finestre di dialogo, imposta la proprietà category della libreria client su cq.authoring.dialog. Questo è il nome della categoria della libreria client inclusa per impostazione predefinita durante il rendering di tutte le finestre di dialogo. Si desidera eseguire questa operazione se la libreria client è piccola e/o il campo è generico e può essere riutilizzato in altre finestre di dialogo.

Ad esempio, consulta:

  • cqgems/customizingfield/components/colorpicker/clientlibs

Estensione (ereditarietà da) un campo

A seconda delle tue esigenze, puoi:

  • Estende un determinato campo dell’interfaccia Granite in base all’ereditarietà dei componenti ( sling:resourceSuperType)
  • Estendi un determinato widget dalla libreria di widget sottostante (nel caso dell'interfaccia utente Granite, questa è l'interfaccia utente Coral), seguendo l'API della libreria di widget (ereditarietà JS/CSS)

Accesso ai campi della finestra di dialogo

È 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"]

Gestione degli eventi dei campi

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 di avere ascoltatori nella struttura del contenuto.

Listener in una libreria client personalizzata

Per inserire una logica nel campo, devi:

  1. Indicare il campo contrassegnato con una determinata classe CSS (il gancio).
  2. Definisci, nella libreria client, un listener JS collegato al nome della classe CSS (in questo modo la logica personalizzata viene delimitata solo nel campo e non influisce su altri campi dello stesso tipo).

Per ottenere questo risultato è necessario conoscere la libreria di widget sottostante con cui si desidera interagire. Consulta la documentazione Coral UI per identificare l'evento a cui desideri reagire. È molto simile al processo che si era dovuto eseguire con ExtJS in passato: trova la pagina della documentazione di un determinato widget, quindi controlla i dettagli della sua API evento.

Ad esempio, consulta:

  • cqgems/customizingfield/components/clientlibs/customizingfield

Ascoltatori nella struttura del contenuto

Nell’interfaccia classica con ExtJS, nella struttura dei contenuti era solito avere ascoltatori per un determinato widget. Il raggiungimento dello stesso risultato nell’interfaccia touch è diverso perché il codice del 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. Non disponendo di codice JS nella struttura del contenuto, puoi modificare i dettagli di implementazione senza dover modificare la struttura del contenuto. In altre parole, puoi modificare la libreria dei widget senza dover toccare la struttura del contenuto.

Rilevamento della disponibilità della finestra di dialogo

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 agganciare nel codice personalizzato JavaScript che esegue personalizzazioni sui campi all’interno di una finestra di dialogo o attività simili.

Convalida campo

Campo obbligatorio

Per contrassegnare un dato campo come obbligatorio, imposta la seguente proprietà sul nodo del contenuto del campo:

  • Nome: required
  • Tipo: Boolean

Ad esempio, consulta:

/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title

Convalida del campo (interfaccia Granite)

La convalida dei campi nell’interfaccia Granite e nei componenti dell’interfaccia Granite (equivalenti ai widget) viene eseguita utilizzando l’API foundation-validation . Per ulteriori informazioni, consulta la documentazione foundation-valdiation Granite .

Per esempi, consulta:

  • cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js

  • /libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js

Creazione e configurazione di una finestra di dialogo di progettazione

La finestra di dialogo Progettazione viene visualizzata quando un componente presenta dettagli di progettazione che possono essere modificati in Modalità Progettazione.

La definizione è molto simile a quella di una finestra di dialogo utilizzata per modificare il contenuto, con la differenza che è definita come nodo:

  • Nome nodo: cq:design_dialog
  • Tipo: nt:unstructured

Creazione e configurazione di un editor interno

Un editor interno consente all’utente di modificare il contenuto direttamente nel flusso di paragrafi, senza la necessità di aprire una finestra di dialogo. Ad esempio, i componenti Testo e Titolo standard dispongono entrambi di un editor interno.

Un editor interno non è necessario/significativo per ogni tipo di componente.

Per ulteriori informazioni, consulta Estensione dell’authoring delle pagine - Aggiungi nuovo editor interno .

Personalizzazione della barra degli strumenti del componente

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, consulta Estensione dell’authoring delle pagine - Aggiungere una nuova azione a una barra degli strumenti di un componente .

Configurazione di un componente per la barra laterale Riferimenti (prestato/prestato)

Se il nuovo componente fa riferimento a contenuti di altre pagine, puoi considerare se debba avere un impatto sulle sezioni Contenuto prestato e Contenuto prestato della barra laterale Riferimenti.

Il componente Riferimento AEM viene selezionato solo come componente predefinito. Per aggiungere il componente è necessario configurare il bundle OSGi WCM Authoring Content Reference Configuration.

Crea una nuova voce nella definizione, specificando il componente e la proprietà da controllare. Esempio:

/apps/<*your-Project*>/components/reference@parentPath

NOTA

Quando si lavora con AEM esistono diversi metodi per gestire le impostazioni di configurazione per tali servizi. Per ulteriori informazioni e pratiche consigliate, consulta Configurazione di OSGi .

Abilitazione e aggiunta del componente al sistema paragrafo

Una volta sviluppato, il componente deve essere abilitato per l’uso in un sistema paragrafo appropriato, in modo che possa essere utilizzato nelle pagine richieste.

Questo può essere fatto da:

La configurazione di un sistema di paragrafi in modo che il trascinamento di una risorsa crei un’istanza di componente

AEM offre la possibilità di configurare un sistema di paragrafi sulla pagina in modo che un’istanza del nuovo componente venga creata automaticamente quando un utente trascina una risorsa (appropriata) in un’istanza della pagina (anziché sempre trascinare un componente vuoto nella pagina).

Questo comportamento e la relazione risorsa-componente richiesta possono essere configurati:

  1. Sotto la definizione di paragrafo della progettazione della pagina. Esempio:

    • /etc/designs/<myApp>/page/par

    Crea un nuovo nodo:

    • Nome: cq:authoring
    • Tipo: nt:unstructured
  2. In questo crea un nuovo nodo per contenere tutte le mappature asset-to-component:

    • Nome: assetToComponentMapping
    • Tipo: nt:unstructured
  3. Per ogni mappatura asset-to-component crea un nodo:

    • Nome: testo; si raccomanda che il nome indichi l’attività e il tipo di componente correlato; ad esempio, image
    • Tipo: nt:unstructured

    Ognuna con le seguenti proprietà:

    • assetGroup:

      • Tipo: String
      • Valore: il gruppo al quale appartiene l'attività connessa; ad esempio, media
    • assetMimetype:

      • Tipo: String
      • Valore: il tipo MIME dell’attività correlata; ad esempio image/*
    • droptarget:

      • Tipo: String
      • Valore: l'obiettivo di caduta; ad esempio, image
    • resourceType:

      • Tipo: String
      • Valore: la relativa risorsa componente; ad esempio, foundation/components/image
    • type:

      • Tipo: String
      • Valore: il tipo, ad esempio Images

Per esempi consulta:

  • /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

NOTA

La creazione automatica di istanze di componenti può ora essere configurata facilmente nell’interfaccia utente quando si utilizzano Componenti core e modelli modificabili. Per ulteriori informazioni su come definire quali componenti sono associati automaticamente a determinati tipi di file multimediali, consulta Creazione di modelli di pagina .

Utilizzo dell'estensione AEM Brackets

L’ AEM Estensione parentesi graffe fornisce un flusso di lavoro fluido per modificare AEM componenti e librerie client. Si basa sull’ editor di codice Brackets .

Estensione:

  • Semplifica la sincronizzazione (senza Maven o File Vault necessari) per aumentare l'efficienza degli sviluppatori e aiuta gli sviluppatori front-end con limitata conoscenza AEM a partecipare ai progetti.
  • Fornisce il supporto di HTL, il linguaggio del modello progettato per semplificare lo sviluppo dei componenti e aumentare la sicurezza.
NOTA

Brackets è il meccanismo consigliato per la creazione di componenti. Sostituisce la funzionalità CRXDE Lite - Crea componente , progettata per l’interfaccia classica.

Migrazione da un componente Classic

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 congiuntamente), è necessario tenere in considerazione i seguenti problemi:

Migrazione del codice cq:listener

Se stai eseguendo la migrazione di un progetto progettato per l’interfaccia classica, il codice cq:listener (e le clientlib relative 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 durante il periodo di migrazione il progetto deve essere compatibile sia con l’interfaccia classica che con quella touch (lo scenario più consueto), è necessario implementare uno switch per differenziare 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
}

Documentazione del componente

In qualità di sviluppatore, desideri accedere facilmente alla documentazione del componente per comprendere rapidamente:

  • Descrizione
  • Uso previsto
  • Struttura e proprietà del contenuto
  • API e punti di estensione esposti
  • Ecc.

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

È sufficiente inserire un file README.md nella struttura del componente. Questa Markdown verrà quindi visualizzata nella console dei componenti.

chlimage_1-7

Il markdown supportato è lo stesso di quello per frammenti di contenuto.

In questa pagina