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:
- Lokal - I en lokal installation placeras Java-källfilen bredvid HTML-filen i samma databasmapp. Källan kompileras automatiskt vid behov. Inget separat kompilerings- eller paketeringssteg krävs.
- Paket - I en paketinstallation måste Java-klassen kompileras och distribueras i ett OSGi-paket med hjälp av AEM standarddistributionsmekanism (se avsnittet Paketerad Java-klass).
Om du vill veta vilken metod du ska använda när bör du tänka på följande två saker:
- En lokal Java use-class rekommenderas när use-klassen är specifik för den aktuella komponenten.
- En Java-användarklass som ingår i paketet rekommenderas när Java-koden implementerar en tjänst som är tillgänglig från flera HTML-komponenter.
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:
- En metod i formatet
getXyz
visar en objektegenskap med namnetxyz
i HTML-filen.
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.
- Skicka parametrar till en use-klass
- Paketerad Java-klass
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>