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

Med HTL Java Use-API:t kan en HTML-fil få åtkomst till hjälpmetoder i en anpassad Java-klass.

Användningsfall use-case

Använd-API:t för HTL Java gör att en HTML-fil kan komma åt hjälpmetoder i en anpassad Java-klass via data-sly-use. På så sätt kan all komplex affärslogik kapslas in i Java-koden, medan HTML-koden endast hanterar direkt markeringsproduktion.

Ett Java Use-API-objekt kan vara en enkel POJO som initieras av en viss implementering via POJO:s standardkonstruktor.

Use-API-POJO:erna kan också visa en offentlig metod, som kallas init, med följande signatur:

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

Mappningen bindings kan innehålla objekt som ger kontext till det HTML-skript som körs för tillfället och som Use-API-objektet kan använda för bearbetningen.

Ett exempel a-simple-example

I det här exemplet visas användningen av Use-API.

Vi börjar med en HTML-komponent, som kallas info, som inte har någon use-class. Den består av en enda fil, /apps/my-example/components/info.html

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

Vi lägger också till en del innehåll för den här komponenten som ska återges på /content/my-example/:

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

När det här innehållet öppnas körs HTML-filen. I HTML-koden använder vi kontextobjektet properties för att komma åt den aktuella resursens title och description och visa dem. Utdatafilen /content/my-example.html blir:

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

Lägga till en användningsklass adding-a-use-class

Komponenten info som den ser ut behöver ingen use-klass för att utföra sin enkla funktion. Det finns fall där du behöver göra saker som inte kan göras i HTML och där du behöver en användningsklass. Tänk på följande:

Anta till exempel att du vill att komponenten info ska visa egenskaperna title och description för resursen, men alla med gemener. Eftersom HTML inte har någon metod för att sänka rabattsträngar behöver du en use-class. Vi kan göra detta genom att lägga till en Java-användarklass och ändra /apps/my-example/component/info/info.html enligt följande:

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

Dessutom skapar vi /apps/my-example/component/info/Info.java.

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

Mer information finns i Javadocs för com.adobe.cq.sightly.WCMUsePojo.

Nu går vi igenom de olika delarna av koden.

Java-klass, lokal kontra bunt local-vs-bundle-java-class

Java-klassen kan installeras på två sätt:

Om du vill veta vilken metod du ska använda när bör du tänka på följande två saker:

I det här exemplet används en lokal installation.

Java-paketet är en databassökväg java-package-is-repository-path

När en lokal installation används måste paketnamnet för use-klassen matcha databasmappens namn, där eventuella bindestreck i sökvägen ersätts med understreck i paketnamnet.

I det här fallet finns Info.java på /apps/my-example/components/info så paketet är apps.my_example.components.info:

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {

   ...

}

Utökar WCMUsePojo extending-wcmusepojo

Det finns flera sätt att införliva en Java-klass med HTML (se avsnittet Alternativ till WCMUsePojo), men det enklaste är att utöka klassen WCMUsePojo. Till exempel /apps/my-example/component/info/Info.java:

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo

    ...
}

Initierar klassen initializing-the-class

När use-klassen utökas från WCMUsePojo utförs initieringen genom att metoden activate åsidosätts, i det här fallet i /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

Metoden activate används vanligtvis för att beräkna och lagra (i medlemsvariabler) de värden som behövs i din HTML-kod utifrån det aktuella sammanhanget (till exempel aktuell begäran och resurs).

Klassen WCMUsePojo ger åtkomst till samma uppsättning kontextobjekt som finns i en HTML-fil (se dokumentet Globala objekt.)

I en klass som utökar WCMUsePojo kan kontextobjekt nås via namn med

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

Du kan också komma åt ofta använda kontextobjekt direkt med den bekvämlighetsmetod som anges i den här tabellen.

Getter-metoder getter-methods

När use-class har initierats körs HTML-filen. Under den här scenen kommer HTML vanligtvis att dra in status för olika medlemsvariabler i use-klassen och återge dem för presentation.

Om du vill ge åtkomst till dessa värden inifrån HTML-filen måste du definiera egna get-metoder i use-klassen enligt följande namnkonvention:

I följande exempelfil /apps/my-example/component/info/Info.java resulterar metoderna getTitle och getDescription i att objektegenskaperna title och description blir tillgängliga i HTML-filens kontext.

...

public class Info extends WCMUsePojo {

    ...

    public String getLowerCaseTitle() {
        return lowerCaseTitle;
    }

    public String getLowerCaseDescription() {
        return lowerCaseDescription;
    }
}

dataanvändarvänligt attribut data-sly-use-attribute

Attributet data-sly-use används för att initiera use-klassen i din HTML-kod. I vårt exempel deklarerar attributet data-sly-use att vi vill använda klassen Info. Vi kan bara använda det lokala namnet på klassen eftersom vi använder en lokal installation (när Java-källfilen har placerats i samma mapp som HTML-filen). Om vi använde en paketinstallation måste vi ange det fullständiga klassnamnet.

Observera användningen i det här /apps/my-example/component/info/info.html-exemplet.

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

Lokal identifierare local-identifier

Identifieraren info (efter punkten i data-sly-use.info) används i HTML-filen för att identifiera klassen. Identifierarens omfång är globalt i filen, efter att den har deklarerats. Den är inte begränsad till elementet som innehåller programsatsen data-sly-use.

Observera användningen i det här /apps/my-example/component/info/info.html-exemplet.

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

Hämtar egenskaper getting-properties

Identifieraren info används sedan för att komma åt objektegenskaperna title och description som exponerades via get-metoderna Info.getTitle och Info.getDescription.

Observera användningen i det här /apps/my-example/component/info/info.html-exemplet.

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

Utdata output

När vi öppnar /content/my-example.html returneras följande /content/my-example.html-fil.

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

Förutom grunderna beyond-the-basics

I det här avsnittet introduceras ytterligare funktioner som går utöver det enkla exempel som beskrivs ovan.

Parametrar skickas passing-parameters

Parametrar kan skickas till en use-class vid initiering.

Mer information finns i dokumentationen för Sling HTL Scripting Engine.

Paketerad Java-klass bundled-java-class

Med en paketerad användningsklass måste klassen kompileras, paketeras och distribueras i AEM med den vanliga OSGi-paketdistributionsmekanismen. Till skillnad från en lokal installation bör paketdeklarationen för use-klass namnges normalt på samma sätt som i det här /apps/my-example/component/info/Info.java-exemplet.

package org.example.app.components;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {
    ...
}

Programsatsen data-sly-use måste referera till det fullständiga klassnamnet, i motsats till bara det lokala klassnamnet som i det här /apps/my-example/component/info/info.html-exemplet.

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