Componenti AEM - Nozioni di base

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

Questo processo comporta 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 passato a una nuova interfaccia utente standard, moderna e touch, continua a supportare l’interfaccia classica.

Panoramica

Questa sezione descrive i concetti e i problemi chiave come introduzione ai dettagli necessari allo sviluppo dei tuoi componenti.

Pianificazione

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

• Cosa devi fare esattamente con 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 è possibile ereditare le nozioni di base da un componente esistente?

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

• Il componente richiederà una logica per selezionare/manipolare il contenuto?

  • La logica deve essere mantenuta separata dal livello dell’interfaccia utente. HTL è progettato per garantire che ciò accada.

• Il componente avrà bisogno della formattazione CSS?

  • La formattazione CSS deve essere mantenuta separata dalle definizioni dei componenti. Definisci 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, consulta Lista di controllo sicurezza - Best practice per lo sviluppo .

Interfaccia touch e classica

Prima di iniziare una discussione seria sullo sviluppo di componenti è necessario sapere quale interfaccia utente utilizzeranno gli autori:

• Interfaccia utente touch
  Interfaccia utente standard introdotta in AEM 5.6.0 come anteprima ed estesa in 6.x. Si basa sull’esperienza utente unificata di Adobe Marketing Cloud, utilizzando le tecnologie di base di Coral UIe Granite UI.

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

Per ulteriori informazioni, consulta Interfaccia utente Recommendations per i clienti .

I componenti possono essere implementati per supportare l’interfaccia touch, l’interfaccia classica o entrambe. Quando osservi un’istanza standard, vengono anche visualizzati i componenti predefiniti originariamente progettati per l’interfaccia classica, l’interfaccia touch o entrambi.

Per questo motivo descriveremo le nozioni di base di entrambi e come riconoscerli in questa pagina.

Logica dei contenuti e marcatura di rendering

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

Questa filosofia è supportata da HTL, un linguaggio di template appositamente limitato per garantire un linguaggio di programmazione reale viene 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 determinata visualizzazione e, se necessario, consente una logica specifica per diverse visualizzazioni dello stesso componente.

HTL vs JSP

HTL è un linguaggio per modelli HTML introdotto con AEM 6.0.

La discussione sull'utilizzo di HTL o JSP (Java Server Pages) quando si sviluppano 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 si può presumere che HTL sia solo per l’interfaccia touch e JSP per l’interfaccia classica, si tratta di un’errata concezione e più a causa dei tempi. L’interfaccia touch e HTL sono stati incorporati in AEM per circa lo stesso periodo. Poiché HTL è ora la lingua consigliata, viene utilizzato per i nuovi componenti, che tendono a essere per l’interfaccia touch.

Sviluppo di componenti personalizzati

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 i propri componenti e aggiungerli al sistema paragrafo, consulta:

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

Spostamento dei componenti nell’istanza di pubblicazione

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

Utilizza i seguenti strumenti per spostare i componenti nell’istanza di pubblicazione:

• Utilizza Package Manager per aggiungere i componenti a un pacchetto e spostarli in un'altra istanza AEM.
• Utilizza lo strumento di replica Attiva albero per replicare i componenti.

Componenti di cui tenere conto dall'inizio

• 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 che contiene il contenuto del 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 paragrafo.
  • È inoltre possibile selezionare i componenti disponibili per l’uso all’interno di 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 principali considerazioni sono:

• Tipo risorsa
• Definizione del componente
• Proprietà e nodi secondari di un componente
• Finestre di dialogo
• Finestre di dialogo di progettazione
• Disponibilità dei componenti
• 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 l'aspetto cambiano nel tempo, l'intenzione rimanga nel tempo.

Definizione del componente

Nozioni di base sui componenti

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

• I componenti AEM sono basati su Sling.

• I componenti AEM 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à di jcr; queste sono variabili e alcune possono essere facoltative anche se la struttura di base di un nodo componente, le sue proprietà e i suoi sottonodi sono definiti dalla definizione cq:Component

  • Riferimenti:

    Definiscono gli elementi statici utilizzati dal componente.

  • Script:

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

• Nodo principale:

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

• Proprietà vitali:

  • jcr:title - Titolo del 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 passaggio del mouse nel browser componenti o nella barra laterale.

  • Interfaccia classica:

    • icon.png - Icona per questo componente.
    • thumbnail.png - Immagine mostrata se questo componente è elencato all’interno del sistema paragrafo.

  • Interfaccia utente touch

    • Per ulteriori informazioni, consulta la sezione Icona componente nell’interfaccia touch .

• Nodi figlio fondamentali:

  • cq:editConfig (cq:EditConfig) - Definisce le proprietà di modifica del componente e consente al componente di essere visualizzato 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 i propri 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 modificare il contenuto.
    • cq:design_dialog ( nt:unstructured) - Modifica di 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 modificare il contenuto.
    • design_dialog ( cq:Dialog) - Modifica di progettazione per questo componente.

Icona del 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. Queste 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 componenti

   • Utilizza il valore dell’attributo HTML dell’icona Coral.

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

   • L'abbreviazione deve essere limitata a due caratteri.

   • Specificando una stringa vuota si otterrà l'abbreviazione dei 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 ha una proprietà abbreviation_commentI18n , che viene quindi utilizzata come suggerimento 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.

     • Verranno ridimensionate le icone più grandi (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 escape come _cq_icon.png o _cq_icon.svg.

   • .png ha un precedente .svg se sono presenti entrambi

Se sul componente non è presente 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 trovato nulla o un'abbreviazione vuota, il sistema costruirà l'abbreviazione dalle prime lettere della proprietà jcr:title del componente corrente.

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

La console Componenti mostra come è 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, con differenze che rimangono indipendenti in modo che il componente possa funzionare in entrambi gli ambienti.

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

Se osserviamo il componente Testo (una delle due versioni), possiamo vedere questi 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, viene visualizzato nell’elenco dei componenti all’interno del browser Componenti o della barra laterale

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

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

I nodi figlio di particolare interesse includono:

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

• cq:childEditConfig ( cq:EditConfig) : controlla gli aspetti visivi dei componenti secondari che non hanno le proprie definizioni

• 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 dell’interfaccia classica)
  • design_dialog ( cq:Dialog) - specifica le opzioni di modifica della progettazione per questo componente
  • icon.png - file grafico da usare come icona per il componente nella barra laterale
  • thumbnail.png - file grafico da usare come miniatura del componente durante il trascinamento 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, potrebbe essere necessaria una o più schede per mantenere breve la finestra di dialogo e ordinare i campi di input.

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

• 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 i componenti dell’interfaccia 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 l'icona della Guida (l'icona ?) (icona).

      • Per i componenti predefiniti, questo fa spesso riferimento a una pagina nella documentazione.
      • Se non viene specificato alcun URL helpPath, viene visualizzato l’URL predefinito (pagina di panoramica della documentazione).

  

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

  

• Interfaccia classica

  • dialog ( cq:Dialog) nodes

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

    • specifiche dell’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 predefiniti, questo fa spesso riferimento a una pagina nella documentazione.
      • Se non viene specificato alcun URL helpPath, viene visualizzato l’URL predefinito (pagina di panoramica della documentazione).

  

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

  

  In una finestra di dialogo classica:

  • puoi creare la finestra di dialogo come cq:Dialog, che fornisce una singola scheda, come nel componente di testo, o se ti servono più schede, come nel 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 altre 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 i contenuti, ma forniscono agli autori l’interfaccia per configurare e fornire dettagli di progettazione per quel componente.

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

La finestra di dialogo Progettazione per il sistema paragrafo (ad esempio, parsys) è un caso particolare in quanto consente all’utente di selezionare altri componenti specifici (dal browser Componenti o dalla barra laterale) nella pagina.

Aggiunta del componente al sistema paragrafo

Una volta definito un componente, questo deve essere reso disponibile per l’uso. Per rendere un componente disponibile per l’uso in un sistema paragrafo, potete effettuare le seguenti operazioni:

1. Apri Modalità progettazione per una pagina e abilita il componente richiesto.

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

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

   Ad esempio, vedi:

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

   

Componenti e contenuti creati

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

• Interfaccia utente touch

  

• Interfaccia classica

  

A questo punto è possibile vedere la struttura del contenuto creato all’interno dell’archivio:

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

• la definizione (per entrambe le interfacce) presenta 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 contenente il contenuto dell’autore.

Le proprietà definite dipendono dalle singole definizioni. Anche se possono essere più complessi di quanto sopra, 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 dei tipi di risorsa

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

  • script (risolti da Sling)
  • finestre di dialogo
  • descrizioni (incluse immagini in miniatura, icone, ecc.)

• Gerarchia dei contenitori

  Viene utilizzato per popolare le impostazioni di configurazione per il componente figlio 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 controllo (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 runtime dalla sequenza di "include".

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

Modifica comportamento

Questa sezione spiega come configurare il comportamento di modifica di un componente. Ciò include 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 viene 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 figlio:

• 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 le modalità di apertura della finestra di dialogo dei componenti nell’interfaccia classica

    • Nell’interfaccia touch, le finestre di dialogo sono sempre mobili in modalità desktop e vengono 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 (Stringa): definisce come deve essere aperta la 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

    • Le destinazioni di rilascio multiple 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 che vengono aggiunte all’elenco cq:actions .

  • cq:formParameters (tipo di nodo nt:unstructured): definisce parametri aggiuntivi aggiunti al modulo 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>

Nell’archivio sono presenti molte configurazioni esistenti. È possibile cercare facilmente proprietà specifiche o nodi secondari:

• Per cercare una proprietà del nodo cq:editConfig, ad esempio cq:actions, puoi utilizzare lo strumento Query in CRXDE Lite e cercare con la seguente stringa di 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; puoi utilizzare lo strumento Query in ​ CRXDE Lite e cercare con la seguente stringa di query XPath:

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

Segnaposto Componente

I componenti devono sempre eseguire il rendering di contenuti HTML visibili all’autore, anche quando il componente non dispone di contenuti. 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 eseguano il rendering di alcun output visibile quando la pagina viene sottoposta a rendering nell’editor di pagine (quando la modalità WCM è edit o preview).
Il markup HTML tipico per un segnaposto è il seguente:

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

Lo script HTL tipico che esegue il rendering del segnaposto HTML di cui 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 è true solo quando il componente non ha contenuto ed è invisibile all’autore.

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

L’utilizzo del modello nel collegamento precedente viene quindi fatto 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:actions

La proprietà cq:actions ( String array) definisce una o più azioni che possono essere eseguite sul componente. Per la configurazione sono disponibili i seguenti valori:

Nella configurazione seguente vengono aggiunti 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 dal framework di base" 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 come modificare il componente nell’interfaccia classica. Sono disponibili i seguenti valori:

Nella configurazione seguente viene aggiunto 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 come verrà aperta la finestra di dialogo del componente nell’interfaccia classica. Sono disponibili i seguenti valori:

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.

• Il valore fullscreen apre la finestra di dialogo a schermo intero.
• Per impostazione predefinita, un valore vuoto o l’assenza della proprietà aprono normalmente la finestra di dialogo.
• L’utente può sempre attivare la modalità a tutto schermo 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 figlio di tipo cq:DropTargetConfig definisce una destinazione di rilascio nel componente. Il nome del nodo è importante perché deve essere utilizzato nel JSP, come segue, per generare il nome della classe CSS assegnato all'elemento DOM che è il target di rilascio effettivo:

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

Il <*drag and drop prefix*> è definito dalla proprietà Java:

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

Ad esempio, il nome della classe è definito come segue nel 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à:

La seguente configurazione viene presa dal componente Scarica . Consente di rilasciare qualsiasi risorsa (il tipo mime può essere una qualsiasi stringa) dal gruppo media dal Content Finder al 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 figlio 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;

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

• un pulsante denominato Gestisci commenti che esegue la funzione di gestione 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 di dialogo. Ogni proprietà viene mappata su un parametro di modulo.

Nella configurazione seguente viene aggiunto al modulo 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à:

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.

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

afteredit = "project.customerAction"

L'esempio seguente equivale 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"/>