HTL-Blockanweisungen

Bei HTML-Vorlagensprachen-Blockanweisungen (HTL) handelt es sich um direkt zur vorhandenen HTML hinzugefügten data-Attributen. Dadurch kann eine statische HTML-Musterseite einfach und unauffällig mit Anmerkungen versehen werden, wodurch sie in eine funktionierende dynamische Vorlage umgewandelt wird, ohne die Gültigkeit des HTML-Codes außer Kraft zu setzen.

Blockübersicht

HTL-Block-Plugins werden durch data-sly-* Attribute definiert, die auf HTML-Elementen festgelegt werden. Elemente können ein schließendes Tag oder selbstschließend sein. Attribute können Werte haben (statische Zeichenfolgen oder Ausdruck) oder einfach boolesche Attribute sein (ohne Wert).

<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. */-->

Alle ausgewerteten data-sly-* Attribute werden aus dem generierten Markup entfernt.

Bezeichner

Auf eine Blockanweisung kann auch ein Bezeichner folgen:

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

Der Bezeichner kann von der Blockanweisung auf verschiedene Weise verwendet werden. Hier einige Beispiele:

<!--/* 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 */-->

Bei Bezeichnern der obersten Ebene wird nicht zwischen Groß- und Kleinschreibung unterschieden (da sie über HTML-Attribute festgelegt werden können, bei denen die Groß-/Kleinschreibung nicht beachtet wird), bei allen Eigenschaften wird jedoch die Groß-/Kleinschreibung beachtet.

Verfügbare Blockanweisungen

Es stehen eine Reihe von Blockanweisungen zur Verfügung. Bei Verwendung mit demselben Element definiert die folgende Prioritätsstufe, wie Blockanweisungen ausgewertet werden:

  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

Wenn zwei Blockanweisungen dieselbe Priorität haben, wird ihre Bewertungsreihenfolge von links nach rechts geändert.

Verwenden Sie

data-sly-use initialisiert ein Hilfsobjekt (in JavaScript oder Java definiert) und stellt es über eine Variable bereit.

Initialisieren Sie ein JavaScript-Objekt, wobei sich die Quelldatei im selben Verzeichnis wie die Vorlage befindet. Beachten Sie, dass der Dateiname verwendet werden muss:

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

Initialisieren Sie eine Java-Klasse, wobei sich die Quelldatei im selben Verzeichnis wie die Vorlage befindet. Beachten Sie, dass der Klassenname verwendet werden muss, nicht der Dateiname:

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

Initialisieren Sie eine Java-Klasse, wobei diese Klasse als Teil eines OSGi-Bundles installiert wird. Beachten Sie, dass der zugehörige vollqualifizierte Klassenname verwendet werden muss:

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

Parameter können mithilfe von options an die Initialisierung weitergegeben werden. Diese Funktion sollte generell nur durch HTL-Code verwendet werden, der sich selbst in einem data-sly-template-Block befindet:

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

Initialisieren Sie eine andere HTL-Vorlage, die mithilfe von data-sly-call abgerufen werden kann:

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

Weitere Informationen über die Anwendungs-API finden Sie unter:

data-sly-use mit Ressourcen

Dies ermöglicht es, Ressourcen direkt in HTML mit zu bekommen data-sly-use und erfordert kein Schreiben von Code, um es zu erhalten.

Beispiel:

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

Siehe auch Abschnitt Pfad nicht immer erforderlich.

unwrap

data-sly-unwrap Entfernt das Hostelement aus dem generierten Markup, während der Inhalt beibehalten wird. Dadurch können Elemente ausgeschlossen werden, die als Bestandteil der HTL-Darstellungslogik erforderlich, in der tatsächlichen Ausgabe jedoch nicht erwünscht sind.

Diese Anweisung sollte jedoch sparsam verwendet werden. Im Allgemeinen ist es besser, das HTL-Markup möglichst nah beim vorgesehenen Ausgabe-Markup zu belassen. Versuchen Sie demnach beim Hinzufügen von HTL-Blockanweisungen, die vorhandene HTML soweit möglich einfach mit Anmerkungen zu versehen, ohne neue Elemente einzuführen.

Dies beispielsweise

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

ergibt

<p>Hello World</p>

Dies demgegenüber

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

ergibt

Hello World

Es ist auch möglich, ein Element bedingt zu umbrechen:

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

set

data-sly-set definiert einen neuen Bezeichner mit einem vordefinierten Wert.

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

text

data-sly-text ersetzt den Inhalt des Hostelements durch den angegebenen Text.

Dies beispielsweise

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

entspricht

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

Beide zeigen den Wert von jcr:description als Absatztext an. Der Vorteil der zweiten Methode besteht darin, dass sie die unauffällige Anmerkung der HTML ermöglicht und gleichzeitig den statischen Platzhalterinhalt aus dem ursprünglichen Designer beibehält.

attribute

data-sly-attribute fügt dem Hostelement Attribute hinzu.

Dies beispielsweise

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

entspricht

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

Beide legen das Attribut title auf den Wert von jcr:title fest. Der Vorteil der zweiten Methode besteht darin, dass sie die unauffällige Anmerkung der HTML ermöglicht und gleichzeitig den statischen Platzhalterinhalt aus dem ursprünglichen Designer beibehält.

Attribute werden von links nach rechts aufgelöst, wobei die am weitesten rechts liegende Instanz eines Attributs (literal oder definiert über data-sly-attribute) vor anderen, links davon definierten Instanzen desselben Attributs (data-sly-attribute) Vorrang hat.

Beachten Sie, dass ein Attribut (literal oder festgelegt über data-sly-attribute), dessen Wert in einer leeren Zeichenfolge ausgewertet wird, aus dem endgültigen Markup entfernt wird. Die einzige Ausnahme von dieser Regel ist, dass ein auf eine leere literal-Zeichenfolge festgelegtes literal-Attribut beibehalten wird. Beispiel:

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

produziert

<div></div>

aber

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

produziert

<div class=""></div>

Geben Sie zum Festlegen mehrerer Attribute ein Schlüssel-Wert-Paare enthaltendes Zuordnungsobjekt weiter, das den Attributen und ihren Werten entspricht. Angenommen,

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

Dann,

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

produziert

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

element

data-sly-element ersetzt den Elementnamen des Hostelements.

Beispiel:

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

Ersetzt den h1 durch den Wert titleLevel.

Aus Sicherheitsgründen akzeptiert data-sly-element nur die folgenden Elementnamen:

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

Zum Festlegen anderer Elemente muss die XSS-Sicherheit deaktiviert sein ( @context='unsafe').

test

data-sly-test entfernt das Hostelement und seinen Inhalt bedingt. Durch den Wert false wird das Element entfernt. Durch den Wert true wird das Element beibehalten.

Zum Beispiel werden das Element p und die zugehörigen Inhalte nur dargestellt, wenn isShown dem Wert true entspricht:

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

Das Testergebnis kann zur Variable zugewiesen werden, die später verwendet werden kann. Dies wird für gewöhnlich zum Erstellen der „if else“-Logik verwendet, da keine explizite else-Anweisung vorliegt:

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

Die Variable ist nach ihrer Festlegung global in der HTL-Datei.

Im Folgenden finden Sie einige Beispiele zum Vergleichen von Werten:

<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

With data-sly-repeat you can repeat an element multiple times based on the list that is specified.

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

This works the same way as data-sly-list, except that you do not need a container element.

Das folgende Beispiel zeigt, dass Sie für Attribute auch auf das Element verweisen können:

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

list

data-sly-list wiederholt den Inhalt des Hostelements für jede Eigenschaft, die im bereitgestellten Objekt nummeriert werden kann.

Im Folgenden finden Sie eine einfache Schleife:

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

Die folgenden standardmäßigen Variablen sind im Umfang der Liste verfügbar:

  • item: Das aktuelle Elemente in der Wiederholung.
  • itemList: Objekt, das die folgenden Eigenschaften enthält:
  • index: Zähler auf Basis null ( 0..length-1).
  • count: Zähler auf Basis eins ( 1..length).
  • first: true, wenn das aktuelle Element das erste Element ist.
  • middle: true wenn das aktuelle Element weder das erste noch das letzte Element ist.
  • last: true wenn das aktuelle Element das letzte Element ist.
  • odd: true wenn ungerade index ist.
  • even: true wenn index es gerade ist.

Durch das Definieren eines Bezeichners für die Anweisung data-sly-list itemList können Sie die Variablen  und item umbenennen. item werden <variable> und werden itemList werden <variable>List.

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

Sie können auch dynamisch auf Eigenschaften zugreifen:

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

Ressource

data-sly-resource enthält das Ergebnis der Wiedergabe der angegebenen Ressource durch die Sling-Auflösung und den Renderprozess.

Zu einer einfachen Ressource gehören:

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

Pfad nicht immer erforderlich

Beachten Sie, dass die Verwendung eines Pfades mit nicht erforderlich data-sly-resource ist, wenn Sie bereits über die Ressource verfügen. Wenn Sie die Ressource bereits haben, können Sie sie direkt verwenden.

Beispielsweise ist Folgendes richtig.

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

Gleichwohl ist Folgendes vollkommen akzeptabel.

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

Es wird empfohlen, die Ressource aus folgenden Gründen möglichst direkt zu verwenden.

  • Wenn Sie bereits über die Ressource verfügen, ist eine erneute Auflösung unter Verwendung des Pfads zusätzliche, unnötige Arbeit.
  • Die Verwendung des Pfads, wenn Sie bereits über die Ressource verfügen, kann zu unerwarteten Ergebnissen führen, da Sling-Ressourcen umschlossen werden können oder synthetisch sein können und nicht an dem angegebenen Pfad bereitgestellt werden.

Optionen

Optionen ermöglichen einige zusätzliche Varianten:

Ändern des Ressourcenpfads:

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

Hinzufügen (oder Ersetzen) einer Auswahl:

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

Hinzufügen, Ersetzen oder Entfernen von Mehrfachauswahlen:

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

Hinzufügen einer Auswahl zu vorhandenen:

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

Entfernen einiger Auswahlen aus vorhandenen:

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

Entfernen sämtlicher Auswahlen:

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

Überschreibt den Ressourcentyp der Ressource:

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

Ändert den WCM-Modus:

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

Die decoration-Tags von AEM sind standardmäßig deaktiviert. Mit der Option „decorationTagName“ können sie zurückgeholt werden und mit „cssClassName“ können diesem Element Klassen hinzugefügt werden.

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

AEM bietet klare und einfache Logik, die die decoration-Tags steuert, die enthaltene Elemente umschließen. For details see Decoration Tag in the developing components documentation.

include

data-sly-include ersetzt den Inhalt des Hostelements durch das Markup, das von der angegebenen HTML-Vorlagendatei (HTL, JSP, ESP usw.) generiert wurde. wenn er durch das entsprechende Vorlagenmodul verarbeitet wird. Der Darstellungskontext der eingeschlossenen Datei enthält den aktuellen HTL-Kontext nicht (den der einzuschließenden Datei). Demzufolge muss das aktuelle Element data-sly-use für das Einschließen der HTL-Dateien in der eingeschlossenen Datei wiederholt werden (in einem solchen Fall ist es für gewöhnlich besser, data-sly-template und data-sly-call zu verwenden).

Ein einfaches include-Beispiel:

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

JSPs können auf gleiche Weise eingeschlossen werden:

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

Mit Optionen können Sie den Dateipfad ändern:

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

Sie können auch den WCM-Modus ändern:

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

Request-attributes

In the data-sly-include and data-sly-resource you can pass requestAttributes in order to use them in the receiving HTL-script.

So können Sie Parameter in Skripten oder Komponenten ordnungsgemäß weitergeben.

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

Java-Code der Einstellungsklasse, die Zuordnung wird zum Weitergeben in requestAttributes verwendet:

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");
  }
}

For example, via a Sling-Model, you can consume the value of the specified requestAttributes.

In diesem Beispiel wird layout über die Zuordnung aus der Anwendungsklasse eingefügt:

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

}

template & call

Vorlagenblöcke können wie Funktionsaufrufe verwendet werden: in ihrer Deklaration können sie Parameter abrufen, die dann beim Aufruf weitergegeben werden können. Sie ermöglichen auch eine Rekursion.

data-sly-template definiert eine Vorlage. Das Hostelement und die zugehörigen Inhalte werden durch HTL nicht ausgegeben

data-sly-call ruft eine mit einer datenbasierten Vorlage definierte Vorlage auf. Der Inhalt der abgerufenen Vorlage (optional parametrisiert) ersetzt den Inhalt des Hostelements des Aufrufs.

Definieren Sie eine statische Vorlage und rufen Sie sie anschließend auf:

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

Definieren Sie eine dynamische Vorlage und rufen Sie sie dann mit Parametern auf:

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

Templates located in a different file, can be initialized with data-sly-use. Beachten Sie, dass in diesem Fall data-sly-use und data-sly-call auch im selben Element platziert werden könnten:

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

Die Vorlagenverschachtelung wird unterstützt:

<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

Das <sly> HTML-Tag kann zum Entfernen des aktuellen Elements verwendet werden, sodass nur dessen untergeordnete Elemente angezeigt werden können. Seine Funktionalität ähnelt dem data-sly-unwrap Blockelement:

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

Obwohl es sich nicht um ein gültiges HTML5-Tag handelt, kann das <sly> -Tag in der endgültigen Ausgabe angezeigt werden data-sly-unwrap:

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

The goal of the <sly> element is to make it more obvious that the element is not output. If you want you can still use data-sly-unwrap.

As with data-sly-unwrap, try to minimize the use of this.

Auf dieser Seite