API de uso Java do HTL htl-java-use-api

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 use-case

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 a-simple-example

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

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 adding-a-use-class

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:

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 local-vs-bundle-java-class

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

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

Este exemplo usa uma instalação local.

O pacote Java é o caminho do repositório java-package-is-repository-path

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 {

   ...

}

Extensão WCMUsePojo extending-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 initializing-the-class

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 context

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.

Métodos Getter getter-methods

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:

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 data-sly-use-attribute

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 local-identifier

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 getting-properties

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 output

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>

Além das noções básicas beyond-the-basics

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

Passagem de parâmetros passing-parameters

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

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

Classe Java agrupada bundled-java-class

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>