Show Menu
TOPICS×

Istruzioni di blocco HTL

Le istruzioni di blocco HTML Template Language (HTL) sono
data
attributi personalizzati aggiunti direttamente al codice 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
data-sly-*
attributi 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
data-sly-*
gli attributi 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
data-sly-template
blocco:
<div data-sly-use.nav="${'navigation.js' @parentPage=currentPage}">${nav.foo}</div>
Inizializzate 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>
Per ulteriori informazioni sull'API Use-API, vedi:

utilizzo semplice dei dati con le risorse

Questo consente di ottenere risorse direttamente in HTL con
data-sly-use
e non richiede la scrittura di codice per ottenerlo.
Ad esempio:
<div data-sly-use.product=“/etc/commerce/product/12345”> ${ product.title } </div>
Vedere anche la sezione Percorso non sempre obbligatorio.

staccare

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 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 impostano l'
title
attributo 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.
Si noti 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. Ad 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.
Ad esempio,
<h1 data-sly-element="${titleLevel}">text</h1>
Sostituisce l’
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
rimozione dell'elemento; un valore di
true
mantiene l'elemento.
Ad esempio, il rendering dell'
p
elemento e del relativo contenuto sarà eseguito 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>

repeat

È
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
data-sly-list
, ma non è necessario un elemento contenitore.
L'esempio seguente mostra che è anche possibile fare riferimento all'
elemento
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'
data-sly-list
istruzione consente di rinominare le
itemList
variabili e
item
le variabili.
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

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 indietro e il parametro cssClassName aggiunge le classi a tale elemento.
<article data-sly-resource="${'path/to/resource' @ decorationTagName='span', cssClassName='className'}"></article>
AEM offre una logica chiara e semplice che controlla i tag di decorazione che racchiudono gli elementi inclusi. Per informazioni dettagliate, consultate Decoration Tag (Tagdecorazione) nella documentazione sui 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 ripetuto 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
potete 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 Sling-Model è possibile utilizzare il valore specificato
requestAttributes
.
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
. Si noti che in questo caso
data-sly-use
e
data-sly-call
potrebbe anche essere posizionato 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
<sly>
HTML può essere utilizzato per rimuovere l'elemento corrente, consentendo la visualizzazione solo dei relativi elementi secondari. La sua funzionalità è simile all'elemento
data-sly-unwrap
block:
<!--/* 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
<sly>
tag può essere visualizzato nell'output finale utilizzando
data-sly-unwrap
:
<sly data-sly-unwrap="${false}"></sly> <!--/* outputs: <sly></sly> */-->
L'obiettivo dell'
<sly>
elemento è rendere più ovvio che l'elemento non è in uscita. Se vuoi puoi ancora usare
data-sly-unwrap
.
Come con
data-sly-unwrap
, cercare di minimizzare l'uso di questo.