Componenti AEM - Nozioni di base

Quando si inizia a sviluppare nuovi componenti è necessario comprendere le basi della loro struttura e configurazione.

Questo processo richiede la lettura della teoria e l'analisi dell'ampia gamma di implementazioni di componenti in un'istanza AEM standard. Quest’ultimo approccio è leggermente complicato dal fatto che, sebbene AEM sia passata a una nuova interfaccia touch standard, moderna, continua a supportare l’interfaccia classica.

Panoramica

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

Pianificazione

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

• Quali operazioni sono necessarie esattamente per il nuovo componente?

  • Una specifica chiara aiuta in tutte le fasi di sviluppo, test e consegna.

    I dettagli possono cambiare nel tempo, ma la specifica può essere aggiornata (anche se le modifiche devono essere documentate).

• È necessario creare un componente da zero o ereditare le nozioni di base da un componente esistente?

  • Non c'è bisogno di reinventare la ruota.
  • Esistono diversi meccanismi forniti da AEM per ereditare ed estendere i dettagli da un'altra definizione di componente, tra cui override, overlay e la Sling Resource Merger.

• Il componente richiede logica per selezionare o manipolare il contenuto?

  • La logica deve essere separata dal livello dell'interfaccia utente. HTL è progettato per contribuire a garantire che ciò avvenga.

• Il componente avrà bisogno di formattazione CSS?

  • La formattazione CSS deve essere separata dalle definizioni dei componenti. Definite le convenzioni per denominare gli elementi HTML in modo da poterli modificare tramite file CSS esterni.

• Quali aspetti di sicurezza devo prendere in considerazione?

  • Per ulteriori informazioni, vedere Security Checklist - Development Best Practices.

Interfaccia touch e interfaccia classica

Prima di iniziare qualsiasi discussione seria sullo sviluppo di componenti, è necessario conoscere l’interfaccia utente che gli autori utilizzeranno:

• Interfaccia utente touch
  L’ interfaccia utente standard introdotta in AEM 5.6.0 come anteprima ed estesa in 6.x. È basato sull’esperienza utente unificata per l’Adobe Marketing Cloud, utilizzando le tecnologie sottostanti dell’ interfaccia Coral e dell’interfaccia utente Granite.

• Interfaccia classica
  UIUser basata sulla tecnologia ExtJS introdotta con CQ 5.1.

Per ulteriori informazioni, vedere Interfaccia utente Recommendations per clienti.

I componenti possono essere implementati per supportare l’interfaccia touch, l’interfaccia classica o entrambi. Se osservate un’istanza standard, vengono inoltre visualizzati i componenti forniti originariamente per l’interfaccia classica, l’interfaccia touch o entrambi.

Per questo motivo descriveremo le basi di entrambi, e come riconoscerli, in questa pagina.

Logica dei contenuti e markup di rendering

È consigliabile mantenere il codice responsabile per la marcatura e il rendering separato dal codice che controlla la logica utilizzata per selezionare il contenuto del componente.

Questa filosofia è supportata da HTL, un linguaggio di modello appositamente limitato per garantire che un linguaggio di programmazione reale venga utilizzato per definire la logica di business sottostante. Questa logica (facoltativa) viene richiamata da HTL con un comando specifico. Questo meccanismo evidenzia il codice richiesto per una vista specifica e, se necessario, consente logiche specifiche per diverse viste dello stesso componente.

HTL vs JSP

HTL è un linguaggio HTML basato su modelli introdotto con AEM 6.0.

La discussione sull'utilizzo di HTL o JSP (Java Server Pages) durante lo sviluppo dei componenti deve essere semplice, in quanto HTL è ora il linguaggio di script consigliato per AEM.

HTL e JSP possono essere utilizzati per lo sviluppo di componenti sia per l’interfaccia classica che per quella touch. Anche se può esserci la tendenza a supporre che HTL sia solo per l’interfaccia touch e che sia JSP per l’interfaccia classica, si tratta di un’erronea concezione e più a causa dei tempi. L’interfaccia touch e l’HTL sono stati incorporati in AEM nello stesso periodo. Poiché HTL è ora la lingua consigliata, viene utilizzato per i nuovi componenti, che di solito sono per l’interfaccia touch.

Sviluppo dei propri componenti

Per creare componenti personalizzati per l’interfaccia utente appropriata, consulta (dopo aver letto questa pagina):

• Componenti AEM per l’interfaccia touch
• Componenti AEM per l’interfaccia classica

Un modo rapido per iniziare consiste nel copiare un componente esistente e quindi apportare le modifiche desiderate. Per informazioni su come creare componenti personalizzati e aggiungerli al sistema di paragrafi, consulta:

• Sviluppo di componenti (con particolare attenzione all’interfaccia touch)

Spostamento dei componenti nell'istanza di pubblicazione

I componenti per il rendering del contenuto devono essere distribuiti nella stessa istanza AEM contenuto. Pertanto, tutti i componenti utilizzati per l’authoring e il rendering delle pagine nell’istanza di creazione devono essere distribuiti nell’istanza di pubblicazione. Una volta distribuiti, i componenti sono disponibili per il rendering delle pagine attivate.

Per spostare i componenti nell’istanza di pubblicazione, usate i seguenti strumenti:

• Utilizzate Package Manager (Gestione pacchetti) per aggiungere i componenti a un pacchetto e spostarli in un'altra istanza AEM.
• Utilizzare lo strumento di replica Attiva albero per replicare i componenti.

Componenti a cui si deve prestare attenzione dall'avvio

• Pagina:

  • AEM ha il componente page ( cq:Page).
  • Si tratta di un tipo specifico di risorsa importante per la gestione dei contenuti.
    • Una pagina corrisponde a una pagina Web con contenuti per il sito Web.

• Sistemi paragrafo:

  • Il sistema paragrafo è una parte chiave di un sito Web in quanto gestisce un elenco di paragrafi. Viene utilizzato per contenere e strutturare i singoli componenti che contengono il contenuto effettivo.
  • È possibile creare, spostare, copiare ed eliminare paragrafi nel sistema di paragrafi.
  • È inoltre possibile selezionare i componenti da utilizzare in un sistema paragrafo specifico.
  • All'interno di un'istanza standard sono disponibili diversi sistemi di paragrafi (ad esempio parsys, [responsivegrid](/docs/experience-manager-64/sites-authoring/responsive-layout.md)).

Struttura

La struttura di un componente AEM è potente e flessibile, le considerazioni principali sono:

• Tipo risorsa
• Definizione componente
• Proprietà e nodi secondari di un componente
• Finestre di dialogo
• Finestre di dialogo Progettazione
• Disponibilità del componente
• Componenti e contenuti creati

Tipo risorsa

Un elemento chiave della struttura è il tipo di risorsa.

• La struttura del contenuto dichiara le intenzioni.
• Il tipo di risorsa li implementa.

Questa è un'astrazione che aiuta a garantire che anche quando l'aspetto e il sentire cambiano nel tempo, l'intenzione rimane il tempo.

Definizione del componente

Nozioni di base sui componenti

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

• AEM componenti si basano su Sling.

• AEM componenti si trovano (in genere) in:

  • HTL: /libs/wcm/foundation/components
  • JSP: /libs/foundation/components

• I componenti specifici per progetto/sito si trovano (in genere) in:

  • /apps/<myApp>/components

• AEM componenti standard sono definiti come cq:Component e presentano gli elementi chiave:

  • proprietà JCR:

    Un elenco delle proprietà JCR; queste sono variabili e alcune possono essere facoltative attraverso la struttura di base di un nodo di componente, le sue proprietà e i suoi sottonodi sono definiti dalla definizione cq:Component

  • Riferimenti:

    Definiscono gli elementi statici usati dal componente.

  • Script:

  Sono utilizzati per implementare il comportamento dell’istanza risultante del componente.

• Nodo principale:

  • <mycomponent> (cq:Component) - Nodo gerarchico del componente.

• Proprietà vitali:

  • jcr:title - Titolo componente; ad esempio, utilizzato come etichetta quando il componente è elencato nel browser o nella barra laterale dei componenti.

  • jcr:description - Descrizione del componente; può essere utilizzato come hint di posizionamento del mouse nel browser o nella barra laterale dei componenti.

  • Interfaccia classica:

    • icon.png - Icona per questo componente.
    • thumbnail.png - Immagine visualizzata se questo componente è elencato nel sistema di paragrafi.

  • Interfaccia touch

    • Per ulteriori informazioni, vedere la sezione Icona componente nell'interfaccia touch.

• Nodi secondari fondamentali:

  • cq:editConfig (cq:EditConfig) - Definisce le proprietà di modifica del componente e abilita la visualizzazione del componente nel browser Componenti o nella barra laterale.

    Nota: se il componente dispone di una finestra di dialogo, viene visualizzato automaticamente nel browser Componenti o nella barra laterale, anche se cq:editConfig non esiste.

  • cq:childEditConfig (cq:EditConfig) - Controlla gli aspetti dell’interfaccia utente dell’autore per i componenti secondari che non ne definiscono uno personalizzato cq:editConfig.

  • Interfaccia utente touch:

    • cq:dialog ( nt:unstructured) - Finestra di dialogo per questo componente. Definisce l’interfaccia che consente all’utente di configurare il componente e/o di modificarne il contenuto.
    • cq:design_dialog ( nt:unstructured) - Modifica progettazione per questo componente

  • Interfaccia classica:

    • dialog ( cq:Dialog) - Finestra di dialogo per questo componente. Definisce l’interfaccia che consente all’utente di configurare il componente e/o di modificarne il contenuto.
    • design_dialog ( cq:Dialog) - Modifica progettazione per questo componente.

Icona componente nell'interfaccia touch

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

1. cq:icon - Proprietà String che punta a un'icona standard nella libreria Coral UI da visualizzare nel browser dei componenti

   • Utilizzate il valore dell'attributo HTML dell'icona Corallo.

2. abbreviation - Proprietà String per personalizzare l'abbreviazione del nome del componente nel browser Componenti

   • L'abbreviazione deve essere limitata a due caratteri.

   • Se si specifica una stringa vuota, l'abbreviazione verrà generata dai primi due caratteri della proprietà jcr:title.

     • Ad esempio "Im" per "Image"
     • Il titolo localizzato verrà utilizzato per creare l’abbreviazione.

   • L'abbreviazione viene tradotta solo se il componente dispone di una proprietà abbreviation_commentI18n, che viene quindi utilizzata come hint di traduzione.

3. cq:icon.png o cq:icon.svg - Icona per questo componente, visualizzata nel browser Componenti

   • 20 x 20 pixel è la dimensione delle icone dei componenti standard.

     • Le icone più grandi verranno ridotte (lato client).

   • Il colore consigliato è rgb(112, 112, 112) > #707070

   • Lo sfondo delle icone dei componenti standard è trasparente.

   • Sono supportati solo i file .png e .svg.

   • Se si importa dal file system tramite il plug-in Eclipse, i nomi dei file devono essere preceduti, ad esempio, da un carattere di escape come _cq_icon.png o _cq_icon.svg.

   • .png prende un precedente rispetto a .svg se entrambi sono presenti

Se sul componente non viene trovata nessuna delle proprietà di cui sopra ( cq:icon, abbreviation, cq:icon.png o cq:icon.svg):

• Il sistema cercherà le stesse proprietà sui super componenti che seguono la proprietà sling:resourceSuperType.
• Se a livello di super componente non viene trovata alcuna abbreviazione o un'abbreviazione vuota, il sistema genererà l'abbreviazione dalle prime lettere della proprietà jcr:title del componente corrente.

Per annullare l'ereditarietà delle icone dai super componenti, l'impostazione di una proprietà vuota abbreviation sul componente ripristina il comportamento predefinito.

La console dei componenti mostra come viene definita l'icona di un particolare componente.

Esempio di icona SVG

<?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 secondari di un componente

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

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

Nome	Tipo	Descrizione
.	cq:Component	Componente corrente. Un componente è di tipo nodo cq:Component.
componentGroup	String	Gruppo in cui è possibile selezionare il componente nel browser Componenti (interfaccia touch) o nella barra laterale (interfaccia classica). Il valore di .hidden è utilizzato per i componenti che non possono essere selezionati dall’interfaccia utente, ad esempio i sistemi paragrafo effettivi.
cq:isContainer	Boolean	Indica se il componente è un componente contenitore e può quindi contenere altri componenti, ad esempio un sistema paragrafo.
cq:dialog	nt:unstructured	Definizione della finestra di dialogo di modifica per l’interfaccia touch.
dialog	cq:Dialog	Definizione della finestra di dialogo di modifica per l’interfaccia classica.
cq:design_dialog	nt:unstructured	Definizione della finestra di dialogo di progettazione per l’interfaccia touch.
design_dialog	cq:Dialog	Definizione della finestra di dialogo di progettazione per l'interfaccia classica.
dialogPath	String	Percorso di una finestra di dialogo che copre il caso in cui il componente non dispone di un nodo di dialogo.
cq:cellName	String	Se impostata, questa proprietà viene impostata come ID cella. Per ulteriori informazioni, consultare l'articolo della Knowledge Base How are Design Cell IDs build.
cq:childEditConfig	cq:EditConfig	Quando il componente è un contenitore, come ad esempio un sistema paragrafo, questo determina la configurazione di modifica dei nodi secondari.
cq:editConfig	cq:EditConfig	Modificare la configurazione del componente.
cq:htmlTag	nt:unstructured	Restituisce attributi di tag aggiuntivi aggiunti al tag HTML circostante. Consente l'aggiunta di attributi ai div generati automaticamente.
cq:noDecoration	Boolean	Se true, il rendering del componente non viene eseguito con classi div e css generate automaticamente.
cq:template	nt:unstructured	Se trovato, questo nodo verrà utilizzato come modello di contenuto quando il componente viene aggiunto dal Browser componenti o dalla barra laterale.
cq:templatePath	String	Percorso di un nodo da utilizzare come modello di contenuto quando il componente viene aggiunto dal browser Componenti o dalla barra laterale. Deve essere un percorso assoluto, non relativo al nodo del componente. A meno che non desideriate riutilizzare il contenuto già disponibile altrove, questo non è necessario ed cq:template è sufficiente (vedete di seguito).
jcr:created	Date	Data di creazione del componente.
jcr:description	String	Descrizione del componente.
jcr:title	String	Titolo del componente.
sling:resourceSuperType	String	Quando viene impostato, il componente eredita da questo componente.
virtual	sling:Folder	Abilita la creazione di componenti virtuali. Per visualizzare un esempio, consultare il componente di contatto all'indirizzo: /libs/foundation/components/profile/form/contact
<breadcrumb.jsp>	nt:file	File di script.
icon.png	nt:file	Icona del componente, visualizzata accanto al titolo nella barra laterale.
thumbnail.png	nt:file	Miniatura opzionale visualizzata durante il trascinamento del componente dalla barra laterale.

Se osserviamo il componente Testo (una delle due versioni), è possibile vedere i seguenti elementi:

• HTL ( /libs/wcm/foundation/components/text)

  

• JSP ( /libs/foundation/components/text)

  

Le proprietà di particolare interesse comprendono:

• jcr:title - titolo del componente; può essere utilizzato per identificare il componente, ad esempio, nell’elenco dei componenti nel browser o nella barra laterale dei componenti

• jcr:description - descrizione del componente; può essere usato come hint di posizionamento del mouse nell’elenco dei componenti nella barra laterale

• sling:resourceSuperType: indica il percorso di ereditarietà quando si estende un componente (sostituendo una definizione)

I nodi secondari di particolare interesse includono:

• cq:editConfig ( cq:EditConfig) - questo controlla gli aspetti visivi; ad esempio, può definire l'aspetto di una barra o di un widget, oppure aggiungere controlli personalizzati

• cq:childEditConfig ( cq:EditConfig) - controlla gli aspetti visivi dei componenti secondari che non hanno una propria definizione

• Interfaccia utente touch:

  • cq:dialog ( nt:unstructured) - definisce la finestra di dialogo per la modifica del contenuto di questo componente
  • cq:design_dialog ( nt:unstructured) - specifica le opzioni di modifica della progettazione per questo componente

• Interfaccia classica:

  • dialog ( cq:Dialog) - Definisce la finestra di dialogo per la modifica del contenuto di questo componente (specifica per l’interfaccia classica)
  • design_dialog ( cq:Dialog) - specifica le opzioni di modifica della progettazione per questo componente
  • icon.png - file di grafica da usare come icona per il componente nella barra laterale
  • thumbnail.png - file di grafica da usare come miniatura per il componente mentre lo trascinate dalla barra laterale

Finestre di dialogo

Le finestre di dialogo sono un elemento chiave del componente in quanto forniscono un’interfaccia che consente agli autori di configurare e fornire input a tale componente.

A seconda della complessità del componente, la finestra di dialogo può richiedere una o più schede, per contenere la lunghezza della finestra di dialogo e ordinare i campi di input.

Le definizioni delle finestre di dialogo sono specifiche dell’interfaccia:

• Interfaccia utente touch

  • cq:dialog ( nt:unstructured) nodes:

    • definire la finestra di dialogo per la modifica del contenuto di questo componente

    • specifica per l’interfaccia touch

    • sono definiti utilizzando componenti dell’interfaccia utente Granite

    • hanno una proprietà sling:resourceType, come struttura di contenuto Sling standard

    • può disporre di una proprietà helpPath per definire la risorsa della guida sensibile al contesto (percorso assoluto o relativo) a cui si accede quando si utilizza l'icona della Guida (l'icona ? icon) è selezionata.

      • Per i componenti out-of-the-box questo fa spesso riferimento a una pagina nella documentazione.
      • Se non viene specificato helpPath, viene visualizzato l'URL predefinito (pagina di panoramica della documentazione).

  

  All’interno della finestra di dialogo, sono definiti i singoli campi:

  

• Interfaccia classica

  • dialog ( cq:Dialog) nodes

    • definire la finestra di dialogo per la modifica del contenuto di questo componente

    • specifica per l’interfaccia classica

    • sono definiti utilizzando i widget ExtJS

    • hanno una proprietà xtype che fa riferimento a ExtJS

    • può disporre di una proprietà helpPath per definire la risorsa della guida sensibile al contesto (percorso assoluto o relativo) a cui si accede quando si seleziona il pulsante Help.

      • Per i componenti out-of-the-box questo fa spesso riferimento a una pagina nella documentazione.
      • Se non viene specificato helpPath, viene visualizzato l'URL predefinito (pagina di panoramica della documentazione).

  

  All’interno della finestra di dialogo, sono definiti i singoli campi:

  

  In una finestra di dialogo classica:

  • potete creare la finestra di dialogo come cq:Dialog, che fornirà una singola scheda, come nel componente di testo, o se avete bisogno di più schede, come con il componente di testo, la finestra di dialogo può essere definita come cq:TabPanel.
  • viene utilizzato un cq:WidgetCollection ( items) per fornire una base per i campi di input ( cq:Widget) o per ulteriori schede ( cq:Widget). Questa gerarchia può essere estesa.

Finestre di dialogo di progettazione

Le finestre di dialogo di progettazione sono molto simili alle finestre di dialogo utilizzate per modificare e configurare il contenuto, ma forniscono agli autori l’interfaccia per configurare e fornire i dettagli di progettazione per quel componente.

Le finestre di dialogo Progettazione sono disponibili in modalità Progettazione, anche se non sono necessarie per tutti i componenti, ad esempio ​​Titolo e ​​Immagini, entrambe dispongono di finestre di dialogo di progettazione, mentre ​​Testo non lo è.

La finestra di dialogo di progettazione per il sistema paragrafo (ad esempio parsys) è un caso speciale in quanto consente all’utente di selezionare altri componenti specifici (dal browser dei componenti o dalla barra laterale) sulla pagina.

Aggiunta del componente al sistema paragrafo

Una volta definito, il componente deve essere reso disponibile per l’uso. Per rendere un componente disponibile per l’uso in un sistema paragrafo, potete:

1. Aprite Modalità progettazione per una pagina e abilitate il componente richiesto.

2. Aggiungete i componenti richiesti alla proprietà components della definizione del modello in:

   /etc/designs/<*yourProject*>/jcr:content/<*yourTemplate*>/par

   Ad esempio, vedete:

   /etc/designs/geometrixx/jcr:content/contentpage/par

   

Componenti e contenuti creati

Se si crea e si configura un'istanza del componente Titolo sulla pagina: <content-path>/Prototype.html

• Interfaccia utente touch

  

• Interfaccia classica

  

Potete quindi visualizzare la struttura del contenuto creato all’interno della directory archivio:

In particolare, se si guarda il testo effettivo per un Titolo:

• la definizione (per entrambe le interfacce) ha la proprietà name= ./jcr:title

  • /libs/foundation/components/title/cq:dialog/content/items/column/items/title
  • /libs/foundation/components/title/dialog/items/title

• all'interno del contenuto, viene generata la proprietà jcr:title che contiene il contenuto dell'autore.

Le proprietà definite dipendono dalle singole definizioni. Anche se possono essere più complessi di quanto non lo siano in precedenza, seguono comunque gli stessi principi di base.

Gerarchia e ereditarietà dei componenti

I componenti all’interno di AEM sono soggetti a 3 gerarchie diverse:

• Gerarchia tipo di risorsa

  Viene utilizzato per estendere i componenti utilizzando la proprietà sling:resourceSuperType. Questo consente al componente di ereditare. Ad esempio, un componente di testo erediterà vari attributi dal componente standard.

  • script (risolti da Sling)
  • finestre di dialogo
  • descrizioni (comprese miniature, icone, ecc.)

• Gerarchia contenitore

  Viene utilizzato per compilare le impostazioni di configurazione per il componente secondario ed è utilizzato più comunemente in uno scenario parsys.

  Ad esempio, le impostazioni di configurazione per i pulsanti della barra di modifica, il layout del set di controlli (barre di modifica, rollover), il layout della finestra di dialogo (in linea, mobile) possono essere definiti sul componente principale e propagati ai componenti secondari.

  Le impostazioni di configurazione (relative alla funzionalità di modifica) in cq:editConfig e cq:childEditConfig vengono propagate.

• Includi gerarchia

  Questo viene imposto in fase di esecuzione dalla sequenza di include.

  Questa gerarchia è utilizzata da Designer, che a sua volta funge da base per vari aspetti di progettazione del rendering; incluse le informazioni sul layout, le informazioni css, i componenti disponibili in parsys tra gli altri.

Modifica comportamento

In questa sezione viene illustrato come configurare il comportamento di modifica di un componente. Sono inclusi 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à specifiche e nodi secondari. Sono disponibili le seguenti proprietà e nodi secondari:

• cq:editConfig proprietà nodo:

  • cq:actions ( String array): definisce le azioni che possono essere eseguite sul componente.

  • cq:layout ( String): : definisce la modalità di modifica del componente nell’interfaccia classica.

  • cq:dialogMode ( String): Definisce la modalità di apertura della finestra di dialogo del componente nell’interfaccia classica

    • Nell’interfaccia touch, le finestre di dialogo sono sempre mobili in modalità desktop e automaticamente aperte come schermo intero in dispositivi mobili.

  • cq:emptyText ( String): definisce il testo che viene visualizzato quando non è presente alcun contenuto visivo.

  • cq:inherit ( Boolean): definisce se i valori mancanti vengono ereditati dal componente da cui eredita.

  • dialogLayout (String): Definisce la modalità di apertura della finestra di dialogo.

• cq:editConfig nodi secondari:

  • cq:dropTargets (tipo di nodo nt:unstructured): Definisce un elenco di destinazioni di rilascio che possono accettare un rilascio da una risorsa di Content Finder

    • Più destinazioni di rilascio sono disponibili solo nell’interfaccia classica.
    • Nell’interfaccia touch è consentita una singola destinazione di rilascio.

  • cq:actionConfigs (tipo di nodo nt:unstructured): definisce un elenco di nuove azioni aggiunte all'elenco cq:actions.

  • cq:formParameters (tipo di nodo nt:unstructured): definisce parametri aggiuntivi aggiunti al modulo della finestra di dialogo.

  • cq:inplaceEditing (tipo di nodo cq:InplaceEditingConfig): definisce una configurazione di modifica locale per il componente.

  • cq:listeners (tipo di nodo cq:EditListenersConfig): definisce cosa accade prima o dopo un’azione sul componente.

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afteredit="REFRESH_PAGE"/>
</jcr:root>

Nella directory archivio sono presenti diverse configurazioni. È possibile cercare facilmente proprietà specifiche o nodi secondari:

• Per cercare una proprietà del nodo cq:editConfig, ad esempio cq:actions, è possibile utilizzare lo strumento Query in CRXDE Lite ed effettuare ricerche con la seguente stringa query XPath:

  //element(cq:editConfig, cq:EditConfig)[@cq:actions]

• Per cercare un nodo figlio di cq:editConfig, ad esempio è possibile cercare cq:dropTargets, che è di tipo cq:DropTargetConfig; è possibile utilizzare lo strumento Query in CRXDE Lite ed effettuare ricerche con la seguente stringa di query XPath:

  //element(cq:dropTargets, cq:DropTargetConfig)

Segnaposto componente

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

Per questo motivo, i componenti devono eseguire il rendering di un segnaposto purché non rendano alcun output visibile quando la pagina viene sottoposta a rendering nell'editor pagina (quando la modalità WCM è edit o preview).
La marcatura HTML tipica di un segnaposto è la seguente:

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

Lo script HTL tipico che esegue il rendering del codice HTML segnaposto riportato sopra è 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 è vera solo quando il componente non ha contenuto ed è invisibile all'autore.

Per evitare ripetizioni, 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 effettuato 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 può essere visualizzato nei componenti core, come nel componente titolo.

Configurazione con cq:EditConfig Properties

cq:azioni

La proprietà cq:actions ( String array) definisce una o più azioni che è possibile eseguire sul componente. I seguenti valori sono disponibili per la configurazione:

Valore proprietà	Descrizione
text:<some text>	Visualizza il valore di testo statico <alcuni testo> visibile solo nell'interfaccia classica. L’interfaccia touch non visualizza azioni in un menu contestuale, pertanto non è applicabile.
-	Aggiunge un distanziatore. Visibile solo nell’interfaccia classica. L’interfaccia touch non visualizza azioni in un menu contestuale, pertanto non è applicabile.
edit	Aggiunge un pulsante per modificare il componente.
editannotate	Aggiunge un pulsante per modificare il componente e consentire l'inserimento di annotazioni.
delete	Aggiunge un pulsante per eliminare il componente
insert	Aggiunge un pulsante per inserire un nuovo componente prima di quello corrente
copymove	Aggiunge un pulsante per copiare e tagliare il componente.

La configurazione seguente aggiunge un pulsante di modifica, un distanziatore, un pulsante di eliminazione e un pulsante di inserimento alla barra di modifica del componente:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit,-,delete,insert]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

Nella configurazione seguente viene aggiunto il testo "Configurazioni ereditate da Base Framework" alla barra di modifica del componente:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[text:Inherited Configurations from Base Framework]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

cq:layout (solo interfaccia classica)

La proprietà cq:layout ( String) definisce il modo in cui il componente può essere modificato nell'interfaccia classica. Sono disponibili i seguenti valori:

Valore proprietà	Descrizione
rollover	Valore predefinito. L’edizione del componente è accessibile "al passaggio del mouse" tramite clic e/o menu di scelta rapida. Per un uso avanzato, tenere presente che l'oggetto lato client corrispondente è: CQ.wcm.EditRollover.
editbar	L’edizione del componente è accessibile tramite una barra degli strumenti. Per un uso avanzato, tenere presente che l'oggetto lato client corrispondente è: CQ.wcm.EditBar.
auto	La scelta viene lasciata al codice lato client.

La configurazione seguente aggiunge un pulsante di modifica alla barra di modifica del componente:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq:dialogMode (solo interfaccia classica)

Il componente può essere collegato a una finestra di dialogo di modifica. La proprietà cq:dialogMode ( String) definisce il modo in cui la finestra di dialogo del componente verrà aperta nell'interfaccia classica. Sono disponibili i seguenti valori:

Valore proprietà	Descrizione
floating	Finestra di dialogo mobile.
inline	(valore predefinito). La finestra di dialogo è ancorata sul componente.
auto	Se la larghezza del componente è inferiore al valore CQ.themes.wcm.EditBase.INLINE_MINIMUM_WIDTH lato client, la finestra di dialogo è mobile, altrimenti è in linea.

La configurazione seguente definisce una barra di modifica con un pulsante di modifica e una finestra di dialogo mobile:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq:emptyText

La proprietà cq:emptyText ( String) definisce il testo visualizzato quando non è presente alcun contenuto visivo. Per impostazione predefinita: Drag components or assets here.

cq:inherit

La proprietà cq:inherit ( boolean) definisce se i valori mancanti vengono ereditati dal componente da cui eredita. Il valore predefinito è false.

dialogLayout

La proprietà dialogLayout definisce come aprire una finestra di dialogo per impostazione predefinita.

• Un valore di fullscreen apre la finestra di dialogo a schermo intero.
• Per impostazione predefinita, un valore vuoto o l’assenza della proprietà determina l’apertura normale della finestra di dialogo.
• L’utente può sempre attivare o disattivare la modalità a schermo intero all’interno della finestra di dialogo.
• Non si applica all’interfaccia classica.

Configurazione con cq:EditConfig Child Nodes

cq:dropTargets

Il nodo cq:dropTargets (tipo di nodo nt:unstructured) definisce un elenco di destinazioni di rilascio che possono accettare un rilascio da una risorsa trascinata da Content Finder. Funge da raccolta di nodi di tipo cq:DropTargetConfig.

Ogni nodo secondario di tipo cq:DropTargetConfig definisce una destinazione di rilascio nel componente. Il nome del nodo è importante perché deve essere utilizzato nella JSP, come segue, per generare il nome della classe CSS assegnato all'elemento DOM che è la destinazione di rilascio effettiva:

<drop target css class> = <drag and drop prefix> + 
 <node name of the drop target in the edit configuration>

La <*drag and drop prefix*> è definita dalla proprietà Java:

com.day.cq.wcm.api.components.DropTarget.CSS_CLASS_PREFIX.

Ad esempio, il nome della classe è definito come segue nella JSP del componente Download
( /libs/foundation/components/download/download.jsp), dove file è il nome del nodo della destinazione di rilascio nella configurazione di modifica del componente Download:

String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";

Il nodo di tipo cq:DropTargetConfig deve avere le seguenti proprietà:

Nome proprietà	Valore proprietà
accept	Regex applicato al tipo di mime della risorsa per verificare se è consentito il rilascio.
groups	Array di gruppi di destinazione di rilascio. Ogni gruppo deve corrispondere al tipo di gruppo definito nell’estensione di Content Finder e associato alle risorse.
propertyName	Nome della proprietà che verrà aggiornata dopo un rilascio valido.

La configurazione seguente è tratta dal componente Download. Consente di rilasciare qualsiasi risorsa (il tipo mime può essere una qualsiasi stringa) dal gruppo media da Content Finder nel componente. Dopo il rilascio, la proprietà del componente fileReference viene aggiornata:

    <cq:dropTargets jcr:primaryType="nt:unstructured">
        <file
            jcr:primaryType="cq:DropTargetConfig"
            accept="[.*]"
            groups="[media]"
            propertyName="./fileReference"/>
    </cq:dropTargets>

cq:actionConfigs (solo interfaccia classica)

Il nodo cq:actionConfigs (tipo di nodo nt:unstructured) definisce un elenco di nuove azioni aggiunte all'elenco definito dalla proprietà cq:actions. Ogni nodo secondario di cq:actionConfigs definisce una nuova azione definendo un widget.

La seguente configurazione di esempio definisce un nuovo pulsante (con un separatore per l’interfaccia classica):

• un separatore, definito dal tipo xtype tbseparator;

  • Questa opzione è utilizzata solo dall’interfaccia classica.
  • Questa definizione viene ignorata dall’interfaccia touch in quanto i xtype vengono ignorati (e i separatori non sono necessari in quanto la barra degli strumenti delle azioni è costruita in modo diverso nell’interfaccia touch).

• un pulsante denominato Gestisci commenti che esegue la funzione del gestore CQ_collab_forum_openCollabAdmin().

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
    cq:actions="[EDIT,COPYMOVE,DELETE,INSERT]"
    jcr:primaryType="cq:EditConfig">
    <cq:actionConfigs jcr:primaryType="nt:unstructured">
        <separator0
            jcr:primaryType="nt:unstructured"
            xtype="tbseparator"/>
        <manage
            jcr:primaryType="nt:unstructured"
            handler="function(){CQ_collab_forum_openCollabAdmin();}"
            text="Manage comments"/>
    </cq:actionConfigs>
</jcr:root>

cq:formParameters

Il nodo cq:formParameters (tipo di nodo nt:unstructured) definisce parametri aggiuntivi che vengono aggiunti al modulo della finestra di dialogo. Ogni proprietà viene mappata su un parametro modulo.

La seguente configurazione aggiunge al modulo della finestra di dialogo un parametro denominato name, impostato con il valore photos/primary:

    <cq:formParameters
        jcr:primaryType="nt:unstructured"
        name="photos/primary"/>

cq:inplaceEditing

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

Nome proprietà	Valore proprietà
active	(boolean) True per abilitare la modifica locale del componente.
configPath	(String) Percorso della configurazione dell'editor. La configurazione può essere specificata da un nodo di configurazione.
editorType	(String) Tipo di editor. I tipi disponibili sono: testo normale: da utilizzare per contenuti non HTML. title: è un editor di testo in testo normale avanzato che converte i titoli grafici in testo in testo normale prima dell’inizio della modifica. Utilizzato dal componente titolo Geometrixx. text: da utilizzare per il contenuto HTML (utilizza l'Editor Rich Text).

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

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

cq:listener

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

Nome proprietà	Valore proprietà	Valore predefinito (Solo interfaccia classica)
beforedelete	Il gestore viene attivato prima della rimozione del componente.
beforeedit	Il gestore viene attivato prima della modifica del componente.
beforecopy	Il gestore viene attivato prima della copia del componente.
beforemove	Il gestore viene attivato prima dello spostamento del componente.
beforeinsert	Il gestore viene attivato prima dell'inserimento del componente. Solo per l’interfaccia touch.
beforechildinsert	Il gestore viene attivato prima che il componente venga inserito in un altro componente (solo contenitori).
afterdelete	Il gestore viene attivato dopo la rimozione del componente.	REFRESH_SELF
afteredit	Il gestore viene attivato dopo la modifica del componente.	REFRESH_SELF
aftercopy	Il gestore viene attivato dopo la copia del componente.	REFRESH_SELF
afterinsert	Il gestore viene attivato dopo l'inserimento del componente.	REFRESH_INSERTED
aftermove	Il gestore viene attivato dopo lo spostamento del componente.	REFRESH_SELFMOVED
afterchildinsert	Il gestore viene attivato dopo che il componente è stato inserito in un altro componente (solo contenitori).

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 alla configurazione REFRESH_INSERTED:

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