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

Java Use-API per HTL consente a un file HTL di accedere a metodi di supporto in una classe Java personalizzata.

Caso d’uso use-case

Java Use-API per HTL consente a un file HTL di accedere a metodi di supporto in una classe Java personalizzata tramite data-sly-use. Questo metodo consente di incapsulare nel codice Java tutte le logiche di business complesse, mentre il codice HTL tratta solo la produzione di markup diretto.

Un oggetto Java Use-API può essere un semplice POJO, istanziato in base a una particolare implementazione tramite il costruttore predefinito di POJO.

I POJO Use-API possono inoltre esporre un metodo pubblico, denominato init, con la seguente firma:

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

La mappa bindings può contenere oggetti che forniscono contesto allo script HTL attualmente eseguito che può essere utilizzato dall’oggetto Use-API per la relativa elaborazione.

Un esempio semplice a-simple-example

Questo esempio illustra l’utilizzo di Use-API.

Inizia con un componente HTL, chiamato info,, che non ha una classe use. È costituito da un singolo file, /apps/my-example/components/info.html

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

Aggiungi del contenuto per questo componente per il rendering a /content/my-example/:

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

Quando si accede a questo contenuto, viene eseguito il file HTL. All’interno del codice HTL si utilizza l’oggetto contestuale properties per accedere a title e description della risorsa corrente e per visualizzarli. Il file di output /content/my-example.html è il seguente:

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

Aggiunta di una classe use adding-a-use-class

Il componente info così com’è non ha bisogno di una classe use per eseguire la sua semplice funzione. Tuttavia, in alcuni casi è necessario eseguire operazioni che sono impossibili in HTL e quindi è necessario utilizzare una classe use. Ma tieni presente quanto segue:

Ad esempio, supponiamo che si desideri che il componente info visualizzi le proprietà title e description della risorsa, ma il tutto in minuscolo. Poiché HTL non dispone di un metodo per rendere le stringhe in minuscolo, puoi aggiungere una classe use Java e modificare /apps/my-example/component/info/info.html come segue:

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

Inoltre, viene creato /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;
    }
}

Per ulteriori dettagli, consulta la documentazione Java per com.adobe.cq.sightly.WCMUsePojo.

Osserviamo ora le diverse parti del codice.

Confronto tra classe Java locale e bundle local-vs-bundle-java-class

La classe use Java può essere installata in due modi:

Per sapere quale metodo utilizzare, considera questi due punti:

In questo esempio viene utilizzata un’installazione locale.

Il pacchetto Java è il percorso dell’archivio java-package-is-repository-path

Quando si utilizza un’installazione locale, il nome del pacchetto della classe use deve corrispondere alla posizione della cartella dell’archivio. I caratteri di sottolineatura nel nome del pacchetto sostituiscono eventuali trattini nel percorso.

In questo caso, Info.java si trova in /apps/my-example/components/info e quindi il pacchetto è apps.my_example.components.info:

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {

   ...

}

Estensione WCMUsePojo extending-wcmusepojo

Ci sono diversi modi per incorporare una classe Java con HTL, ma quello più semplice consiste nell’estendere la classe WCMUsePojo. Per questo esempio /apps/my-example/component/info/Info.java:

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo

    ...
}

Inizializzazione della classe initializing-the-class

Quando la classe use viene estesa da WCMUsePojo, l’inizializzazione viene eseguita escludendo il metodo activate, in questo caso 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();
    }

...

}

Contesto context

In genere, il metodo activate viene utilizzato per pre-calcolare e memorizzare (in variabili membro) i valori necessari nel codice HTL, in base al contesto corrente (ad esempio la richiesta e la risorsa correnti).

La classe WCMUsePojo consente di accedere allo stesso set di oggetti contestuali disponibili all’interno di un file HTL (consulta il documento Oggetti globali).

In una classe che estende WCMUsePojo, è possibile accedere agli oggetti contestuali utilizzando i relativi nomi:

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

In alternativa, è possibile accedere direttamente agli oggetti contestuali di uso comune utilizzando il metodo di convenienza appropriato elencato in questa tabella.

Metodi getter getter-methods

Una volta inizializzata la classe use, viene eseguito il file HTL. In questa fase, solitamente HTL richiama lo stato di diverse variabili membro della classe use e li renderizza per la presentazione.

Per fornire l’accesso a questi valori dall’interno del file HTL, è necessario definire metodi getter personalizzati nella classe use in base alla seguente convenzione di denominazione:

Nel seguente file di esempio /apps/my-example/component/info/Info.java, i metodi getTitle e getDescription rendono accessibili le proprietà oggetto title e description all’interno del contesto del file HTL.

...

public class Info extends WCMUsePojo {

    ...

    public String getLowerCaseTitle() {
        return lowerCaseTitle;
    }

    public String getLowerCaseDescription() {
        return lowerCaseDescription;
    }
}

Attributo data-sly-use data-sly-use-attribute

L’attributo data-sly-use viene utilizzato per inizializzare la classe use all’interno del codice HTL. Nell’esempio, l’attributo data-sly-use dichiara che è utilizzata la classe Info. È possibile utilizzare solo il nome locale della classe perché si sta utilizzando un’installazione locale (avendo posizionato il file Java di origine nella stessa cartella del file HTL). Se si utilizzasse un’installazione bundle, si dovrebbe specificare il nome completo della classe.

Nota l’utilizzo in questo esempio /apps/my-example/component/info/info.html.

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

Identificatore locale local-identifier

L’identificatore info (dopo il punto in data-sly-use.info) viene utilizzato all’interno del file HTL per identificare la classe. L’ambito di questo identificatore è globale all’interno del file, dopo che è stato dichiarato. Non è limitato all’elemento che contiene l’istruzione data-sly-use.

Nota l’utilizzo in questo esempio /apps/my-example/component/info/info.html.

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

Ottenere le proprietà getting-properties

L’identificatore info viene quindi utilizzato per accedere alle proprietà oggetto title e description esposte tramite i metodi getter Info.getTitle e Info.getDescription.

Nota l’utilizzo in questo esempio /apps/my-example/component/info/info.html.

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

Output output

Ora, quando si accede a /content/my-example.html, viene restituito il seguente file /content/my-example.html.

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

Oltre le nozioni di base beyond-the-basics

In questa sezione sono presentate alcune ulteriori funzioni che vanno oltre il semplice esempio già descritto.

Trasferimento dei parametri passing-parameters

I parametri possono essere trasferiti a una classe use al momento dell’inizializzazione.

Per maggiori dettagli, consulta la documentazione del motore di script HTL di Sling.

Classe Java in bundle bundled-java-class

Con una classe use in bundle, la classe deve essere compilata, inserita in un pacchetto e implementata in AEM utilizzando il meccanismo di implementazione standard di bundle OSGi. A differenza di un’installazione locale, la dichiarazione di pacchetto della classe use deve essere denominata normalmente come nell’esempio /apps/my-example/component/info/Info.java.

package org.example.app.components;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {
    ...
}

L’istruzione data-sly-use deve fare riferimento al nome completo della classe, anziché al solo nome locale della classe, come nell’esempio /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>