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

Adicione 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, o objeto de contexto properties é usado para acessar os title e description do recurso atual e exibi-los. 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 o HTL não tem um método para cadeias de caracteres em minúsculas, você pode 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 os documentos Java de com.adobe.cq.sightly.WCMUsePojo para obter mais detalhes.

Agora, vamos observar 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 deve corresponder ao local da pasta do 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 Java com HTL (consulte a seção Alternativas para o WCMUsePojo), a mais simples é estender a classe WCMUsePojo. Para este 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 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 uma classe que estende WCMUsePojo, você pode acessar objetos de contexto usando seus nomes:

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

Como alternativa, você pode acessar objetos de contexto comumente usados diretamente usando o método de conveniência apropriado listado 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 normalmente extrai o estado de várias variáveis de membro da classe de uso e as renderiza para 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:

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

O atributo data-sly-use é usado para inicializar a classe de uso no seu código HTL. No exemplo, o atributo data-sly-use declara que a classe Info é usada. Você pode usar apenas o nome local da classe porque está usando uma instalação local (tendo colocado o arquivo de origem Java na mesma pasta que o arquivo HTL). Se você estivesse usando uma instalação de pacote, precisaria 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, quando /content/my-example.html é acessado, 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 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>