Istruzioni di blocco HTL

Le istruzioni di blocco HTML Template Language (HTL) sono attributi data personalizzati aggiunti direttamente all'HTML esistente. Questo consente di inserire facilmente un'annotazione discreta di un prototipo di pagina HTML statica, convertendola in un modello dinamico funzionante senza interrompere la validità del codice HTML.

Panoramica del blocco

I plug-in per blocchi HTL sono definiti dagli attributi data-sly-* impostati sugli elementi HTML. Gli elementi possono avere un tag di chiusura o chiudersi autonomamente. Gli attributi possono avere valori (che possono essere stringhe statiche o espressioni), oppure essere semplicemente attributi booleani (senza un valore).

<tag data-sly-BLOCK></tag>                                 <!--/* A block is simply consists in a data-sly attribute set on an element. */-->
<tag data-sly-BLOCK/>                                      <!--/* Empty elements (without a closing tag) should have the trailing slash. */-->
<tag data-sly-BLOCK="string value"/>                       <!--/* A block statement usually has a value passed, but not necessarily. */-->
<tag data-sly-BLOCK="${expression}"/>                      <!--/* The passed value can be an expression as well. */-->
<tag data-sly-BLOCK="${@ myArg='foo'}"/>                   <!--/* Or a parametric expression with arguments. */-->
<tag data-sly-BLOCKONE="value" data-sly-BLOCKTWO="value"/> <!--/* Several block statements can be set on a same element. */-->

Tutti gli attributi data-sly-* valutati vengono rimossi dalla marcatura generata.

Identificatori

Un'istruzione block può anche essere seguita da un identificatore:

<tag data-sly-BLOCK.IDENTIFIER="value"></tag>

L'identificatore può essere utilizzato dall'istruzione block in vari modi. Di seguito sono riportati alcuni esempi:

<!--/* Example of statements that use the identifier to set a variable with their result: */-->
<div data-sly-use.navigation="MyNavigation">${navigation.title}</div>
<div data-sly-test.isEditMode="${wcmmode.edit}">${isEditMode}</div>
<div data-sly-list.child="${currentPage.listChildren}">${child.properties.jcr:title}</div>
<div data-sly-template.nav>Hello World</div>

<!--/* The attribute statement uses the identifier to know to which attribute it should apply it's value: */-->
<div data-sly-attribute.title="${properties.jcr:title}"></div> <!--/* This will create a title attribute */-->

Gli identificatori di primo livello non fanno distinzione tra maiuscole e minuscole (perché possono essere impostati tramite attributi HTML che non fanno distinzione tra maiuscole e minuscole), ma tutte le relative proprietà sono sensibili alla distinzione tra maiuscole e minuscole.

Istruzioni blocco disponibili

Sono disponibili diverse istruzioni di blocco. Quando viene utilizzato sullo stesso elemento, il seguente elenco di priorità definisce il modo in cui vengono valutate le istruzioni di blocco:

  1. data-sly-template
  2. data-sly-set, data-sly-test, data-sly-use
  3. data-sly-call
  4. data-sly-text
  5. data-sly-element, data-sly-include, data-sly-resource
  6. data-sly-unwrap
  7. data-sly-list, data-sly-repeat
  8. data-sly-attribute

Quando due istruzioni di blocco hanno la stessa priorità, l'ordine di valutazione è da sinistra a destra.

use

data-sly-use inizializza un oggetto helper (definito in JavaScript o Java) ed lo espone attraverso una variabile.

Inizializzare un oggetto JavaScript, dove il file di origine si trova nella stessa directory del modello. Il nome file deve essere utilizzato:

<div data-sly-use.nav="navigation.js">${nav.foo}</div>

Inizializzare una classe Java, in cui il file di origine si trova nella stessa directory del modello. È necessario utilizzare il nome della classe, non il nome del file:

<div data-sly-use.nav="Navigation">${nav.foo}</div>

Inizializzare una classe Java, in cui tale classe viene installata come parte di un bundle OSGi. È necessario utilizzare il nome completo della classe:

<div data-sly-use.nav="org.example.Navigation">${nav.foo}</div>

I parametri possono essere passati all'inizializzazione utilizzando le opzioni. In genere questa funzione deve essere utilizzata solo dal codice HTL che si trova all'interno di un blocco data-sly-template:

<div data-sly-use.nav="${'navigation.js' @parentPage=currentPage}">${nav.foo}</div>

Inizializzare un altro modello HTL che può essere chiamato utilizzando data-sly-call:

<div data-sly-use.nav="navTemplate.html" data-sly-call="${nav.foo}"></div>
NOTA

Per ulteriori informazioni sull'API Use-API, vedi:

utilizzo semplice dei dati con risorse

Questo consente di ottenere risorse direttamente in HTL con data-sly-use e non richiede la scrittura del codice per ottenerlo.

Esempio:

<div data-sly-use.product=“/etc/commerce/product/12345”>
  ${ product.title }
</div>
SUGGERIMENTO

Vedere anche la sezione Percorso non sempre obbligatorio.

estrarre

data-sly-unwrap rimuove l'elemento host dalla marcatura generata mantenendo il contenuto. Questo consente di escludere gli elementi che sono richiesti come parte della logica di presentazione HTL ma che non sono desiderati nell'output effettivo.

Tuttavia, tale affermazione dovrebbe essere utilizzata con cautela. In generale è meglio mantenere la marcatura HTL il più vicino possibile alla marcatura di output prevista. In altre parole, quando si aggiungono istruzioni blocco HTL, provare il più possibile ad aggiungere semplicemente annotazioni all'HTML esistente, senza introdurre nuovi elementi.

Ad esempio, questo

<p data-sly-use.nav="navigation.js">Hello World</p>

produrrà

<p>Hello World</p>

considerando che,

<p data-sly-use.nav="navigation.js" data-sly-unwrap>Hello World</p>

produrrà

Hello World

È inoltre possibile estrarre un elemento in modo condizionale:

<div class="popup" data-sly-unwrap="${isPopup}">content</div>

imposta

data-sly-set definisce un nuovo identificatore con un valore predefinito.

<span data-sly-set.profile="${user.profile}">Hello, ${profile.firstName} ${profile.lastName}!</span>
<a class="profile-link" href="${profile.url}">Edit your profile</a>

Testo

data-sly-text sostituisce il contenuto del relativo elemento host con il testo specificato.

Ad esempio, questo

<p>${properties.jcr:description}</p>

equivale a

<p data-sly-text="${properties.jcr:description}">Lorem ipsum</p>

Entrambi visualizzeranno il valore di jcr:description come testo di paragrafo. Il vantaggio del secondo metodo è che consente l'annotazione non intrusiva di HTML mantenendo il contenuto segnaposto statico nella finestra di progettazione originale.

attribute

data-sly-attribute aggiunge attributi all'elemento host.

Ad esempio, questo

<div title="${properties.jcr:title}"></div>

equivale a

<div title="Lorem Ipsum" data-sly-attribute.title="${properties.jcr:title}"></div>

Entrambi imposteranno l'attributo title sul valore di jcr:title. Il vantaggio del secondo metodo è che consente l'annotazione non intrusiva di HTML mantenendo il contenuto segnaposto statico nella finestra di progettazione originale.

Gli attributi vengono risolti da sinistra a destra, con l'istanza più a destra di un attributo (letterale o definito tramite data-sly-attribute) che ha la precedenza su qualsiasi istanza dello stesso attributo (definito letteralmente o tramite data-sly-attribute) definita a sinistra.

Tenere presente che un attributo (literal o impostato tramite data-sly-attribute) il cui valore restituisce una stringa vuota verrà rimosso nella marcatura finale. L'unica eccezione a questa regola è che verrà mantenuto un attributo letterale impostato su una stringa vuota letterale. Esempio,

<div class="${''}" data-sly-attribute.id="${''}"></div>

produce,

<div></div>

ma,

<div class="" data-sly-attribute.id=""></div>

produce,

<div class=""></div>

Per impostare più attributi, passare un oggetto mappa contenente coppie chiave-valore corrispondenti agli attributi e ai relativi valori. Ad esempio, supponendo che

attrMap = {
    title: "myTitle",
    class: "myClass",
    id: "myId"
}

Allora,

<div data-sly-attribute="${attrMap}"></div>

produce,

<div title="myTitle" class="myClass" id="myId"></div>

elemento

data-sly-element sostituisce il nome dell'elemento dell'elemento host.

Esempio,

<h1 data-sly-element="${titleLevel}">text</h1>

Sostituisce l'elemento h1 con il valore di titleLevel.

Per motivi di sicurezza, data-sly-element accetta solo i seguenti nomi di elementi:

a abbr address article aside b bdi bdo blockquote br caption cite code col colgroup
data dd del dfn div dl dt em figcaption figure footer h1 h2 h3 h4 h5 h6 header i ins
kbd li main mark nav ol p pre q rp rt ruby s samp section small span strong sub
sup table tbody td tfoot th thead time tr u var wbr

Per impostare altri elementi, la protezione XSS deve essere disattivata ( @context='unsafe').

test

data-sly-test rimuove in modo condizionale l'elemento host ed è contenuto. Un valore di false rimuove l'elemento; un valore di true mantiene l'elemento.

Ad esempio, l'elemento p e il relativo contenuto saranno sottoposti a rendering solo se isShown è true:

<p data-sly-test="${isShown}">text</p>

Il risultato di un test può essere assegnato a una variabile che può essere utilizzata successivamente. Questa funzione è in genere utilizzata per costruire la logica "if else", in quanto non esiste un'istruzione else esplicita:

<p data-sly-test.abc="${a || b || c}">is true</p>
<p data-sly-test="${!abc}">or not</p>

Una volta impostata, la variabile ha ambito globale all’interno del file HTL.

Di seguito sono riportati alcuni esempi di confronto di valori:

<div data-sly-test="${properties.jcr:title == 'test'}">TEST</div>
<div data-sly-test="${properties.jcr:title != 'test'}">NOT TEST</div>

<div data-sly-test="${properties['jcr:title'].length > 3}">Title is longer than 3</div>
<div data-sly-test="${properties['jcr:title'].length >= 0}">Title is longer or equal to zero </div>

<div data-sly-test="${properties['jcr:title'].length > aemComponent.MAX_LENGTH}">
    Title is longer than the limit of ${aemComponent.MAX_LENGTH}
</div>

ripetizione

Con data-sly-repeat è possibile ripetere un elemento più volte in base all'elenco specificato.

<div data-sly-repeat="${currentPage.listChildren}">${item.name}</div>

Funziona allo stesso modo di data-sly-list, ma non è necessario un elemento contenitore.

L'esempio seguente mostra che è anche possibile fare riferimento a item per gli attributi:

<div data-sly-repeat="${currentPage.listChildren}" data-sly-attribute.class="${item.name}">${item.name}</div>

elenco

data-sly-list ripete il contenuto dell'elemento host per ogni proprietà enumerabile nell'oggetto fornito.

Di seguito è riportato un ciclo semplice:

<dl data-sly-list="${currentPage.listChildren}">
    <dt>index: ${itemList.index}</dt>
    <dd>value: ${item.title}</dd>
</dl>

Nell'ambito dell'elenco sono disponibili le seguenti variabili predefinite:

  • item: L'elemento corrente nell'iterazione.
  • itemList: Oggetto con le seguenti proprietà:
  • index: contatore basato su zero ( 0..length-1).
  • count: un contatore ( 1..length).
  • first: true se l'elemento corrente è il primo elemento.
  • middle: true se l'elemento corrente non è né il primo né l'ultimo elemento.
  • last: true se l'elemento corrente è l'ultimo elemento.
  • odd: true se index è strano.
  • even: true se index è pari.

La definizione di un identificatore nell'istruzione data-sly-list consente di rinominare le variabili itemList e item. item diventerà <variable> e itemList diventerà <variable>List.

<dl data-sly-list.child="${currentPage.listChildren}">
    <dt>index: ${childList.index}</dt>
    <dd>value: ${child.title}</dd>
</dl>

È inoltre possibile accedere alle proprietà in modo dinamico:

<dl data-sly-list.child="${myObj}">
    <dt>key: ${child}</dt>
    <dd>value: ${myObj[child]}</dd>
</dl>

riferimento

data-sly-resource include il risultato del rendering della risorsa indicata tramite la risoluzione e il processo di rendering sling.

Una semplice risorsa include:

<article data-sly-resource="path/to/resource"></article>

Percorso non sempre richiesto

Tenere presente che l'utilizzo di un percorso con data-sly-resource non è richiesto se si dispone già di una risorsa. Se disponete già di una risorsa, potete utilizzarla direttamente.

Ad esempio, quanto segue è corretto.

<sly data-sly-resource="${resource.path @ decorationTagName='div'}"></sly>

Tuttavia, anche quanto segue è perfettamente accettabile.

<sly data-sly-resource="${resource @ decorationTagName='div'}"></sly>

È consigliabile utilizzare la risorsa direttamente quando possibile, per i motivi seguenti.

  • Se disponete già della risorsa, la risoluzione del problema utilizzando il percorso è un lavoro aggiuntivo e non necessario.
  • Se si utilizza il percorso in cui è già presente la risorsa, è possibile che vengano generati risultati imprevisti in quanto le risorse Sling possono essere racchiuse o sintetiche e non essere fornite nel percorso specificato.

Opzioni

Le opzioni consentono una serie di varianti aggiuntive:

Manipolazione del percorso della risorsa:

<article data-sly-resource="${ @ path='path/to/resource'}"></article>
<article data-sly-resource="${'resource' @ prependPath='my/path'}"></article>
<article data-sly-resource="${'my/path' @ appendPath='resource'}"></article>

Aggiungere o sostituire un selettore:

<article data-sly-resource="${'path/to/resource' @ selectors='selector'}"></article>

Aggiungete, sostituite o rimuovete più selettori:

<article data-sly-resource="${'path/to/resource' @ selectors=['s1', 's2']}"></article>

Aggiungere un selettore a quelli esistenti:

<article data-sly-resource="${'path/to/resource' @ addSelectors='selector'}"></article>

Rimuovete alcuni selettori da quelli esistenti:

<article data-sly-resource="${'path/to/resource' @ removeSelectors='selector1'}"></article>

Rimuovete tutti i selettori:

<article data-sly-resource="${'path/to/resource' @ removeSelectors}"></article>

Sostituisce il tipo di risorsa:

<article data-sly-resource="${'path/to/resource' @ resourceType='my/resource/type'}"></article>

Cambia la modalità WCM:

<article data-sly-resource="${'path/to/resource' @ wcmmode='disabled'}"></article>

Per impostazione predefinita, i tag di decorazione AEM sono disattivati, l'opzione decorationTagName consente di riportarli e l'opzione cssClassName consente di aggiungere classi a tale elemento.

<article data-sly-resource="${'path/to/resource' @ decorationTagName='span',
cssClassName='className'}"></article>
NOTA

AEM offre una logica chiara e semplice che controlla i tag di decorazione che racchiudono gli elementi inclusi. Per informazioni dettagliate, vedere Decoration Tag nella documentazione dei componenti in via di sviluppo.

includi

data-sly-include sostituisce il contenuto dell'elemento host con la marcatura generata dal file modello HTML indicato (HTL, JSP, ESP, ecc.) quando viene elaborato dal motore modello corrispondente. Il contesto di rendering del file incluso non includerà il contesto HTL corrente (quello del file incluso); Di conseguenza, per l'inclusione di file HTL, l'attuale data-sly-use dovrebbe essere ripetuta nel file incluso (In tal caso è generalmente meglio utilizzare data-sly-template e data-sly-call)

Un semplice esempio:

<section data-sly-include="path/to/template.html"></section>

I JSP possono essere inclusi allo stesso modo:

<section data-sly-include="path/to/template.jsp"></section>

Le opzioni consentono di modificare il percorso del file:

<section data-sly-include="${ @ file='path/to/template.html'}"></section>
<section data-sly-include="${'template.html' @ prependPath='my/path'}"></section>
<section data-sly-include="${'my/path' @ appendPath='template.html'}"></section>

È inoltre possibile modificare la modalità WCM:

<section data-sly-include="${'template.html' @ wcmmode='disabled'}"></section>

Request-Attributes

In data-sly-include e data-sly-resource è possibile passare requestAttributes per utilizzarli nello script HTL ricevente.

Questo consente di trasmettere correttamente i parametri agli script o ai componenti.

<sly data-sly-use.settings="com.adobe.examples.htl.core.hashmap.Settings"
        data-sly-include="${ 'productdetails.html' @ requestAttributes=settings.settings}" />

Codice Java della classe Settings, la Mappa viene utilizzata per trasmettere in requestAttributes:

public class Settings extends WCMUsePojo {

  // used to pass is requestAttributes to data-sly-resource
  public Map<String, Object> settings = new HashMap<String, Object>();

  @Override
  public void activate() throws Exception {
    settings.put("layout", "flex");
  }
}

Ad esempio, tramite un modello Sling, è possibile utilizzare il valore di requestAttributes specificato.

In questo esempio, il layout viene inserito tramite la Mappa dalla classe Use:

@Model(adaptables=SlingHttpServletRequest.class)
public class ProductSettings {
  @Inject @Optional @Default(values="empty")
  public String layout;

}

template & call

I blocchi modello possono essere utilizzati come chiamate di funzione: nella loro dichiarazione possono ottenere parametri, che possono poi essere passati quando li chiamano. Consentono inoltre la ricorsione.

data-sly-template definisce un modello. L’elemento host e il relativo contenuto non vengono inviati da HTL

data-sly-call chiama un modello definito con un modello basato su dati. Il contenuto del modello denominato (eventualmente con parametri) sostituisce il contenuto dell’elemento host della chiamata.

Definire un modello statico e richiamarlo:

<template data-sly-template.one>blah</template>
<div data-sly-call="${one}"></div>

Definire un modello dinamico e richiamarlo con i parametri:

<template data-sly-template.two="${ @ title}"><h1>${title}</h1></template>
<div data-sly-call="${two @ title=properties.jcr:title}"></div>

I modelli che si trovano in un file diverso possono essere inizializzati con data-sly-use. Tenere presente che in questo caso data-sly-use e data-sly-call possono essere inseriti anche sullo stesso elemento:

<div data-sly-use.lib="templateLib.html">
    <div data-sly-call="${lib.one}"></div>
    <div data-sly-call="${lib.two @ title=properties.jcr:title}"></div>
</div>

È supportata la ricorsione del modello:

<template data-sly-template.nav="${ @ page}">
    <ul data-sly-list="${page.listChildren}">
        <li>
            <div class="title">${item.title}</div>
            <div data-sly-call="${nav @ page=item}" data-sly-unwrap></div>
        </li>
    </ul>
</template>
<div data-sly-call="${nav @ page=currentPage}" data-sly-unwrap></div>

sly Element

Il tag HTML <sly> può essere utilizzato per rimuovere l'elemento corrente, consentendo la visualizzazione solo degli elementi secondari. La sua funzionalità è simile all'elemento blocco data-sly-unwrap:

<!--/* This will display only the output of the 'header' resource, without the wrapping <sly> tag */-->
<sly data-sly-resource="./header"></sly>

Sebbene non sia un tag HTML 5 valido, il tag <sly> può essere visualizzato nell'output finale utilizzando data-sly-unwrap:

<sly data-sly-unwrap="${false}"></sly> <!--/* outputs: <sly></sly> */-->

L'obiettivo dell'elemento <sly> è di rendere più ovvio che l'elemento non è in uscita. Se si desidera è comunque possibile utilizzare data-sly-unwrap.

Come con data-sly-unwrap, cercate di ridurre al minimo l'uso di questo.

In questa pagina