Java Use-API HTL

Le Java Use-API HTL permet à un fichier HTL d’accéder aux méthodes d’assistance de classe Java personnalisées.

Cas d’utilisation

Le Java Use-API HTL permet à un fichier HTL d’accéder aux méthodes d’assistance dans une classe Java personnalisée via data-sly-use. Cela permet à l’ensemble de la logique commerciale complexe d’être encapsulée dans le code Java tandis que le code HTL traite uniquement la production directe des balises.

Un objet java Use-API peut être un POJO simple, instancié par une implémentation particulière à travers le constructeur par défaut du POJO.

Les POJO Use-API peuvent également exposer une méthode publique, appelée init, avec la signature suivante :

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

La carte bindings peut contenir des objets qui fournissent du contexte au script HTL actuellement exécuté que l’objet Use-API peut utiliser pour son traitement.

Un exemple simple

Cet exemple illustre l’utilisation du Use-API.

REMARQUE

Cet exemple est simplifié afin d’illustrer de façon simple son utilisation. Dans un environnement de production, il est recommandé d’utiliser les Modèles Sling.

Nous allons commencer avec un composant HTL appelé info, qui n’a pas de classe d’utilisation. Il consiste en un seul fichier, /apps/my-example/components/info.html

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

Nous ajoutons également du contenu pour que ce composant effectue le rendu à /content/my-example/ :

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

Lorsque l’on accède à ce contenu, le fichier HTL est exécuté. Dans le code HTL, nous utilisons l’objet contextuel properties pour accéder au title et à la description de la ressource active et les afficher. Le fichier de sortie /content/my-example.html sera :

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

Ajouter une classe d’utilisation

Le composant info en tant que tel n’a pas besoin d’une classe d’utilisation pour remplir sa simple fonction. Cependant, dans certains cas, vous devez effectuer des opérations qui ne peuvent pas être effectuées dans HTL, et vous avez donc besoin d’une classe d’utilisation. Cependant, gardez à l’esprit les considérations suivantes :

REMARQUE

Une classe d’utilisation ne devrait être utilisée que lorsque quelque chose ne peut pas être fait dans le HTL seul.

Par exemple, supposons que vous souhaitiez que le composant info affiche les propriétés title et description de la ressource, mais toutes en minuscules. Comme HTL ne dispose pas d’une méthode pour mettre en minuscules les chaînes, vous aurez besoin d’une classe d’utilisation. Nous pouvons le faire en ajoutant une classe d’utilisation Java et en modifiant /apps/my-example/component/info/info.html comme suit :

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

En outre, nous créons /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;
    }
}

Pour en savoir plus, veuillez consulter la documentation Javadocs pour com.adobe.cq.sightly.WCMUsePojo.

Maintenant, examinons les différentes parties du code.

Comparaison entre la classe Java locale et celle groupée

La classe d’utilisation Java peut être installée de deux manières :

  • Local - dans le cas d’une installation locale, le fichier source Java est placé à côté du fichier HTL, dans le même dossier du référentiel. Sur demande, la source est automatiquement compilée. Aucune étape de compilation ou d’assemblage distincte n’est requise.
  • Bundle - dans le cas d’une installation groupée, la classe Java doit être compilée et déployée au sein d’un bundle OSGi par le biais du mécanisme de déploiement de bundle standard d’AEM (voir Classe Java groupée).

Pour savoir quelle méthode utiliser et à quel moment, tenez compte des deux points suivants :

  • Une classe d’utilisation Java locale est recommandée quand la classe d’utilisation est spécifique au composant en question.
  • Une classe d’utilisation Java groupée est recommandée quand le code Java met en œuvre un service qui est utilisé par plusieurs composants HTL.

Cet exemple utilise une installation locale.

Le package Java est le chemin d’accès du référentiel.

Lorsqu’une installation locale est utilisée, le nom du package de la classe d’utilisation doit correspondre à l’emplacement du dossier du référentiel, les traits d’union du chemin étant remplacés par des traits de soulignement dans le nom du package.

Dans ce cas, Info.java se trouve à l’adresse /apps/my-example/components/info. Par conséquent, le package est apps.my_example.components.info :

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {

   ...

}
REMARQUE

L’utilisation de traits d’union dans les noms des éléments du référentiel est une pratique recommandée dans le développement AEM. Toutefois, les traits d’union sont des caractères interdits dans les noms de packages Java. C’est pourquoi tous les tirets dans le chemin d’accès au référentiel doivent être convertis en traits de soulignement dans le nom du package.

Extension WCMUsePojo

Bien qu’il existe plusieurs façons d’intégrer une classe Java à HTL (voir la section Alternatives à WCMUsePojo), le plus simple est d’étendre la classe WCMUsePojo. Pour notre exemple /apps/my-example/component/info/Info.java :

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo

    ...
}

Initialiser la classe

Lorsque la classe d’utilisation est étendue depuis WCMUsePojo, l’initialisation est effectuée en remplaçant la méthode activate, dans ce cas dans /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();
    }

...

}

Contexte

En règle générale, la méthode activate est utilisé pour précalculer et stocker (dans des variables membres) les valeurs nécessaires dans votre code HTL, en fonction du contexte actif (la requête et la ressource actives, par exemple).

La classe WCMUsePojo permet d’accéder au même ensemble d’objets de contexte qui est disponible dans un fichier HTL (voir le document Objets globaux.).

Dans une classe qui étend WCMUsePojo, on peut accéder aux objets de contexte par leur nom en utilisant

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

Vous pouvez également accéder directement aux objets de contexte fréquemment utilisés par la méthode pratique appropriée, comme indiqué dans ce tableau.

Objet Méthode pratique
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()

Méthodes getter

Une fois que la classe d’utilisation est initialisée, le fichier HTL est exécuté. Au cours de cette étape, HTL récupère généralement l’état de plusieurs variables de membres de la classe de l’utilisation et les restitue pour la présentation.

Pour permettre l’accès à ces valeurs à partir du fichier HTL, vous devez définir des méthodes getter personnalisées dans la classe d’utilisation, en respectant la convention de nommage suivante :

  • Une méthode de formulaire getXyz exposera dans le fichier HTL une propriété d’objet appelée xyz.

Dans l’exemple suivant /apps/my-example/component/info/Info.java, les méthodes getTitle et getDescription font en sorte que les propriétés d’objets title et description deviennent accessibles dans le contexte du fichier HTL.

...

public class Info extends WCMUsePojo {

    ...

    public String getLowerCaseTitle() {
        return lowerCaseTitle;
    }

    public String getLowerCaseDescription() {
        return lowerCaseDescription;
    }
}

attribut data-sly-use

L’attribut data-sly-use est utilisé pour initialiser la classe d’utilisation dans votre code HTL. Dans notre exemple, l’attribut data-sly-use indique que nous voulons utiliser la classe Info. Nous pouvons utiliser uniquement le nom local de la classe, car nous utilisons une installation locale (le fichier source Java ayant été placé dans le même dossier que le fichier HTL). Si nous utilisions une installation groupée, nous devrions spécifier le nom de classe entièrement qualifié.

Notez l’utilisation dans cet exemple : /apps/my-example/component/info/info.html.

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

Identifiant local

L’identificateur info (après le point dans data-sly-use.info) est utilisé dans le fichier HTL pour identifier la classe. La portée de cet identificateur est globale dans le fichier, une fois qu’il a été déclaré. Elle ne se limite pas à l’élément qui contient l’instruction data-sly-use.

Notez l’utilisation dans cet exemple : /apps/my-example/component/info/info.html.

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

Obtenir des propriétés

L’identificateur info est alors utilisé pour accéder aux propriétés de l’objet title et description, qui ont été exposées par les méthodes getter Info.getTitle et Info.getDescription.

Notez l’utilisation dans cet exemple : /apps/my-example/component/info/info.html.

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

Sortie

Désormais, lorsque nous accédons à /content/my-example.html, le fichier /content/my-example.html suivant vous sera envoyé.

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

Cet exemple a été simplifié pour illustrer simplement son utilisation. Dans un environnement de production, il est recommandé d’utiliser des Modèles Sling.

Au-delà des concepts de base

Dans cette section, prenez connaissance de quelques autres fonctionnalités qui vont au-delà du simple exemple donné ci-dessus.

  • Transmettre des paramètres à une classe d’utilisation
  • Classe d’utilisation Java groupée

Transmission des paramètres

Les paramètres peuvent être transmis à un chemin de classe d’utilisation lors de l’initialisation.

Pour plus d’informations, veuillez vous reporter à la section Documentation du moteur de script HTL Sling.

Classe Java groupée

Avec une classe d’utilisation groupée, la classe doit être compilée, mise en package et déployée dans AEM à l’aide du mécanisme de déploiement standard du bundle OSGi. Contrairement à une installation locale, la classe d’utilisation de déclaration du package doit normalement être nommée comme dans cet exemple : /apps/my-example/component/info/Info.java.

package org.example.app.components;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {
    ...
}

Et l’instruction data-sly-use doit référencer le nom de classe entièrement qualifié, par opposition au simple nom de classe local comme dans cet exemple : /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>

Sur cette page