Personalizar a Camada de dados do cliente Adobe com componentes AEM customize-data-layer

Saiba como personalizar a Camada de dados do cliente Adobe com conteúdo de componentes AEM personalizados. Saiba como usar APIs fornecidas pelos Componentes principais do AEM para estender e personalizar a camada de dados.

O que você vai criar

Camada de dados de byline

Neste tutorial, vamos explorar várias opções para estender a Camada de dados do cliente Adobe, atualizando o Componente de byline da WKND. O componente Subtítulo é um componente personalizado e as lições aprendidas neste tutorial podem ser aplicadas a outros componentes personalizados.

Objetivos objective

  1. Insira dados do componente na camada de dados estendendo um Modelo Sling e o componente HTL
  2. Usar utilitários de camada de dados dos Componentes principais para reduzir o esforço
  3. Usar atributos de dados do Componente principal para conectar-se aos eventos existentes da camada de dados

Pré-requisitos prerequisites

É necessário um ambiente de desenvolvimento local para concluir este tutorial. Capturas de tela e vídeos são capturados usando o SDK do AEM as a Cloud Service em execução em uma macOS. Os comandos e o código são independentes do sistema operacional local, a menos que indicado de outra forma.

Novo no AEM as a Cloud Service? Consulte o guia a seguir para configurar um ambiente de desenvolvimento local usando o SDK do AEM as a Cloud Service.

Novo no AEM 6.5? Consulte o guia a seguir para configurar um ambiente de desenvolvimento local.

Baixar e implantar o site de referência WKND set-up-wknd-site

Este tutorial estende o componente Subtítulo no site de referência WKND. Clonar e instalar a base de código WKND em seu ambiente local.

  1. Inicie uma instância de AEM do Quickstart author local em execução em http://localhost:4502.

  2. Abra uma janela de terminal e clone a base de código WKND usando Git:

    code language-shell
    $ git clone git@github.com:adobe/aem-guides-wknd.git
    
  3. Implante a base de código WKND em uma instância local de AEM:

    code language-shell
    $ cd aem-guides-wknd
    $ mvn clean install -PautoInstallSinglePackage
    
    note note
    NOTE
    Para o AEM 6.5 e o pacote de serviços mais recente, adicione o perfil classic ao comando Maven:
    mvn clean install -PautoInstallSinglePackage -Pclassic
  4. Abra uma nova janela do navegador e faça logon no AEM. Abra uma página de Revista como: http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

    Componente de Subtítulo na Página

    Você deve ver um exemplo do componente Subtítulo que foi adicionado à página como parte de um Fragmento de experiência. Você pode exibir o Fragmento de experiência em http://localhost:4502/editor.html/content/experience-fragments/wknd/language-masters/en/contributors/stacey-roswells/byline.html

  5. Abra as ferramentas do desenvolvedor e digite o seguinte comando no Console:

    code language-js
    window.adobeDataLayer.getState();
    

    Para ver o estado atual da camada de dados em um site AEM, inspecione a resposta. Você deve ver informações sobre a página e os componentes individuais.

    Resposta da Camada de Dados Adobe

    Observe que o componente Subtítulo não está listado na Camada de dados.

Atualizar o modelo Sling de byline sling-model

Para inserir dados sobre o componente na camada de dados, primeiro vamos atualizar o Modelo Sling do componente. Em seguida, atualize a interface Java™ do Byline e a implementação do Modelo Sling para ter um novo método getData(). Esse método contém as propriedades a serem inseridas na camada de dados.

  1. Abra o projeto aem-guides-wknd no IDE de sua escolha. Navegue até o módulo core.

  2. Abra o arquivo Byline.java em core/src/main/java/com/adobe/aem/guides/wknd/core/models/Byline.java.

    Byline Java Interface

  3. Adicionar o método abaixo à interface:

    code language-java
    public interface Byline {
        ...
        /***
         * Return data about the Byline Component to populate the data layer
         * @return String
         */
        String getData();
    }
    
  4. Abra o arquivo BylineImpl.java em core/src/main/java/com/adobe/aem/guides/wknd/core/models/impl/BylineImpl.java. É a implementação da interface Byline e é implementada como um Modelo Sling.

  5. Adicione as seguintes instruções de importação no início do arquivo:

    code language-java
    import java.util.HashMap;
    import java.util.Map;
    import org.apache.sling.api.resource.Resource;
    import com.fasterxml.jackson.core.JsonProcessingException;
    import com.fasterxml.jackson.databind.ObjectMapper;
    import com.adobe.cq.wcm.core.components.util.ComponentUtils;
    

    As APIs fasterxml.jackson são usadas para serializar os dados a serem expostos como JSON. O ComponentUtils dos Componentes principais do AEM são usados para verificar se a camada de dados está habilitada.

  6. Adicionar o método não implementado getData() a BylineImple.java:

    code language-java
    public class BylineImpl implements Byline {
        ...
        @Override
        public String getData() {
            Resource bylineResource = this.request.getResource();
            // Use ComponentUtils to verify if the DataLayer is enabled
            if (ComponentUtils.isDataLayerEnabled(bylineResource)) {
    
                //Create a map of properties we want to expose
                Map<String, Object> bylineProperties = new HashMap<String,Object>();
                bylineProperties.put("@type", bylineResource.getResourceType());
                bylineProperties.put("name", this.getName());
                bylineProperties.put("occupation", this.getOccupations());
                bylineProperties.put("fileReference", image.getFileReference());
    
                //Use AEM Core Component utils to get a unique identifier for the Byline component (in case multiple are on the page)
                String bylineComponentID = ComponentUtils.getId(bylineResource, this.currentPage, this.componentContext);
    
                // Return the bylineProperties as a JSON String with a key of the bylineResource's ID
                try {
                    return String.format("{\"%s\":%s}",
                        bylineComponentID,
                        // Use the ObjectMapper to serialize the bylineProperties to a JSON string
                        new ObjectMapper().writeValueAsString(bylineProperties));
                } catch (JsonProcessingException e) {
    
                    LOGGER.error("Unable to generate dataLayer JSON string", e);
                }
    
            }
            // return null if the Data Layer is not enabled
            return null;
        }
    }
    

    No método acima, um novo HashMap é usado para capturar as propriedades a serem expostas como JSON. Observe que métodos existentes como getName() e getOccupations() são usados. O @type representa o tipo de recurso exclusivo do componente. Ele permite que um cliente identifique eventos e/ou acionadores facilmente com base no tipo de componente.

    O ObjectMapper é usado para serializar as propriedades e retornar uma cadeia de caracteres JSON. Essa cadeia de caracteres JSON pode ser inserida na camada de dados.

  7. Abra uma janela de terminal. Crie e implante apenas o módulo core usando suas habilidades Maven:

    code language-shell
    $ cd aem-guides-wknd/core
    $ mvn clean install -PautoInstallBundle
    

Atualizar o HTL do byline htl

Em seguida, atualize o Byline HTL. HTL (Linguagem de modelo de HTML) é o modelo usado para renderizar o HTML do componente.

Um atributo de dados especial data-cmp-data-layer em cada componente do AEM é usado para expor sua camada de dados. O JavaScript fornecido pelos Componentes principais AEM procura esse atributo de dados. O valor desse atributo de dados é preenchido com a Cadeia de caracteres JSON retornada pelo método getData() do Modelo Sling de byline e inserida na camada de Dados do cliente Adobe.

  1. Abra o projeto aem-guides-wknd no IDE. Navegue até o módulo ui.apps.

  2. Abra o arquivo byline.html em ui.apps/src/main/content/jcr_root/apps/wknd/components/byline/byline.html.

    HTML de Linha

  3. Atualize byline.html para incluir o atributo data-cmp-data-layer:

    code language-diff
      <div data-sly-use.byline="com.adobe.aem.guides.wknd.core.models.Byline"
        data-sly-use.placeholderTemplate="core/wcm/components/commons/v1/templates.html"
        data-sly-test.hasContent="${!byline.empty}"
    +   data-cmp-data-layer="${byline.data}"
        class="cmp-byline">
        ...
    

    O valor de data-cmp-data-layer foi definido como "${byline.data}", onde byline é o Modelo Sling atualizado anteriormente. .data é a notação padrão para chamar um método Getter Java™ no HTL de getData() implementado no exercício anterior.

  4. Abra uma janela de terminal. Crie e implante apenas o módulo ui.apps usando suas habilidades Maven:

    code language-shell
    $ cd aem-guides-wknd/ui.apps
    $ mvn clean install -PautoInstallPackage
    
  5. Retorne ao navegador e reabra a página com um componente Subtítulo: http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

  6. Abra as ferramentas do desenvolvedor e inspecione o código-fonte HTML da página para o componente Subtítulo:

    Camada de dados de byline

    Você deve ver que data-cmp-data-layer foi preenchido com a sequência JSON do modelo Sling.

  7. Abra as ferramentas de desenvolvedor do navegador e digite o seguinte comando no Console:

    code language-js
    window.adobeDataLayer.getState();
    
  8. Navegue abaixo da resposta em component para descobrir se a instância do componente byline foi adicionada à camada de dados:

    Parte da sublinha da camada de dados

    Você deve ver uma entrada como a seguinte:

    code language-json
    byline-136073cfcb:
        @type: "wknd/components/byline"
        fileReference: "/content/dam/wknd/en/contributors/stacey-roswells.jpg"
        name: "Stacey Roswells"
        occupation: (3) ["Artist", "Photographer", "Traveler"]
        parentId: "page-30d989b3f8"
    

    Observe que as propriedades expostas são as mesmas adicionadas em HashMap no Modelo Sling.

Adicionar um evento de clique click-event

A Camada de Dados de Clientes Adobe é orientada por eventos e um dos eventos mais comuns para disparar uma ação é o evento cmp:click. Os Componentes principais do AEM facilitam o registro do componente com a ajuda do elemento de dados: data-cmp-clickable.

Os elementos clicáveis geralmente são um botão CTA ou um link de navegação. Infelizmente, o componente Subtítulo não tem nenhum desses, mas vamos registrá-lo de qualquer maneira, pois isso pode ser comum para outros componentes personalizados.

  1. Abra o módulo ui.apps no IDE

  2. Abra o arquivo byline.html em ui.apps/src/main/content/jcr_root/apps/wknd/components/byline/byline.html.

  3. Atualize byline.html para incluir o atributo data-cmp-clickable no elemento name da linha de dados:

    code language-diff
      <h2 class="cmp-byline__name"
    +    data-cmp-clickable="${byline.data ? true : false}">
         ${byline.name}
      </h2>
    
  4. Abra um novo terminal. Crie e implante apenas o módulo ui.apps usando suas habilidades Maven:

    code language-shell
    $ cd aem-guides-wknd/ui.apps
    $ mvn clean install -PautoInstallPackage
    
  5. Retorne ao navegador e reabra a página com o componente Subtítulo adicionado: http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

    Para testar nosso evento, adicionaremos manualmente alguns JavaScript usando o console do desenvolvedor. Consulte Usando a Camada de Dados do Cliente Adobe com Componentes Principais AEM para ver um vídeo sobre como fazer isso.

  6. Abra as ferramentas de desenvolvedor do navegador e insira o seguinte método no Console:

    code language-javascript
    function bylineClickHandler(event) {
        var dataObject = window.adobeDataLayer.getState(event.eventInfo.path);
        if (dataObject != null && dataObject['@type'] === 'wknd/components/byline') {
            console.log("Byline Clicked!");
            console.log("Byline name: " + dataObject['name']);
        }
    }
    

    Este método simples deve lidar com o clique do nome do componente Subtítulo.

  7. Digite o seguinte método no Console:

    code language-javascript
    window.adobeDataLayer.push(function (dl) {
         dl.addEventListener("cmp:click", bylineClickHandler);
    });
    

    O método acima envia um ouvinte de eventos para a camada de dados para ouvir o evento cmp:click e chama bylineClickHandler.

    note caution
    CAUTION
    É importante não atualizar o navegador durante todo este exercício, caso contrário, o JavaScript do console será perdido.
  8. No navegador, com o Console aberto, clique no nome do autor no componente Subtítulo:

    Componente de byline clicado

    Você deve ver a mensagem de console Byline Clicked! e o nome de Subtítulo.

    O evento cmp:click é o mais fácil de conectar. Para componentes mais complexos e rastrear outros comportamentos, é possível adicionar um JavaScript personalizado para adicionar e registrar novos eventos. Um ótimo exemplo é o componente Carrossel, que aciona um evento cmp:show sempre que um slide é alternado. Consulte o código-fonte para obter mais detalhes.

Usar o utilitário DataLayerBuilder data-layer-builder

Quando o Modelo Sling foi atualizado anteriormente no capítulo, optamos por criar a Cadeia de caracteres JSON usando um HashMap e definindo cada uma das propriedades manualmente. Esse método funciona bem para componentes únicos pequenos, no entanto, para componentes que estendem os Componentes principais do AEM, isso pode resultar em muito código extra.

Uma classe de utilitário, DataLayerBuilder, existe para executar a maior parte do trabalho pesado. Isso permite que as implementações estendam apenas as propriedades que desejam. Vamos atualizar o Modelo do Sling para usar o DataLayerBuilder.

  1. Retorne ao IDE e navegue até o módulo core.

  2. Abra o arquivo Byline.java em core/src/main/java/com/adobe/aem/guides/wknd/core/models/Byline.java.

  3. Modifique o método getData() para retornar um tipo de ComponentData

    code language-java
    import com.adobe.cq.wcm.core.components.models.datalayer.ComponentData;
    ...
    public interface Byline {
        ...
        /***
         * Return data about the Byline Component to populate the data layer
         * @return ComponentData
         */
        ComponentData getData();
    }
    

    ComponentData é um objeto fornecido pelos Componentes principais do AEM. Ele resulta em uma sequência JSON, como no exemplo anterior, mas também executa muito trabalho adicional.

  4. Abra o arquivo BylineImpl.java em core/src/main/java/com/adobe/aem/guides/wknd/core/models/impl/BylineImpl.java.

  5. Adicione as seguintes instruções de importação:

    code language-java
    import com.adobe.cq.wcm.core.components.models.datalayer.ComponentData;
    import com.adobe.cq.wcm.core.components.models.datalayer.builder.DataLayerBuilder;
    
  6. Substitua o método getData() pelo seguinte:

    code language-java
    @Override
    public ComponentData getData() {
        Resource bylineResource = this.request.getResource();
        // Use ComponentUtils to verify if the DataLayer is enabled
        if (ComponentUtils.isDataLayerEnabled(bylineResource)) {
    
            return DataLayerBuilder.extending(getImage().getData()).asImageComponent()
                .withTitle(this::getName)
                .build();
    
        }
        // return null if the Data Layer is not enabled
        return null;
    }
    

    O componente Subtítulo reutiliza partes do Componente principal de imagem para exibir uma imagem representando o autor. No trecho acima, o DataLayerBuilder é usado para estender a camada de dados do componente Image. Isso preenche o objeto JSON previamente com todos os dados sobre a imagem usada. Também executa algumas funções de rotina, como definir o @type e o identificador exclusivo do componente. Observe que o método é pequeno!

    A única propriedade estendeu o withTitle, que é substituído pelo valor de getName().

  7. Abra uma janela de terminal. Crie e implante apenas o módulo core usando suas habilidades Maven:

    code language-shell
    $ cd aem-guides-wknd/core
    $ mvn clean install -PautoInstallBundle
    
  8. Retorne ao IDE e abra o arquivo byline.html em ui.apps

  9. Atualize o HTL para usar byline.data.json para popular o atributo data-cmp-data-layer:

    code language-diff
      <div data-sly-use.byline="com.adobe.aem.guides.wknd.core.models.Byline"
        data-sly-use.placeholderTemplate="core/wcm/components/commons/v1/templates.html"
        data-sly-test.hasContent="${!byline.empty}"
    -   data-cmp-data-layer="${byline.data}"
    +   data-cmp-data-layer="${byline.data.json}"
    

    Lembre-se de que agora estamos retornando um objeto do tipo ComponentData. Este objeto inclui um método getter getJson() e é usado para preencher o atributo data-cmp-data-layer.

  10. Abra uma janela de terminal. Crie e implante apenas o módulo ui.apps usando suas habilidades Maven:

    code language-shell
    $ cd aem-guides-wknd/ui.apps
    $ mvn clean install -PautoInstallPackage
    
  11. Retorne ao navegador e reabra a página com o componente Subtítulo adicionado: http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

  12. Abra as ferramentas de desenvolvedor do navegador e digite o seguinte comando no Console:

    code language-js
    window.adobeDataLayer.getState();
    
  13. Navegue abaixo da resposta em component para localizar a instância do componente byline:

    Camada de dados de byline atualizada

    Você deve ver uma entrada como a seguinte:

    code language-json
    byline-136073cfcb:
        @type: "wknd/components/byline"
        dc:title: "Stacey Roswells"
        image:
            @type: "image/jpeg"
            repo:id: "142658f8-4029-4299-9cd6-51afd52345c0"
            repo:modifyDate: "2019-10-25T23:49:51Z"
            repo:path: "/content/dam/wknd/en/contributors/stacey-roswells.jpg"
            xdm:tags: []
        parentId: "page-30d989b3f8"
        repo:modifyDate: "2019-10-18T20:17:24Z"
    

    Observe que agora há um objeto image dentro da entrada de componente byline. Há muito mais informações sobre o ativo no DAM. Observe também que @type e a ID exclusiva (neste caso, byline-136073cfcb) foram automaticamente preenchidas, e a repo:modifyDate que indica quando o componente foi modificado.

Exemplos adicionais additional-examples

  1. Outro exemplo de extensão da camada de dados pode ser visualizado ao inspecionar o componente ImageList na base de código WKND:

    • ImageList.java - Interface Java no módulo core.
    • ImageListImpl.java - Modelo Sling no módulo core.
    • image-list.html - Modelo HTL no módulo ui.apps.
    note note
    NOTE
    É um pouco mais difícil incluir propriedades personalizadas como occupation ao usar o DataLayerBuilder. No entanto, se estender um Componente principal que inclua uma Imagem ou Página, o utilitário economiza muito tempo.
    note note
    NOTE
    Se estiver criando uma Camada de dados avançada para objetos reutilizados em uma implementação, é recomendável extrair os elementos da Camada de dados em seus próprios objetos Java™ específicos da camada de dados. Por exemplo, os Componentes Principais do Commerce adicionaram interfaces para ProductData e CategoryData já que eles podem ser usados em muitos componentes dentro de uma implementação do Commerce. Revise o código no repositório aem-CIF-core-components para obter mais detalhes.

Parabéns. congratulations

Você acabou de explorar algumas maneiras de estender e personalizar a Camada de dados do cliente Adobe com componentes AEM!

Recursos adicionais additional-resources

recommendation-more-help
bb44cebf-d964-4e3c-b64e-ce882243fe4d