Personalización de los componentes principales del CIF de AEM

La variable Proyecto de CIF Venia es una base de código de referencia para usar Componentes principales de CIF. En este tutorial, ampliará aún más la variable Teaser de productos para mostrar un atributo personalizado de Adobe Commerce. También obtendrá más información sobre la integración de GraphQL entre AEM y Adobe Commerce y los enlaces de extensión proporcionados por los componentes principales del CIF.

SUGERENCIA

Utilice la variable AEM tipo de archivo del proyecto al iniciar su propia implementación de comercio.

Qué va a generar

La marca Venia comenzó recientemente a fabricar algunos productos utilizando materiales sostenibles y la empresa quiere mostrar un Compatible con el ecosistema distintivo como parte del teaser de productos. Se creará un nuevo atributo personalizado en Adobe Commerce para indicar si un producto usa la variable Eco amigable material. Este atributo personalizado se agregará como parte de la consulta de GraphQL y se mostrará en el teaser de productos de los productos especificados.

Implementación Final De Distintivo Compatible Con Eco

Requisitos previos

Se requiere un entorno de desarrollo local para completar este tutorial. Esto incluye una instancia de AEM en ejecución configurada y conectada a una instancia de Adobe Commerce. Consulte los requisitos y pasos para configuración de un desarrollo local con AEM SDK as a Cloud Service. Para seguir el tutorial por completo, necesitará permisos para agregar Atributos a un producto en Adobe Commerce.

También necesitará el IDE de GraphQL como GraphiQL o una extensión del explorador para ejecutar ejemplos de código y tutoriales. Si instala una extensión del explorador, asegúrese de que tenga la capacidad de establecer encabezados de solicitud. En Google Chrome, Cliente Altair GraphQL es una extensión que puede realizar el trabajo.

Clonar el proyecto de Venia

Clonaremos el Proyecto Venia y, a continuación, anule los estilos predeterminados.

NOTA

Siéntase libre de usar un proyecto existente (basado en el tipo de archivo del proyecto AEM con CIF incluido) y omita esta sección.

  1. Ejecute el siguiente comando git para clonar el proyecto:

    $ git clone git@github.com:adobe/aem-cif-guides-venia.git
    
  2. Cree e implemente el proyecto en una instancia local de AEM:

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  3. Agregue las configuraciones de OSGi necesarias para conectar la instancia de AEM a una instancia de Adobe Commerce o agregue las configuraciones al proyecto recién creado.

  4. En este punto debe tener una versión de trabajo de una tienda conectada a una instancia de Adobe Commerce. Vaya a la US > Home en: http://localhost:4502/editor.html/content/venia/us/en.html.

    Hay que ver que la tienda esté usando actualmente el tema de Venia. Al expandir el menú principal de la tienda, debería ver varias categorías que indican que la conexión a Adobe Commerce está funcionando.

    Tienda configurada con tema de Venia

Creación del teaser de productos

El componente teaser de productos se ampliará a lo largo de este tutorial. Como primer paso, agregue una nueva instancia del teaser de productos a la página principal para comprender la funcionalidad de línea de base.

  1. Vaya hasta la Página de inicio del sitio: http://localhost:4502/editor.html/content/acme/us/en.html

  2. Inserte un nuevo componente teaser de productos en el contenedor del diseño principal de la página.

    Inserción del teaser de productos

  3. Expanda el panel lateral (si no está activado) y cambie desde menú desplegable del buscador de recursos a Productos. Esto debería mostrar una lista de los productos disponibles de una instancia de Adobe Commerce conectada. Seleccione un producto y arrástrelo y suéltelo en el componente teaser de productos de la página.

    Arrastrar y soltar teaser de productos

    NOTA

    Tenga en cuenta que también puede configurar el producto mostrado configurando el componente con el cuadro de diálogo (haga clic en el icono de llave inglesa).

  4. Ahora debería ver un producto que muestra el teaser de productos. Se muestran el nombre y el precio del producto ya que son atributos predeterminados.

    Teaser de productos: estilo predeterminado

Añadir un atributo personalizado en Adobe Commerce

Los productos y los datos de productos mostrados en AEM se almacenan en Adobe Commerce. A continuación, añada un nuevo atributo para Compatible con el ecosistema como parte del atributo de producto configurado mediante la interfaz de usuario de Adobe Commerce.

SUGERENCIA

Ya tiene un Sí/No como parte de su conjunto de atributos de producto? Siéntase libre de usarlo y omita esta sección.

  1. Inicie sesión en la instancia de Adobe Commerce.

  2. Vaya a Catálogo > Productos.

  3. Actualice el filtro de búsqueda para encontrar la variable Producto configurable se utiliza cuando se añade al componente Teaser en el ejercicio anterior. Abra el producto en modo de edición.

    Buscar el producto Valeria

  4. En la vista del producto, haga clic en Añadir atributo > Crear nuevo atributo.

  5. Complete el Nuevo atributo formulario con los siguientes valores (deje la configuración predeterminada para otros valores)

    Conjunto de campos Etiqueta de campo Value
    Propiedades de atributo Etiqueta de atributo Compatible con el ecosistema
    Propiedades de atributo Tipo de entrada de catálogo Sí/No
    Propiedades de atributos avanzadas Código de atributo eco_friendly

    Nuevo formulario de atributos

    Haga clic en Guardar atributo cuando termine.

  6. Desplácese hasta la parte inferior del producto y amplíe el Atributos encabezado. Debería ver el nuevo Compatible con el ecosistema campo . Cambie el conmutador a .

    Cambiar alternancia a sí

    Guardar los cambios en el producto.

  7. Vaya a Sistema > Herramientas > Administración de caché. Como se ha realizado una actualización del esquema de datos, es necesario invalidar algunos de los tipos de caché en Adobe Commerce.

  8. Marque la casilla situada junto a Configuración y envíe el tipo de caché para Actualizar

    Actualizar tipo de caché de configuración

Uso de un IDE de GraphQL para verificar el atributo

Antes de saltar a AEM código, es útil explorar el Información general de GraphQL uso de un IDE de GraphQL. La integración de Adobe Commerce con AEM se realiza principalmente mediante una serie de consultas de GraphQL. Comprender y modificar las consultas de GraphQL es una de las formas clave de ampliar los componentes principales del CIF.

A continuación, utilice un IDE de GraphQL para verificar que la variable eco_friendly se ha agregado al conjunto de atributos de producto. Las capturas de pantalla de este tutorial utilizan la variable Cliente Altair GraphQL.

  1. Abra el IDE de GraphQL e introduzca la URL http://<commerce-server>/graphql en la barra URL de su IDE o extensión.

  2. Agregue lo siguiente consulta de productos donde YOUR_SKU es la variable SKU del producto utilizado en el ejercicio anterior:

      {
        products(
        filter: { sku: { eq: "YOUR_SKU" } }
        ) {
            items {
            name
            sku
            eco_friendly
            }
        }
    }
    
  3. Ejecute la consulta y debe obtener una respuesta como la siguiente:

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

    Ejemplo de respuesta de GraphQL

    Tenga en cuenta que el valor de es un entero de 1. Esto resulta útil cuando escribimos la consulta GraphQL en Java.

    SUGERENCIA

    Documentación más detallada sobre Adobe Commerce GraphQL se puede encontrar aquí.

Actualización del modelo de Sling para el teaser de productos

A continuación, ampliaremos la lógica empresarial del teaser de productos implementando el modelo Sling. Los modelos de Sling son objetos Java antiguos comunes ("POJO"), impulsados por anotaciones que implementan cualquier lógica comercial necesaria para el componente. Los modelos Sling se utilizan junto con las secuencias de comandos HTL como parte del componente. Seguiremos el patrón de delegación de modelos Sling para que podamos extender las partes del modelo de teaser de productos existente.

Los modelos Sling se implementan como Java y se pueden encontrar en el módulo principal del proyecto generado.

Uso el IDE que elija para importar el proyecto Venia. Las capturas de pantalla utilizadas son de la Código IDE de Visual Studio.

  1. En su IDE, vaya a la sección core para: core/src/main/java/com/venia/core/models/commerce/MyProductTeaser.java.

    IDE de ubicación principal

    MyProductTeaser.java es una interfaz de Java que amplía el CIF ProductTeaser interfaz.

    Ya se ha agregado un nuevo método con el nombre isShowBadge() para mostrar un distintivo si el producto se considera "nuevo".

  2. Añada un nuevo método isEcoFriendly() en la interfaz:

    @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 es un nuevo método que introduciremos para encapsular la lógica para indicar si el producto tiene la variable eco_friendly establecido en o No.

  3. A continuación, revise la MyProductTeaserImpl.java at core/src/main/java/com/venia/core/models/commerce/MyProductTeaserImpl.java.

    La variable patrón de delegación para modelos Sling permite MyProductTeaserImpl referencia ProductTeaser a través del sling:resourceSuperType propiedad:

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

    Para todos los métodos que no queremos anular o cambiar, simplemente podemos devolver el valor de que la variable ProductTeaser devuelve. Por ejemplo:

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

    Esto minimiza la cantidad de código Java que debe escribir una implementación.

  4. Uno de los puntos de extensión adicionales que proporcionan AEM componentes principales del CIF es el AbstractProductRetriever que proporciona acceso a atributos de producto específicos. Inspect la variable initModel() método:

    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 initialize the productRetriever */
        @PostConstruct
        public void initModel() {
            productRetriever = productTeaser.getProductRetriever();
    
            if (productRetriever != null) {
                productRetriever.extendProductQueryWith(p -> p.createdAt());
            }
    
        }
    ...
    

    La variable @PostConstruct la anotación garantiza que se llame a este método en cuanto se inicialice el modelo Sling.

    Tenga en cuenta que la consulta de producto GraphQL ya se ha ampliado con la variable extendProductQueryWith método para recuperar el created_at atributo. Este atributo se utiliza más adelante como parte del isShowBadge() método.

  5. Actualice la consulta de GraphQL para incluir el eco_friendly en la consulta 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 -> p
                .createdAt()
                .addCustomSimpleField(ECO_FRIENDLY_ATTRIBUTE)
            );
        }
    }
    

    Añadir al método extendProductQueryWith es una manera eficaz de garantizar que el resto del modelo disponga de atributos de productos adicionales. También minimiza el número de consultas ejecutadas.

    En el código anterior, la variableaddCustomSimpleField se utiliza para recuperar la variable eco_friendly atributo. Esto ilustra cómo se puede consultar cualquier atributo personalizado que forme parte del esquema de Adobe Commerce.

    NOTA

    La variable createdAt() se ha implementado como parte de la función Interfaz de producto. Se han implementado la mayoría de los atributos de esquema encontrados con frecuencia, por lo que solo debe utilizarse addCustomSimpleField para atributos verdaderamente personalizados.

  6. Agregue un registrador para ayudar a depurar el 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. A continuación, implemente la variable isEcoFriendly() método:

    @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;
    }
    

    En el método anterior, la variable productRetriever se usa para recuperar el producto y la variable getAsInteger() para obtener el valor de eco_friendly atributo. Basándonos en las consultas de GraphQL que ejecutamos anteriormente sabemos que el valor esperado cuando la variable eco_friendly se configura como "" es en realidad un entero de 1.

    Ahora que se ha actualizado el modelo Sling, es necesario actualizar el marcado del componente para que muestre un indicador de Compatible con el ecosistema basado en el modelo Sling.

Personalización del marcado del teaser de productos

Una extensión común de los componentes de AEM es modificar el marcado que genera el componente. Esto se realiza anulando la secuencia de comandos HTL que utiliza el componente para representar su marcado. La plantilla de idioma HTML (HTL) es un idioma de plantilla ligero que los componentes de AEM utilizan para representar dinámicamente el marcado basado en contenido creado, lo que permite la reutilización de los componentes. El teaser de productos, por ejemplo, se puede reutilizar una y otra vez para mostrar diferentes productos.

En nuestro caso, queremos renderizar un banner sobre el teaser para indicar que el producto es "compatible con el medio ambiente" basado en un atributo personalizado. El patrón de diseño para personalizar el marcado de un componente es en realidad estándar para todos los componentes AEM, no solo para los componentes principales del CIF de AEM.

NOTA

Si personaliza un componente mediante los seleccionadores de productos y categorías del CIF como este teaser de productos o el componente de página del CIF, asegúrese de incluir el cif.shell.picker clientlib para los cuadros de diálogo de componentes. Consulte Uso del selector de productos y categorías del CIF para obtener más información.

  1. En el IDE, navegue y expanda el ui.apps y expanda la jerarquía de carpetas a: ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser e inspeccione el .content.xml archivo.

    Product Teaser ui.apps

    <?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"/>
    

    Arriba se encuentra la definición del componente para el componente teaser de productos en nuestro proyecto. Observe la propiedad sling:resourceSuperType="core/cif/components/commerce/productteaser/v1/productteaser". Este es un ejemplo de creación de un componente Proxy. En lugar de copiar y pegar todas las secuencias de comandos HTL del teaser de productos de los componentes principales del CIF de AEM, podemos usar sling:resourceSuperType para heredar todas las funcionalidades.

  2. Abra el archivo productteaser.html. Esta es una copia de productteaser.html del Teaser del producto CIF

    <!--/* 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}"
    ></sly>
    

    Observe que el modelo Sling para MyProductTeaser se utiliza y se asigna a la variable product variable.

  3. Modificar productteaser.html para realizar una llamada a la función isEcoFriendly método implementado en el ejercicio 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>
      ...
    </div>
    

    Al llamar a un método de modelo de Sling en HTL, la variable get y is parte del método se suelta y la primera letra se escribe en minúsculas. So isShowBadge() se convierte .showBadge y isEcoFriendly se convierte .ecoFriendly. Basado en el valor booleano devuelto por .isEcoFriendly() determina si la variable <span>Eco Friendly</span> se muestra.

    Más información sobre data-sly-test y otros Las instrucciones de bloque HTL se pueden encontrar aquí.

  4. Guarde los cambios e implemente las actualizaciones en AEM con sus habilidades con Maven, desde un terminal de línea de comandos:

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  5. Abra una nueva ventana del explorador y vaya a AEM y a la Consola OSGi > Estado > Modelos de Sling: http://localhost:4502/system/console/status-slingmodels

  6. Buscar MyProductTeaserImpl y debería ver una línea como la siguiente:

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

    Esto indica que el modelo Sling se ha implementado correctamente y se ha asignado al componente correcto.

  7. Actualice a Página de inicio de Venia at http://localhost:4502/editor.html/content/venia/us/en.html donde se ha añadido el teaser de productos.

    Se muestra un mensaje ecológico

    Si el producto tiene la variable eco_friendly establecido en , debería ver el texto "Eco Friendly" en la página. Intente cambiar a diferentes productos para ver el cambio de comportamiento.

  8. A continuación, abra la AEM error.log para ver las instrucciones de registro que agregamos. La variable error.log se encuentra en <AEM SDK Install Location>/crx-quickstart/logs/error.log.

    Busque en los registros de AEM para ver las instrucciones de registro agregadas en el modelo Sling:

    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**
    ...
    
    PRECAUCIÓN

    También puede ver algunos rastros de pila si el producto utilizado en el teaser no tiene el valor eco_friendly como parte de su conjunto de atributos.

Agregar estilos para el distintivo ecológico

En este punto, la lógica de cuándo mostrar la variable Compatible con el ecosistema está funcionando, sin embargo el texto sin formato podría utilizar algunos estilos. A continuación, agregue un icono y estilos a la variable ui.frontend para completar la implementación.

  1. Descargue el eco_friendly.svg archivo. Se utilizará como el Compatible con el ecosistema distintivo.

  2. Vuelva al IDE y vaya a la ui.frontend carpeta.

  3. Agregue la variable eco_friendly.svg a ui.frontend/src/main/resources/images carpeta:

    Se agregó un SVG compatible con el ecosistema.

  4. Abra el archivo . productteaser.scss at ui.frontend/src/main/styles/commerce/_productteaser.scss.

  5. Añada las siguientes reglas de Sass dentro de la variable .productteaser Clase :

    .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');
            }
        }
    ...
    }
    
    NOTA

    Consulte Diseño de los componentes principales del CIF para obtener más información sobre los flujos de trabajo front-end.

  6. Guarde los cambios e implemente las actualizaciones en AEM con sus habilidades con Maven, desde un terminal de línea de comandos:

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  7. Actualice a Página de inicio de Venia at http://localhost:4502/editor.html/content/venia/us/en.html donde se ha añadido el teaser de productos.

    Implementación Final De Distintivo Compatible Con Eco

Felicitaciones

Acaba de personalizar su primer componente del CIF de AEM. Descargue el archivos de solución terminados aquí.

Desafío para una bonificación

Revise la funcionalidad de la variable Nuevo que ya se ha implementado en el teaser de productos. Intente agregar una casilla de verificación adicional para que los autores controlen cuándo se llama a la función Compatible con el ecosistema se debe mostrar el distintivo. Deberá actualizar el cuadro de diálogo del componente en ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser/_cq_dialog/.content.xml.

Nuevo desafío para la implementación de distintivos

Recursos adicionales

En esta página