Tag di decorazione

Quando viene eseguito il rendering di un componente in una pagina web, è possibile generare un elemento HTML che racchiude all’interno il componente renderizzato. Questo serve principalmente a due scopi:

• Un componente può essere modificato solo quando è racchiuso in un elemento HTML.
• L’elemento wrapping viene utilizzato per applicare classi HTML che forniscono:
  • Informazioni layout
  • Informazioni sullo stile

AEM offre agli sviluppatori una logica chiara e semplice che controlla i tag di decorazione che racchiudono i componenti. Se e come viene eseguito il rendering del tag di decorazione è definito dalla combinazione di due fattori, in cui questa pagina si immergerà:

• Il componente stesso può configurare il proprio tag di decorazione con un set di proprietà.
• Gli script che includono i componenti possono definire gli aspetti del tag di decorazione con parametri di inclusione.

Consigli

Di seguito sono riportati alcuni consigli generali su quando includere l’elemento wrapper per evitare problemi imprevisti:

• La presenza dell’elemento wrapper non deve differire tra i diversi metodi WCMM (modalità di modifica o anteprima), le istanze (di authoring o pubblicazione) o l’ambiente (di staging o produzione), in modo che i CSS e i JavaScript della pagina funzionino in modo identico in tutti i casi.
• L’elemento wrapper deve essere aggiunto a tutti i componenti modificabili, in modo che l’editor pagina possa inizializzarli e aggiornarli correttamente.
• Per i componenti non modificabili, l'elemento wrapper può essere evitato se non svolge alcuna funzione particolare, in modo che il markup risultante non risulti eccessivamente esteso.

Controlli dei componenti

Per controllare il comportamento del tag di decorazione, è possibile applicare ai componenti le proprietà e i nodi seguenti:

• cq:noDecoration {boolean}: Questa proprietà può essere aggiunta a un componente e un valore true impedisce all'AEM di generare elementi wrapper sul componente.
• cq:htmlTagnodo : Questo nodo può essere aggiunto sotto un componente e può avere le seguenti proprietà:
  • cq:tagName {String}: Questa può essere utilizzata per specificare un tag HTML personalizzato da utilizzare per il wrapping dei componenti invece dell’elemento DIV predefinito.
  • class {String}: Può essere utilizzato per specificare i nomi delle classi CSS da aggiungere al wrapper.
  • Altri nomi di proprietà vengono aggiunti come attributi HTML con lo stesso valore String fornito.

Controlli script

In generale, il comportamento del wrapper in HTL può essere riassunto come segue:

• Per impostazione predefinita, non viene eseguito il rendering di alcun DIV wrapper (quando si esegue data-sly-resource="foo").
• Tutte le modalità wcm (disabilitate, anteprima, modifica sia per l’authoring che per la pubblicazione) eseguono il rendering in modo identico.

Il comportamento dell'involucro può anche essere completamente controllato.

• Lo script HTL ha il controllo completo sul comportamento risultante del tag wrapper.
• Proprietà dei componenti (come cq:noDecoration e cq:tagName) può anche definire il tag wrapper.

È possibile controllare completamente il comportamento dei tag wrapper dagli script HTL e dalla relativa logica associata.

Per ulteriori informazioni sullo sviluppo in HTL, vedi Documentazione di HTL.

Albero decisionale

Questo albero decisionale riepiloga la logica che determina il comportamento dei tag wrapper.

Casi d’uso

I tre casi d’uso seguenti forniscono esempi di gestione dei tag wrapper e illustrano quanto sia semplice controllare il comportamento desiderato dei tag wrapper.

Tutti gli esempi seguenti presuppongono la seguente struttura di contenuto e i seguenti componenti:

/content/test/
  @resourceType = "test/components/one"
  child/
    @resourceType = "test/components/two"

/apps/test/components/
  one/
    one.html
  two/
    two.html
    cq:htmlTag/
      @cq:tagName = "article"
      @class = "component-two"

Caso d'uso 1: inclusione di un componente per il riutilizzo del codice

Il caso d’uso più tipico è quando un componente include un altro componente per motivi di riutilizzo del codice. In tal caso, non si desidera che il componente incluso sia modificabile con la propria barra degli strumenti e la propria finestra di dialogo, pertanto non è necessario alcun wrapper, e il cq:htmlTag viene ignorato. Questo può essere considerato il comportamento predefinito.

one.html: <sly data-sly-resource="child"></sly>

two.html: Hello World!

Output risultante su /content/test.html:

Hello World!

Un esempio può essere un componente che include un componente immagine principale per visualizzare un’immagine, in genere utilizzando una risorsa sintetica che consiste nell’includere un componente secondario virtuale passando a data-sly-resource un oggetto Map che rappresenta tutte le proprietà del componente.

Caso d'uso 2: inclusione di un componente modificabile

Un altro caso d’uso comune si verifica quando i componenti contenitore includono componenti figlio modificabili, come un Contenitore di layout. In questo caso, per il funzionamento dell’editor ogni elemento secondario incluso necessita imperativamente di un wrapper (a meno che non sia esplicitamente disabilitato con cq:noDecoration proprietà ).

Poiché il componente incluso è in questo caso un componente indipendente, è necessario un elemento wrapper per il funzionamento dell’editor e per definirne il layout e lo stile da applicare. Per attivare questo comportamento, è necessario decoration=true opzione.

one.html: <sly data-sly-resource="${'child' @ decoration=true}"></sly>

two.html: Hello World!

Output risultante su /content/test.html:

<article class="component-two">Hello World!</article>

Caso d’uso 3: comportamento personalizzato

Ci può essere un numero qualsiasi di casi complessi, che possono essere facilmente raggiunti dalla possibilità che HTL fornisca esplicitamente:

• decorationTagName='ELEMENT_NAME' Per definire il nome elemento del wrapper.
• cssClassName='CLASS_NAME' Per definire i nomi delle classi CSS da impostare su di esso.

one.html: <sly data-sly-resource="${'child' @ decorationTagName='aside', cssClassName='child'}"></sly>

two.html: Hello World!

Output risultante /content/test.html:

<aside class="child">Hello World!</aside>