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 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 l’oggetto Use-API può utilizzare per la relativa elaborazione.

Un esempio semplice a-simple-example

Questo esempio illustra l’utilizzo di Use-API.

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

Aggiungiamo anche 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 utilizziamo l’oggetto contestuale properties per accedere a title e description della risorsa corrente e per visualizzarli. Il file di output /content/my-example.html sarà:

<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, sarà necessaria una classe use. Per farlo, si aggiunge una classe use Java e si modifica /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, si crea /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.

Passiamo ora alle 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 a quello della posizione della cartella dell’archivio, con eventuali trattini nel percorso sostituiti da trattini bassi nel nome del pacchetto.

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 (vedi la sezione Alternative a WCMUsePojo). Quello più semplice è di estendere la classe WCMUsePojo. Per il nostro 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 insieme di oggetti contestuali disponibili all’interno di un file HTL (vedi il documento Oggetti globali).

In una classe che estende WCMUsePojo, è possibile accedere agli oggetti contestuali per nome utilizzando

<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 indicato 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 varie variabili membro della classe use e le restituisce 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. Nel nostro esempio, l’attributo data-sly-use dichiara la volontà di utilizzare 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 utilizzassimo un’installazione bundle, dovremmo 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, verrà 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 presenteremo alcune ulteriori funzioni che vanno oltre il semplice esempio precedente.

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>