HTL-Java-Anwendungs-API htl-java-use-api

Die HTL-Java-Anwendungs-API ermöglicht einer HTL-Datei den Zugriff auf Hilfsmethoden in einer benutzerdefinierten Java-Klasse.

Nutzungsszenario use-case

Die HTL-Java-Anwendungs-API ermöglicht einer HTL-Datei den Zugriff auf Hilfsmethoden in einer benutzerdefinierten Java-Klasse über data-sly-use. Durch diese Methode kann die gesamte komplexe Geschäftslogik im Java-Code verschachtelt werden, während der HTL-Code nur die direkte Markup-Produktion verarbeiten muss.

Ein Java-Anwendungs-API-Objekt kann ein einfacher POJO sein, der von einer bestimmten Implementierung über den Standardkonstruktor von POJO instanziiert wird.

Die Anwendungs-API-POJOs können auch eine öffentliche Methode namens init mit der folgenden Signatur bereitstellen:

    /**
     * Initializes the Use bean.
     *
     * @param bindings All bindings available to the HTL scripts.
     **/
    public void init(javax.script.Bindings bindings);

Die bindings-Karte kann Objekte enthalten, die dem derzeit ausgeführten HTL-Skript einen Kontext geben, den das Anwendungs-API-Objekt für seine Verarbeitung nutzen kann.

Ein einfaches Beispiel a-simple-example

Dieses Beispiel veranschaulicht die Verwendung der Anwendungs-API.

Starten Sie mit einer HTL-Komponente namens info,, die keine Anwendungsklasse hat. Sie besteht aus einer einzelnen Datei namens /apps/my-example/components/info.html

<div>
    <h1>${properties.title}</h1>
    <p>${properties.description}</p>
</div>

Fügen Sie etwas Inhalt für diese unter /content/my-example/ zu rendernde Komponente hinzu:

{
    "sling:resourceType": "my-example/component/info",
    "title": "My Example",
    "description": "This Is Some Example Content."
}

Wenn auf diesen Inhalt zugegriffen wird, wird die HTL-Datei ausgeführt. Innerhalb des HTL-Codes wird das Kontextobjekt properties verwendet, um auf title und description der aktuellen Ressource zuzugreifen und sie anzuzeigen. Die Ausgabedatei /content/my-example.html ist Folgende:

<div>
    <h1>My Example</h1>
    <p>This Is Some Example Content.</p>
</div>

Hinzufügen einer Anwendungsklasse adding-a-use-class

Die Komponente info benötigt in ihrer gegebenen Form keine Anwendungsklasse, um ihre sehr einfache Funktion zu erfüllen. Es gibt jedoch Fälle, in denen Sie Dinge tun müssen, die in HTL nicht möglich sind, und daher eine Anwendungsklasse benötigen. Beachten Sie aber das Folgende:

Angenommen, Sie möchten, dass die Komponente info die Eigenschaften title und description der Ressource anzeigt, jedoch komplett in Kleinschreibung. Da HTL über keine Methode zur Umwandlung von Zeichenfolgen in Kleinschreibung verfügt, können Sie eine Java-Anwendungsklasse hinzufügen und /apps/my-example/component/info/info.html wie folgt ändern:

<div data-sly-use.info="Info">
    <h1>${info.lowerCaseTitle}</h1>
    <p>${info.lowerCaseDescription}</p>
</div>

Außerdem wird /apps/my-example/component/info/Info.java erstellt.

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {
    private String lowerCaseTitle;
    private String lowerCaseDescription;

    @Override
    public void activate() throws Exception {
        lowerCaseTitle = getProperties().get("title", "").toLowerCase();
        lowerCaseDescription = getProperties().get("description", "").toLowerCase();
    }

    public String getLowerCaseTitle() {
        return lowerCaseTitle;
    }

    public String getLowerCaseDescription() {
        return lowerCaseDescription;
    }
}

Weitere Einzelheiten finden Sie in den Javadocs für com.adobe.cq.sightly.WCMUsePojo.

Lassen Sie uns nun einen Blick auf die verschiedenen Teile des Codes werfen.

Lokale vs. Bundle-Java-Klasse local-vs-bundle-java-class

Die Java-Anwendungsklasse kann auf zwei Arten installiert werden:

Um zu wissen, welche Methode Sie wann anwenden sollten, sollten Sie diese beiden Punkte beachten:

In diesem Beispiel wird eine lokale Installation verwendet.

Java-Paket ist der Repository-Pfad java-package-is-repository-path

Bei Verwendung einer lokalen Installation muss der Paketname der Anwendungsklasse mit dem Speicherort des Repository-Ordners übereinstimmen. Unterstriche im Paketnamen ersetzen alle Bindestriche im Pfad.

In diesem Fall befindet sich Info.java unter /apps/my-example/components/info. Daher lautet das Paket apps.my_example.components.info:

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {

   ...

}

Erweitern von WCMUsePojo extending-wcmusepojo

Es gibt zwar eine Reihe von Möglichkeiten, eine Java-Klasse mit HTL zu integrieren, jedoch besteht die einfachste Möglichkeit darin, die Klasse WCMUsePojo zu erweitern. In diesem Beispiel /apps/my-example/component/info/Info.java:

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo

    ...
}

Initialisierung der Klasse initializing-the-class

Wenn die Anwendungsklasse von WCMUsePojo erweitert wird, erfolgt die Initialisierung durch Überschreibung der activate-Methode, in diesem Fall in /apps/my-example/component/info/Info.java

...

public class Info extends WCMUsePojo {
    private String lowerCaseTitle;
    private String lowerCaseDescription;

    @Override
    public void activate() throws Exception {
        lowerCaseTitle = getProperties().get("title", "").toLowerCase();
        lowerCaseDescription = getProperties().get("description", "").toLowerCase();
    }

...

}

Kontext context

Die Methode aktivieren wird für gewöhnlich verwendet, um anhand des aktuellen Kontexts (beispielsweise der aktuellen Anforderung und Ressource) die in Ihrem HTL-Code erforderlichen Werte vorab zu berechnen und zu speichern (in Nutzervariablen).

Die Klasse WCMUsePojo ermöglicht den Zugriff auf dieselbe Reihe von Kontextobjekten, die in einer HTL-Datei verfügbar sind (siehe das Dokument Globale Objekte.)

In einer Klasse, die WCMUsePojo erweitert, können Sie mithilfe ihrer Namen auf Kontextobjekte zugreifen:

<T> T get(String name, Class<T> type)

Alternativ können Sie direkt auf häufig verwendete Kontextobjekte zugreifen, indem Sie die passende Methode in dieser Tabelle verwenden.

Getter-Methoden getter-methods

Sobald die Anwendungsklasse initialisiert ist, wird die HTL-Datei ausgeführt. In dieser Phase wird HTL in der Regel den Status verschiedener Mitgliedsvariablen der Anwendungsklasse abrufen und sie für die Darstellung rendern.

Um den Zugriff auf diese Werte von der HTL-Datei aus zu ermöglichen, müssen Sie benutzerdefinierte Getter-Methoden in der Anwendungsklasse gemäß der folgenden Namenskonvention definieren:

In der folgenden Beispieldatei /apps/my-example/component/info/Info.java führen die Methoden getTitle und getDescription dazu, dass die Objekteigenschaften title und description im Kontext der HTL-Datei zugänglich werden.

...

public class Info extends WCMUsePojo {

    ...

    public String getLowerCaseTitle() {
        return lowerCaseTitle;
    }

    public String getLowerCaseDescription() {
        return lowerCaseDescription;
    }
}

Attribut data-sly-use data-sly-use-attribute

Das Attribut data-sly-use wird verwendet, um die Anwendungsklasse innerhalb Ihres HTL-Codes zu initialisieren. In diesem Beispiel gibt das Attribut data-sly-use an, dass die Klasse Info verwendet wird. Sie können nur den lokalen Namen der Klasse verwenden, da Sie eine lokale Installation verwenden (wobei die Java-Quelldatei im selben Ordner wie die HTL-Datei platziert wurde). Wenn Sie eine Bundle-Installation verwenden würden, müssten Sie den voll qualifizierten Klassennamen angeben.

Beachten Sie die Verwendung in diesem Beispiel für /apps/my-example/component/info/info.html.

<div data-sly-use.info="Info">
    <h1>${info.lowerCaseTitle}</h1>
    <p>${info.lowerCaseDescription}</p>
</div>

Lokale Kennung local-identifier

Die Kennung info (nach dem Punkt in data-sly-use.info) wird in der HTL-Datei verwendet, um die Klasse anzugeben. Diese Kennung erstreckt sich global in der Datei, nachdem sie deklariert wurde. Er ist nicht auf das Element beschränkt, das die Anweisung data-sly-use enthält.

Beachten Sie die Verwendung in diesem Beispiel für /apps/my-example/component/info/info.html.

<div data-sly-use.info="Info">
    <h1>${info.lowerCaseTitle}</h1>
    <p>${info.lowerCaseDescription}</p>
</div>

Abrufen der Eigenschaften getting-properties

Die Kennung info wird anschließend verwendet, um auf die Objekteigenschaften title und description zuzugreifen, die mithilfe der Getter-Methoden Info.getTitle und Info.getDescription zur Verfügung gestellt wurden.

Beachten Sie die Verwendung in diesem Beispiel für /apps/my-example/component/info/info.html.

<div data-sly-use.info="Info">
    <h1>${info.lowerCaseTitle}</h1>
    <p>${info.lowerCaseDescription}</p>
</div>

Ausgabe output

Wenn nun auf /content/my-example.html zugegriffen wird, wird die folgende Datei /content/my-example.html zurückgegeben.

<div>
    <h1>my example</h1>
    <p>this is some example content.</p>
</div>

Mehr als nur die Grundlagen beyond-the-basics

In diesem Abschnitt werden einige zusätzliche Funktionen vorgestellt, die über das zuvor beschriebene Beispiel hinausgehen.

Weitergeben von Parametern passing-parameters

Parameter können bei der Initialisierung an eine Anwendungsklasse weitergegeben werden.

Weitere Informationen finden Sie in der Dokumentation zu HTL Scripting Engine von Sling.

Gebündelte Java-Klasse bundled-java-class

Bei einer gebündelten Anwendungsklasse muss die Klasse kompiliert, verpackt und in AEM mithilfe des standardmäßigen Verteilungsmechanismus für OSGi-Bundles bereitgestellt werden. Im Gegensatz zu einer lokalen Installation sollte die Paketdeklaration für die Anwendungsklasse normal benannt werden, wie in diesem Beispiel für /apps/my-example/component/info/Info.java.

package org.example.app.components;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {
    ...
}

Außerdem muss die Anweisung data-sly-use den voll qualifizierten Klassennamen referenzieren, nicht nur den lokalen Klassennamen wie in diesem Beispiel für /apps/my-example/component/info/info.html.

<div data-sly-use.info="org.example.app.components.info.Info">
  <h1>${info.title}</h1>
  <p>${info.description}</p>
</div>