Sviluppo di componenti AEM

AEM componenti sono utilizzati per conservare, formattare ed eseguire il rendering del contenuto reso disponibile sulle pagine Web.

• Durante la creazione di 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.

    See Developing eCommerce for more information.

  • Quando si crea un sito Community , i componenti possono fornire informazioni e raccogliere informazioni dai visitatori.

    See Developing Communities for more information.

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

Esempi di codice

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, consulta Sviluppo di componenti AEM - Esempi di codice.

Struttura

La struttura di base di un componente è coperta sulla pagina AEM Componenti - Concetti di base. 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.

Estensione di componenti e finestre di dialogo esistenti

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

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.

Estensione di un componente esistente

L’estensione di un componente esistente può essere ottenuta tramite Gerarchia tipo di risorsa e i relativi meccanismi di ereditarietà.

Personalizzazione di una finestra di dialogo di componente esistente

È inoltre possibile ignorare una finestra di dialogo di 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 (mediante sling:resourceSuperType). Metodo consigliato per l’estensione della finestra di dialogo di un componente

Per ulteriori informazioni, vedere la sezione Fusione risorse Sling.

Definizione del codice

Viene eseguito il rendering del componente 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.

Utilizzo del linguaggio HTML Template Language

The HTML Templating Language (HTL), introduced with AEM 6.0, takes the place of JSP (JavaServer Pages) as the preferred and recommended server-side template system for 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.

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. Consente inoltre logiche diverse per diverse viste della stessa risorsa.

Utilizzo di Java

L'API Use-API Java HTL consente a un file HTL di accedere ai metodi helper in una classeJava personalizzata. Questo consente di utilizzare il codice Java per implementare la logica di selezione e configurazione del contenuto del componente.

Uso di JavaScript

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.

Utilizzo di librerie HTML lato client

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.

Per ulteriori informazioni, consultate Utilizzo delle librerie HTML lato client.

Configurazione del comportamento Modifica

È 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 cq:editConfig nodo di tipo cq:EditConfig sotto il nodo del componente (di tipo cq:Component) e aggiungendo proprietà specifiche e nodi secondari.

Configurazione del comportamento Anteprima

Il cookie Modalità WCM 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.

Creazione e configurazione di una finestra di dialogo

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 (tramite una finestra di dialogo Progettazione)

Interfaccia utente Coral e interfaccia Granite

L’interfaccia Coral e l’interfaccia 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 componenti di Experience Manager utilizzando i tipidi risorse Corallo/Granite.

Per maggiori dettagli, consulta:

• Interfaccia utente Coral

  • Fornisce un'interfaccia utente coerente in tutte le soluzioni cloud
  • Concetti dell’interfaccia AEM touch - Interfaccia Coral
  • Guida all’interfaccia utente Coral

• Interfaccia Granite

  • Fornisce il codice Coral UI racchiuso nei componenti Sling per la creazione di console e finestre di dialogo dell'interfaccia utente
  • Concetti dell’interfaccia AEM touch - Interfaccia Granite
  • Documentazione di Granite UI

Creating a New Dialog

Finestre di dialogo per l’interfaccia touch:

• sono denominati cq:dialog.

• sono definiti come un nt:unstructured nodo con la sling:resourceType proprietà impostata.

• si trovano sotto il relativo cq:Component nodo e accanto alla relativa definizione del componente.

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

• utilizzate il framework di interfaccia utente Granite.

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

  • questi nodi sono nt:unstructured con la sling:resourceType proprietà 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

Personalizzazione dei campi di dialogo

Creating a New Field

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 dei componenti per l’interfaccia touch, è necessario creare un nuovo componenteCampo interfaccia Granite.

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 (tramite sling:resourceSuperType):

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

Più precisamente, l’interfaccia utente Granite offre una serie di componenti per campo che possono essere utilizzati nelle finestre di dialogo (o, più in generale, nei moduli).

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.

Creazione di una libreria client per stile e comportamento

Se desiderate definire lo stile e il comportamento del componente, potete creare una libreria client dedicata che definisca i vostri 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

  • fornito dall'esempio di codice

Estensione (ereditarietà da) di un campo

A seconda delle esigenze, potete:

• Estendi un dato campo dell’interfaccia Granite in base all’ereditarietà del componente ( sling:resourceSuperType)
• Estendi un determinato widget dalla libreria di widget sottostante (nel caso dell’interfaccia utente Granite, si tratta dell’interfaccia utente Coral), seguendo l’API della libreria di widget (ereditarietà JS/CSS)

Accesso ai campi di dialogo

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

Gestione degli eventi dei campi

Il metodo di gestione degli eventi nei campi di dialogo ora viene utilizzato con i listener in una libreriaclient personalizzata. Si tratta di una modifica rispetto al metodo precedente, che prevede l'inclusione di listener nella strutturadel contenuto.

Listener in una libreria client personalizzata

Per inserire la logica nel campo, è necessario:

1. Il campo deve essere contrassegnato con una determinata classe CSS (il gancio).
2. Definite, nella libreria client, un listener JS collegato al nome della classe CSS (in questo modo la logica personalizzata viene limitata al campo e non influisce sugli altri campi dello stesso tipo).

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

  • fornito dall'esempio di codice

Listener nella struttura del contenuto

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.

Convalida del campo

Campo obbligatorio

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

• Nome: required
• Tipo: Boolean

Ad esempio, vedete:

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

Convalida dei campi (interfaccia utente Granite)

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

Per esempi, vedete:

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

  • fornito dall'esempio di codice

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

Creazione e configurazione di una finestra di dialogo Progettazione

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 il contenuto, con la differenza che è definita come nodo:

• Node name: 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 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, consulta Estensione dell’authoring delle pagine - Aggiungi nuovo editor interno.

Personalizzazione della barra degli strumenti del componente

La barra degli strumenti del componente permette all’utente di accedere a una serie di azioni per il componente, quali modifica, configurazione, copia ed eliminazione.

Per ulteriori informazioni, consulta Estensione dell’authoring delle pagine - Aggiunta di nuove azioni alla barra degli strumenti di un componente.

Configurazione di un componente per la barra laterale Riferimenti (Presa in prestito/Presa in prestito)

Se il nuovo componente fa riferimento a contenuti provenienti da altre pagine, potete valutare se la modifica avrà un impatto sulle sezioni Contenuto ​​in prestito e Contenuto ​​prestato della Barrariferimenti.

Il componente Riferimento viene AEM solo dal componente Out-of-the-box. Per aggiungere il componente è necessario configurare il bundle OSGi Configurazione di riferimento per l’authoring di contenuti WCM in un bundle.

Create una nuova voce nella definizione, specificando il componente e la proprietà da controllare. Ad esempio:

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

Attivazione e aggiunta del componente al sistema paragrafo

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:

• utilizzo della modalità Progettazione per modificare una pagina specifica.
• definizione della proprietà components nel sistema paragrafo di un modello.

Configuring a Paragraph System so that Dragging an Asset Creates a Component Instance

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:

1. Nella definizione di paragrafo della struttura della pagina. Ad esempio:

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

   Crea un nuovo nodo:

   • Nome: cq:authoring
   • Tipo: nt:unstructured

2. In questa sezione, crea un nuovo nodo per contenere tutte le mappature asset-to-component:

   • Nome: assetToComponentMapping
   • Tipo: nt:unstructured

3. Per ogni mappatura risorsa-componente, crea un nodo:

   • Nome: text; si raccomanda che il nome indichi la risorsa e il tipo di componente correlato; ad esempio, image
   • Tipo: nt:unstructured

   Ciascuno con le seguenti proprietà:

   • assetGroup:

     • Tipo: String
     • Valore: il gruppo cui appartiene l’attività correlata; ad esempio, media

   • assetMimetype:

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

   • droptarget:

     • Tipo: String
     • Valore: il bersaglio di caduta; ad esempio, image

   • resourceType:

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

   • type:

     • Tipo: String
     • Valore: il tipo, ad esempio, 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

• Apri progetto aem-project-archetype su GitHub
• Scarica il progetto come file ZIP

Utilizzo dell’estensione AEM parentesi

L’estensione AEM parentesi offre un flusso di lavoro uniforme per la modifica AEM componenti e librerie client. Si basa sull'editor del codice Brackets .

L'estensione:

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

Migrazione da un componente classico

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

  • L’utilizzo di HTL non è obbligatorio, ma se il componente deve essere aggiornato è il momento ideale per considerare la migrazione da JSP a HTL.

• Componenti

  • Migrare cq:listener il codice che utilizza funzioni specifiche dell’interfaccia classica
  • Per ulteriori informazioni, consultate Configurazione dell’editorRich Text.
  • Migrare cq:listener il codice che utilizza funzioni specifiche dell’interfaccia classica

• Finestre di dialogo

  • Sarà necessario creare una nuova finestra di dialogo da usare nell’interfaccia touch. Tuttavia, a fini di compatibilità, l’interfaccia touch può usare la definizione di una finestra di dialogo dell’interfaccia classica, se non è stata definita alcuna finestra di dialogo per l’interfaccia touch.
  • Lo strumento di conversione finestra di dialogo consente di estendere i componenti esistenti.
  • La mappatura di ExtJS su Granite UI Components offre una comoda panoramica dei tipi di xtype e di nodi ExtJS e dei tipi con i tipi di risorse equivalenti dell'interfaccia Granite.
  • Per ulteriori informazioni, consulta la sessione AEM Gems su Customizing Dialog Fields (Personalizzazione dei campidi dialogo).
  • Migrazione dai tipi alla convalida Granite UI
  • Utilizzando i listener JS, per ulteriori informazioni vedere Gestione degli eventi dei campi e la sessione AEM Gems su Personalizzazione dei campidi dialogo.

Migrazione del codice cq:listener

Se state eseguendo la migrazione di un progetto progettato per l’interfaccia classica, il cq:listener codice (e i clientlibs relativi 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
}

Documentazione del componente

In qualità di sviluppatore, è necessario disporre di un accesso semplice alla documentazione del componente per comprendere rapidamente:

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

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

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

La riduzione supportata è la stessa dei frammenti di contenuto.