API de uso Java do HTL

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. Isso 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 é simplificado para ilustrar seu uso. Em um ambiente de produção, é recomendável usar modelos de Sling.

Começamos com um componente HTL, chamado info, que não tem uma 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>

Também adicionamos 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."
}

Quando esse conteúdo é acessado, o arquivo HTL é executado. No código HTL, usamos o objeto de contexto properties para acessar o title e a description do recurso atual e exibi-los. O arquivo de saída /content/my-example.html será:

<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 o HTL não tem um método para cadeias de caracteres em minúsculas, você precisará de uma classe de uso. Podemos fazer isso adicionando uma classe de uso Java e alterando o /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, criamos o /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;
    }
}

Consulte os Javadocs para 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

Quando uma instalação local é usada, o nome do pacote da classe de uso deve corresponder ao do local da pasta do repositório, com quaisquer hifens no caminho substituídos por sublinhados no nome do pacote.

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 {

   ...

}
OBSERVAÇÃO

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 Java com HTL (consulte a seção Alternativas para o WCMUsePojo), a mais simples é estender a classe WCMUsePojo. Para o nosso exemplo /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 uma classe que estende WCMUsePojo, os objetos de contexto podem ser acessados pelo nome usando

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

Como alternativa, os objetos de contexto usados com frequência podem ser acessados diretamente pelo método de conveniência apropriado, conforme listado nesta tabela.

Objeto Método de conveniência
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étodos Getter

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

Para fornecer acesso a esses valores a partir do arquivo HTL, você deve definir 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 exporá no arquivo HTL uma propriedade de objeto chamada xyz.

No arquivo /apps/my-example/component/info/Info.java de exemplo a seguir, os métodos getTitle e getDescription resultam nas propriedades de objeto title e description, tornando-se 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 seu código HTL. No nosso exemplo, o atributo data-sly-use declara que queremos usar a classe Info. Podemos 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 estivéssemos usando uma instalação de pacote, precisaríamos 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 retornará o seguinte arquivo /content/my-example.html.

<div>
    <h1>my example</h1>
    <p>this is some example content.</p>
</div>
OBSERVAÇÃO

Este exemplo foi simplificado para ilustrar o seu uso. Em um ambiente de produção, é recomendável usar modelos de Sling.

Além das noções básicas

Nesta seção, apresentaremos 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. No caso, podemos fazer algo como no exemplo a seguir:

Para obter detalhes, consulte a documentação do Mecanismo de script HTL do Sling.

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>

Nesta página