API de uso Java do HTL

Última atualização: 24 de julho de 2025

Tópicos:
Ferramentas de desenvolvedores

Criado para:

Desenvolvedor

A API de uso Java do HTL permite que um arquivo HTL acesse métodos de ajuda em uma classe Java personalizada.

Caso de uso

A API de uso Java do HTL permite que um arquivo HTL acesse métodos de ajuda em uma classe Java personalizada através do data-sly-use. Esse método permite que toda lógica de negócios complexa seja encapsulada no código Java, enquanto o código HTL lida somente com a produção de marcação direta.

Um objeto da API de uso do Java pode ser um POJO simples, instanciado por uma implementação específica por meio do construtor padrão do POJO.

Os POJOs da API de uso também podem expor um método público, chamado init, com a seguinte assinatura:

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

O mapa de bindings pode conter objetos que fornecem contexto para o script HTL executado no momento que o objeto da API de uso pode usar para processamento.

Um exemplo simples

Este exemplo ilustra a utilização da API de uso.

OBSERVAÇÃO

Este exemplo foi simplificado apenas para ilustrar o uso. Em um ambiente de produção, a Adobe recomenda usar modelos do Sling.

Comece com um componente HTL, chamado de info,, que não tenha nenhuma classe de uso. Ele consiste em um único arquivo, /apps/my-example/components/info.html

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

Adicione algum conteúdo para esse componente renderizar em /content/my-example/:

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

Ao acessar esse conteúdo, o arquivo HTL será executado. No código HTL, o objeto de contexto properties é usado para acessar e exibir o title e o description do recurso atual. O arquivo de saída /content/my-example.html é o seguinte:

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

Adicionar uma classe de uso

O componente info na sua versão atual não precisa de uma classe de uso para executar sua função simples. Entretanto, há casos em que é necessário fazer coisas que não podem ser feitas no HTL e, portanto, você precisa de uma classe de uso. Mas lembre-se:

OBSERVAÇÃO

Uma classe de uso só deve ser usada quando algo não pode ser feito somente em HTL.

Por exemplo, suponha que você deseja que o componente info exiba as propriedades title e description do recurso, mas todas em minúsculas. Como a HTL não tem um método para deixar as strings em letras minúsculas, é necessário adicionar uma classe de uso Java e alterar /apps/my-example/component/info/info.html da seguinte maneira:

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

Além disso, /apps/my-example/component/info/Info.java é criado.

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;
    }
}

Consulte a documentação do Java sobre com.adobe.cq.sightly.WCMUsePojo para obter mais detalhes.

Agora, vamos analisar as diferentes partes do código.

Classe de Java local vs. pacote

A classe de uso Java pode ser instalada de duas maneiras:

Local - em uma instalação local, o arquivo de origem Java é colocado junto do arquivo HTL, na mesma pasta do repositório. A origem é automaticamente compilada sob demanda. Não é necessária nenhuma etapa de compilação ou empacotamento separada.
Pacote - em uma instalação de pacote, a classe Java deve ser compilada e implantada em um pacote OSGi usando o mecanismo padrão de implantação de pacote do AEM (consulte a seção Classe Java agrupada).

Para saber quando usar cada método, lembre-se destes dois pontos:

Uma classe de uso local do Java é recomendada quando a classe de uso é específica para o componente em questão.
Uma classe de uso em pacote do Java é recomendada quando o código Java implementa um serviço acessado de vários componentes HTL.

Este exemplo usa uma instalação local.

O pacote Java é o caminho do repositório

Ao usar uma instalação local, o nome do pacote da classe de uso precisa corresponder ao local da pasta de repositório. Os sublinhados no nome do pacote substituem os hifens no caminho.

Neste caso, Info.java está localizado em /apps/my-example/components/info, portanto, o pacote é apps.my_example.components.info:

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {

   ...

}

NOTE

Usar hifens nos nomes dos itens do repositório é uma prática recomendada no desenvolvimento do AEM. No entanto, os hifens são inválidos nos nomes dos pacotes Java. Por esse motivo, todos os hifens no caminho do repositório devem ser convertidos em sublinhados no nome do pacote.

Extensão `WCMUsePojo`

Embora existam várias maneiras de incorporar uma classe de Java com HTL, o mais simples é estender a classe WCMUsePojo. Para este exemplo de /apps/my-example/component/info/Info.java:

package apps.my_example.components.info;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo

    ...
}

Inicializar a classe

Quando a classe de uso é estendida de WCMUsePojo, a inicialização é executada substituindo o método activate; nesse caso, em /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();
    }

...

}

Contexto

Normalmente, o método ativar é usado para pré-calcular e armazenar (em variáveis de membro) os valores necessários no código HTL, com base no contexto atual (na solicitação e no recurso atuais, por exemplo).

A classe WCMUsePojo fornece acesso ao mesmo conjunto de objetos de contexto que estão disponíveis em um arquivo HTL (consulte o documento Objetos globais).

Em um WCMUsePojo de extensão de classe, é possível acessar objetos de contexto pelo nome:

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

Alternativamente, é possível acessar diretamente os objetos de contexto comumente usados por meio do método apropriado contido nesta tabela.

Objeto

Método de conveniência

Page

Page

getPageProperties()

Design

Style

getInheritedProperties()

Resource

getResource()

ResourceResolver

getResourceResolver()

SlingHttpServletRequest

getRequest()

SlingHttpServletResponse

getResponse()

SlingScriptHelper

getSlingScriptHelper()

Métodos Getter

Depois que a classe de uso for inicializada, o arquivo HTL será executado. Durante esse estágio, o HTL geralmente obtém o estado de diversas variáveis de membros da classe de uso e as renderiza para fins de apresentação.

Para fornecer acesso a esses valores a partir do arquivo HTL, defina métodos Getter personalizados na classe de uso de acordo com a seguinte convenção de nomeação:

Um método do formulário getXyz expõe no arquivo HTL uma propriedade de objeto chamada xyz.

No arquivo de exemplo a seguir, /apps/my-example/component/info/Info.java, os métodos getTitle e getDescription tornam as propriedades de objeto title e description acessíveis no contexto do arquivo HTL.

...

public class Info extends WCMUsePojo {

    ...

    public String getLowerCaseTitle() {
        return lowerCaseTitle;
    }

    public String getLowerCaseDescription() {
        return lowerCaseDescription;
    }
}

Atributo `data-sly-use`

O atributo data-sly-use é usado para inicializar a classe de uso no código HTL. No exemplo, o atributo data-sly-use declara que a classe Info é usada. É possível usar apenas o nome local da classe, porque estamos usando uma instalação local (uma vez que o arquivo de origem Java tenha sido colocado na mesma pasta que o arquivo HTL). Se estivesse usando uma instalação de pacote, seria necessário especificar o nome de classe totalmente qualificado.

Observe o uso neste exemplo de /apps/my-example/component/info/info.html.

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

Identificador local

O identificador info (após o ponto em data-sly-use.info) é usado no arquivo HTL para identificar a classe. O escopo desse identificador é global dentro do arquivo, depois que ele tiver sido declarado. Não está limitado ao elemento que contém a instrução data-sly-use.

Observe o uso neste exemplo de /apps/my-example/component/info/info.html.

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

Obter propriedades

O identificador info é então usado para acessar as propriedades do objeto title e description, que foram expostas por meio dos métodos Getter Info.getTitle e Info.getDescription.

Observe o uso neste exemplo de /apps/my-example/component/info/info.html.

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

Saída

Agora, ao acessar /content/my-example.html, ele retorna o seguinte arquivo /content/my-example.html.

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

NOTE

Esse exemplo foi simplificado apenas para ilustrar seu uso. Em um ambiente de produção, a Adobe recomenda usar modelos Sling.

Além das noções básicas

Esta seção apresenta alguns recursos adicionais que vão além do exemplo simples descrito anteriormente.

Enviar parâmetros para uma classe de uso
Classe de uso Java agrupada

Passagem de parâmetros

Os parâmetros podem ser passados para uma classe de uso mediante inicialização.

Para mais detalhes, consulte a Sling documentação do mecanismo de script HTL.

Classe Java agrupada

Com uma classe de uso agrupada, a classe deve ser compilada, agrupada e implantada no AEM usando o mecanismo de implantação de pacote OSGi padrão. Diferente de uma instalação local, a declaração do pacote de classe de uso deve ser nomeada normalmente, como neste exemplo de /apps/my-example/component/info/Info.java.

package org.example.app.components;

import com.adobe.cq.sightly.WCMUsePojo;

public class Info extends WCMUsePojo {
    ...
}

E a declaração data-sly-use deve fazer referência a um nome de classe totalmente qualificado, em vez de apenas ao nome de classe local, como neste exemplo de /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>

recommendation-more-help

API de uso Java do HTL

Caso de uso

Um exemplo simples

Adicionar uma classe de uso

Classe de Java local vs. pacote

O pacote Java é o caminho do repositório

Extensão WCMUsePojo

Inicializar a classe

Contexto

Métodos Getter

Atributo data-sly-use

Identificador local

Obter propriedades

Saída

Além das noções básicas

Passagem de parâmetros

Classe Java agrupada

Extensão `WCMUsePojo`

Atributo `data-sly-use`