Java Use-API per HTL

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

Caso d’uso

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

Questo esempio illustra l’utilizzo di Use-API.

NOTA

Questo esempio è semplificato per illustrare semplicemente il suo utilizzo. In un ambiente di produzione, si consiglia di utilizzare i modelli Sling.

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

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:

NOTA

È consigliabile utilizzare una classe use solo quando non è possibile eseguire operazioni unicamente in HTL.

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

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

  • Locale: in un’installazione locale, il file Java di origine viene posizionato accanto al file HTL, nella stessa cartella dell’archivio. Il file di origine viene compilato automaticamente su richiesta. Non è richiesta alcuna fase separata di compilazione o packaging.
  • Bundle: in un’installazione bundle, la classe Java deve essere compilata e implementata all’interno di un bundle OSGi utilizzando il meccanismo di implementazione di bundle standard di AEM (vedi la sezione Classe Java in bundle).

Per sapere quale metodo utilizzare, considera questi due punti:

  • Si consiglia una classe use Java locale quando la classe use è specifica per il componente in questione.
  • Una classe use Java bundle è consigliata quando il codice Java implementa un servizio a cui si accede da più componenti HTL.

In questo esempio viene utilizzata un’installazione locale.

Il pacchetto Java è il percorso dell’archivio

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 {

   ...

}
NOTA

L’utilizzo dei trattini nei nomi di elementi dell’archivio è una pratica consigliata nello sviluppo AEM. Tuttavia, i trattini non sono consentiti nei nomi dei pacchetti Java. Per questo motivo, tutti i trattini nel percorso dell’archivio devono essere convertiti in trattini bassi nel nome del pacchetto.

Estensione 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

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

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.

Oggetto Metodo di convenienza
PageManager getPageManager()
Page getCurrentPage()
Page getResourcePage()
ValueMap getPageProperties()
ValueMap getProperties()
Designer getDesigner()
Design getCurrentDesign()
Style getCurrentStyle()
Component getComponent()
ValueMap getInheritedProperties()
Resource getResource()
ResourceResolver getResourceResolver()
SlingHttpServletRequest getRequest()
SlingHttpServletResponse getResponse()
SlingScriptHelper getSlingScriptHelper()

Metodi getter

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:

  • Un metodo sotto forma di getXyz esporrà all’interno del file HTL una proprietà oggetto denominata xyz.

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

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

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à

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

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

Questo esempio è stato semplificato per illustrare semplicemente il suo utilizzo. In un ambiente di produzione, si consiglia di utilizzare modelli Sling.

Oltre le nozioni di base

In questa sezione presenteremo alcune ulteriori funzioni che vanno oltre il semplice esempio precedente.

  • Trasferimento dei parametri a una classe use
  • Classe use Java in bundle

Trasferimento dei parametri

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

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>

In questa pagina