Personalizar os Componentes principais da CIF do AEM

O CIF Venia Project é uma base de códigos de referência para o uso de CIF Componentes Principais. Neste tutorial, você estenderá ainda mais o componente Teaser de produto para exibir um atributo personalizado do Magento. Você também aprenderá mais sobre a integração do GraphQL entre o AEM e o Magento e os ganchos de extensão fornecidos pelos Componentes principais CIF.

DICA

Use o AEM Tipo de arquivo do projeto ao iniciar sua própria implementação de comércio.

O que você vai criar

A marca Venia começou recentemente a fabricar alguns produtos usando materiais sustentáveis e a empresa gostaria de exibir um crachá Eco Friendly como parte do Teaser do Produto. Um novo atributo personalizado será criado no Magento para indicar se um produto usa o material eco-amigável. Esse atributo personalizado será então adicionado como parte do query GraphQL e exibido no Teaser de produto para produtos especificados.

Implementação final do selo ecológico

Pré-requisitos

É necessário um ambiente de desenvolvimento local para concluir este tutorial. Isso inclui uma instância em execução de AEM configurada e conectada a uma instância Magento. Revise os requisitos e as etapas para configurar um desenvolvimento local com AEM como um SDK Cloud Service. Para seguir o tutorial completamente, você precisará de permissões para adicionar Atributos a um Produto no Magento.

Você também precisará do GraphQL IDE como GraphiQL ou de uma extensão do navegador para executar as amostras de código e os tutoriais. Se você instalar uma extensão do navegador, verifique se ele tem a capacidade de definir cabeçalhos de solicitação. No Google Chrome, Altair GraphQL Client é uma extensão que pode fazer o trabalho.

Clonar o projeto Venia

Vamos clonar o Projeto Venia e depois substituir os estilos padrão.

Observação

Sinta-se à vontade para usar um projeto existente (com base no AEM Project Archetype com CIF incluído) e ignore esta seção.

  1. Execute o seguinte comando git para clonar o projeto:

    $ git clone git@github.com:adobe/aem-cif-guides-venia.git
    
  2. Crie e implante o projeto em uma instância local do AEM:

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallPackage,cloud
    
  3. Adicione as configurações OSGi necessárias para conectar a instância do AEM a uma instância da Magento ou adicione as configurações ao projeto recém-criado.

  4. Nesta etapa, já deve estar funcionando uma versão de loja conectada a uma instância da Magento. Navegue até a página US > Home em: http://localhost:4502/editor.html/content/venia/us/en.html.

    Você verá que a loja está usando o tema Venia. Ao expandir o Menu principal da loja você verá várias categorias, que é um sinal de que a conexão com a Magento está funcionando.

    Storefront Configurado com o Tema de Venia

Criação do Teaser do produto

O componente Teaser do produto será estendido por todo este tutorial. Como primeira etapa, adicione uma nova instância do Teaser de produto ao Home page para entender a funcionalidade da linha de base.

  1. Acesse a página inicial do site: http://localhost:4502/editor.html/content/acme/us/en.html

  2. Insira um novo Teaser do produto no container do layout principal da página.

    Inserir Teaser do produto

  3. Expanda o painel lateral (se ainda não estiver sendo exibido) e na lista suspensa do localizador de ativos selecione Produtos. Essa ação deve exibir uma lista de produtos disponíveis em uma instância conectada da Magento. Selecione, arraste e solte um produto no Teaser do produto exibido na página.

    Arrastar e soltar Teaser do produto

    Observação

    Observação: você também pode configurar o produto exibido definindo o componente na caixa de diálogo (clicando na chave inglesa).

  4. Agora você já deve estar vendo um produto no teaser. O nome e o preço do produto são atributos exibidos por padrão.

    Teaser do produto — estilo padrão

Adicionar um atributo personalizado em Magento

Os produtos e os dados do produto exibidos no AEM são armazenados no Magento. Em seguida, adicione um novo atributo para Eco Friendly como parte do conjunto de atributos do produto usando a interface do Magento.

DICA

Já tem um atributo personalizado Yes/No como parte do conjunto de atributos do produto? Sinta-se à vontade para usá-lo e ignore esta seção.

  1. Faça logon na sua instância do Magento.

  2. Navegue até Catálogo > Produtos.

  3. Atualize o filtro de pesquisa para localizar o Produto Configurável usado quando adicionado ao componente Teaser no exercício anterior. Abra o produto no modo de edição.

    Busca pelo produto Valeria

  4. Na visualização do produto, clique em Adicionar atributo > Criar novo atributo.

  5. Preencha o formulário Novo Atributo com os seguintes valores (deixe as configurações padrão para outros valores)

    Conjunto de campos Rótulo do campo Valor
    Propriedades do atributo Rótulo do atributo Ecológico
    Propriedades do atributo Tipo de entrada do catálogo Sim/Não
    Propriedades avançadas de atributos Código do atributo eco_friendly

    Novo formulário de atributo

    Clique em Salvar atributo quando terminar.

  6. Role até a parte inferior do produto e expanda o cabeçalho Atributos. Você deve ver o novo campo Ecológico. Alterne a alternância para Yes.

    Alternar alternância para yes

    ​Salve as alterações no produto.

  7. Navegue até Sistema > Ferramentas > Gerenciamento de cache. Como foi feita uma atualização no schema de dados, precisamos invalidar alguns dos tipos de cache no Magento.

  8. Marque a caixa ao lado de Configuração e envie o tipo de cache para Atualizar

    Atualizar Tipo de Cache de Configuração

    DICA

Use um GraphQL IDE para verificar o atributo

Antes de pular para AEM código, é útil explorar o Magento GraphQL usando um GraphQL IDE. A integração do Magento com o AEM é feita principalmente por meio de uma série de query GraphQL. Compreender e modificar os query GraphQL é uma das principais maneiras pelas quais os Componentes Principais CIF podem ser estendidos.

Em seguida, use um GraphQL IDE para verificar se o atributo eco_friendly foi adicionado ao conjunto de atributos do produto. As capturas de tela neste tutorial estão usando o Altair GraphQL Client.

  1. Abra o GraphQL IDE e insira o URL http://<magento-server>/graphql na barra de URL do IDE ou da extensão.

  2. Adicione o seguinte query products onde YOUR_SKU é o SKU do produto utilizado no exercício anterior:

      {
        products(
        filter: { sku: { eq: "YOUR_SKU" } }
        ) {
            items {
            name
            sku
            eco_friendly
            }
        }
    }
    
  3. Execute o query e você deverá obter uma resposta como a seguinte:

    {
    "data": {
        "products": {
            "items": [
                {
                "name": "Valeria Two-Layer Tank",
                "sku": "VT11",
                "eco_friendly": 1
                }
            ]
            }
        }
    }
    

    Exemplo de resposta GraphQL

    Observe que o valor de Yes é um número inteiro de 1. Isso será útil quando gravarmos o query GraphQL no Java.

    DICA

    Documentação mais detalhada sobre Magento GraphQL pode ser encontrada aqui.

Atualize o Modelo Sling para o Teaser do Produto

A seguir, estenderemos a lógica de negócios do Teaser do produto implementando um Modelo do Sling. Os Modelos do Sling são objetos POJO (Plain Old Java Objects) orientados por anotações que implementam qualquer lógica de negócios exigida pelo componente. Modelos do Sling são usados junto com os scripts HTL como parte do componente. Seguiremos o padrão de delegação para Modelos do Sling para que possamos estender partes do modelo existente do Teaser do produto.

Os Modelos do Sling são implementados como Java e podem ser encontrados no módulo principal do projeto gerado.

Use o IDE de sua escolha para importar o projeto Venia. As capturas de tela usadas são do código do Visual Studio IDE.

  1. No IDE, navegue sob o módulo core para: core/src/main/java/com/venia/core/models/commerce/MyProductTeaser.java.

    IDE de localização principal

    MyProductTeaser.java é uma interface Java que estende a interface CIF ProductTeaserinterface.

    Já foi adicionado um novo método chamado isShowBadge() para exibir um selo se o produto for considerado "Novo".

  2. Adicione um novo método isEcoFriendly() à interface:

    @ProviderType
    public interface MyProductTeaser extends ProductTeaser {
        // Extend the existing interface with the additional properties which you
        // want to expose to the HTL template.
        public Boolean isShowBadge();
    
        public Boolean isEcoFriendly();
    }
    

    Este é um novo método que introduziremos para encapsular a lógica para indicar se o produto tem o atributo eco_friendly definido como Yes ou No.

  3. Em seguida, inspecione MyProductTeaserImpl.java em core/src/main/java/com/venia/core/models/commerce/MyProductTeaserImpl.java.

    O padrão de delegação para Modelos Sling permite que MyProductTeaserImpl faça referência ao modelo ProductTeaser através da propriedade sling:resourceSuperType:

    @Self
    @Via(type = ResourceSuperType.class)
    private ProductTeaser productTeaser;
    

    Para todos os métodos que não queremos substituir ou alterar, podemos simplesmente retornar o valor que o ProductTeaser retorna. Por exemplo:

    @Override
    public String getImage() {
        return productTeaser.getImage();
    }
    

    Isso minimiza a quantidade de código Java que uma implementação precisa gravar.

  4. Um dos pontos de extensão adicionais fornecidos pela AEM CIF Core Components é o AbstractProductRetriever que fornece acesso a atributos específicos do produto. Inspect o método initModel():

    import javax.annotation.PostConstruct;
    ...
    @Model(adaptables = SlingHttpServletRequest.class, adapters = MyProductTeaser.class, resourceType = MyProductTeaserImpl.RESOURCE_TYPE)
    public class MyProductTeaserImpl implements MyProductTeaser {
        ...
        private AbstractProductRetriever productRetriever;
    
        /* add this method to intialize the proudctRetriever */
        @PostConstruct
        public void initModel() {
            productRetriever = productTeaser.getProductRetriever();
    
            if (productRetriever != null) {
                productRetriever.extendProductQueryWith(p -> p.createdAt());
            }
    
        }
    ...
    

    A anotação @PostConstruct garante que esse método seja chamado assim que o Modelo Sling for inicializado.

    Observe que o query GraphQL do produto já foi estendido usando o método extendProductQueryWith para recuperar o atributo created_at adicional. Este atributo é usado posteriormente como parte do método isShowBadge().

  5. Atualize o query GraphQL para incluir o atributo eco_friendly no query parcial:

    //MyProductTeaserImpl.java
    
    private static final String ECO_FRIENDLY_ATTRIBUTE = "eco_friendly";
    
    @PostConstruct
    public void initModel() {
        productRetriever = productTeaser.getProductRetriever();
    
        if (productRetriever != null) {
            productRetriever.extendProductQueryWith(p ->
                 productRetriever.extendProductQueryWith(p -> p
                    .createdAt()
                    .addCustomSimpleField(ECO_FRIENDLY_ATTRIBUTE)
                );
            );
        }
    }
    

    Atualizar o método extendProductQueryWith é uma maneira eficiente de garantir que atributos de produto adicionais estejam disponíveis para o restante do modelo. Essa ação também minimiza o número de consultas executadas.

    No código acima, addCustomSimpleField é usado para recuperar o atributo eco_friendly. Isso ilustra como você pode consultar qualquer atributo personalizado que faça parte do esquema da Magento.

    Observação

    O método createdAt() foi implementado como parte da Interface do Produto. A maioria dos atributos de esquema encontrados com frequência foram implementados, portanto, use addCustomSimpleField somente para atributos verdadeiramente personalizados.

  6. Adicione um agente de log para ajudar a depurar o código Java:

    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    ...
    @Model(adaptables = SlingHttpServletRequest.class, adapters = MyProductTeaser.class, resourceType = MyProductTeaserImpl.RESOURCE_TYPE)
    public class MyProductTeaserImpl implements MyProductTeaser {
    
    private static final Logger LOGGER = LoggerFactory.getLogger(MyProductTeaserImpl.class);
    
  7. Em seguida, implemente o método isEcoFriendly():

    @Override
    public Boolean isEcoFriendly() {
    
        Integer ecoFriendlyValue;
        try {
            ecoFriendlyValue = productRetriever.fetchProduct().getAsInteger(ECO_FRIENDLY_ATTRIBUTE);
            if(ecoFriendlyValue != null && ecoFriendlyValue.equals(Integer.valueOf(1))) {
                LOGGER.info("*** Product is Eco Friendly**");
                return true;
            }
        } catch (SchemaViolationError e) {
            LOGGER.error("Error retrieving eco friendly attribute");
        }
        LOGGER.info("*** Product is not Eco Friendly**");
        return false;
    }
    

    No método acima, productRetriever é usado para buscar o produto e o método getAsInteger() é usado para obter o valor do atributo eco_friendly. Com base nos query GraphQL que executamos anteriormente, sabemos que o valor esperado quando o atributo eco_friendly está definido como "Yes" é na verdade um número inteiro de 1.

    Agora que o Modelo Sling foi atualizado, a marcação Componente precisa ser atualizada para realmente exibir um indicador de Amigável ao Ambiente com base no Modelo Sling.

Personalização da marcação do Teaser do produto

Uma extensão comum de componentes do AEM é modificar a marcação gerada pelo componente. Essa modificação é feita substituindo o script HTL que o componente usa para renderizar sua marcação. A Linguagem de modelo HTML (HTL) é uma linguagem de modelo leve que os componentes do AEM usam para renderizar dinamicamente a marcação com base no conteúdo criado, permitindo que os componentes sejam reutilizados. O Teaser do produto, por exemplo, pode ser reutilizado várias vezes para exibir produtos diferentes.

Em nosso caso, queremos renderizar um banner sobre o teaser para indicar que o produto é "Ecológico" com base em um atributo personalizado. O padrão de design para personalizar a marcação de um componente é, na verdade, padrão para todos os componentes do AEM, não apenas para os Componentes principais da CIF do AEM.

  1. No IDE, navegue e expanda o módulo ui.apps e expanda a hierarquia de pastas para: ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser e inspecione o arquivo .content.xml.

    User.apps do Teaser do produto

    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
        jcr:description="Product Teaser Component"
        jcr:primaryType="cq:Component"
        jcr:title="Product Teaser"
        sling:resourceSuperType="core/cif/components/commerce/productteaser/v1/productteaser"
        componentGroup="Venia - Commerce"/>
    

    Veja acima a definição de componente para o Teaser do produto em nosso projeto. Observe a propriedade sling:resourceSuperType="core/cif/components/commerce/productteaser/v1/productteaser". Este é um exemplo de criação de um componente Proxy. Em vez de copiar e colar todos os scripts HTL do Teaser do produto dos Componentes principais da CIF do AEM, podemos usar o sling:resourceSuperType para herdar toda a funcionalidade.

  2. Abra o arquivo productteaser.html. Esta é uma cópia do arquivo productteaser.html do CIF Product Teaser

    <!--/* productteaser.html */-->
    <sly data-sly-use.product="com.venia.core.models.commerce.MyProductTeaser"
        data-sly-use.templates="core/wcm/components/commons/v1/templates.html"
        data-sly-use.actionsTpl="actions.html"
        data-sly-test.isConfigured="${properties.selection}"
        data-sly-test.hasProduct="${product.url}">
    

    Observe que o Modelo Sling para MyProductTeaser é usado e atribuído à variável product.

  3. Modifique productteaser.html para fazer uma chamada para o método isEcoFriendly implementado no exercício anterior:

    ...
    <div data-sly-test="${isConfigured && hasProduct}" class="item__root" data-cmp-is="productteaser" data-virtual="${product.virtualProduct}">
        <div data-sly-test="${product.showBadge}" class="item__badge">
            <span>${properties.text || 'New'}</span>
        </div>
        <!--/* Insert call to Eco Friendly here */-->
        <div data-sly-test="${product.ecoFriendly}" class="item__eco">
            <span>Eco Friendly</span>
        </div>
    ...
    

    Ao chamar um método do Modelo Sling em HTL, a parte get e is do método é removida e a primeira letra tem minúsculas. Então isShowBadge() se torna .showBadge e isEcoFriendly se torna .ecoFriendly. Com base no valor booliano retornado de .isEcoFriendly() determina se <span>Eco Friendly</span> é exibido.

    Mais informações sobre data-sly-test e outras instruções de bloco HTL podem ser encontradas aqui.

  4. Salve as alterações e implante as atualizações para AEM usando suas habilidades Maven, a partir de um terminal de linha de comando:

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallPackage,cloud
    
  5. Abra uma nova janela do navegador e navegue até AEM e console OSGi > Status > Modelos Sling: http://localhost:4502/system/console/status-slingmodels

  6. Procure MyProductTeaserImpl e você deverá ver uma linha como a seguinte:

    com.venia.core.models.commerce.MyProductTeaserImpl - venia/components/commerce/productteaser
    

    Isso indica que o Modelo Sling foi implantado e mapeado corretamente para o componente correto.

  7. Atualize para o Home page Venia em http://localhost:4502/editor.html/content/venia/us/en.html onde o Teaser de produto foi adicionado.

    Aparece a mensagem eco-amigável

    Se o produto tiver o atributo eco_friendly definido como Yes, você deverá ver o texto "Eco Friendly" na página. Tente alternar para produtos diferentes para ver a mudança de comportamento.

  8. Em seguida, abra o AEM error.log para ver as declarações de log que adicionamos. O error.log está localizado em <AEM SDK Install Location>/crx-quickstart/logs/error.log.

    Pesquise nos registros de AEM para ver as declarações de log adicionadas no Sling Model:

    2020-08-28 12:57:03.114 INFO [com.venia.core.models.commerce.MyProductTeaserImpl] *** Product is Eco Friendly**
    ...
    2020-08-28 13:01:00.271 INFO [com.venia.core.models.commerce.MyProductTeaserImpl] *** Product is not Eco Friendly**
    ...
    
    CUIDADO

    Você também pode ver alguns rastreamentos de pilha se o produto usado no teaser não tiver o atributo eco_friendly como parte do conjunto de atributos dele.

Adicionar estilos ao selo eco-amigável

Nesse ponto, a lógica para quando exibir o símbolo Eco Friendly está funcionando, no entanto, o texto sem formatação pode usar alguns estilos. Em seguida, adicione um ícone e estilos ao módulo ui.frontend para concluir a implementação.

  1. Baixe o arquivo eco_friendly.svg. Isso será usado como o símbolo Eco Friendly.

  2. Retorne ao IDE e navegue até a pasta ui.frontend.

  3. Adicione o arquivo eco_friendly.svg à pasta ui.frontend/src/main/resources/images:

    SVG eco-amigável adicionado

  4. Abra o arquivo productteaser.scss em ui.frontend/src/main/styles/commerce/_productteaser.scss.

  5. Adicione as seguintes regras Sass dentro da classe .productteaser:

    .productteaser {
        ...
        .item__eco {
            width: 60px;
            height: 60px;
            left: 0px;
            overflow: hidden;
            position: absolute;
            padding: 5px;
    
        span {
            display: block;
            position: absolute;
            width: 45px;
            height: 45px;
            text-indent: -9999px;
            background: no-repeat center center url('../resources/images/eco_friendly.svg'); 
            }
        }
    ...
    }
    
    Observação

    Consulte Styling CIF Core Components para obter mais detalhes sobre os workflows front-end.

  6. Salve as alterações e implante as atualizações para AEM usando suas habilidades Maven, a partir de um terminal de linha de comando:

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallPackage,cloud
    
  7. Atualize para o Home page Venia em http://localhost:4502/editor.html/content/venia/us/en.html onde o Teaser de produto foi adicionado.

    Implementação final do selo ecológico

Parabéns

Você acabou de personalizar seu primeiro componente CIF do AEM. Baixe os arquivos de solução finalizados aqui.

Desafio extra

Analise a funcionalidade do símbolo New que já foi implementado no Teaser do Produto. Tente adicionar uma caixa de seleção adicional para que os autores controlem quando o símbolo Eco Friendly deve ser exibido. Será necessário atualizar a caixa de diálogo do componente em ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser/_cq_dialog/.content.xml.

Novo desafio de implementação de emblema

Recursos adicionais

Nesta página