Criar um componente personalizado
- Aplica-se a:
- Experience Manager as a Cloud Service
Criado para:
- Iniciante
- Desenvolvedor
- O Editor Universal para editar visualmente o conteúdo headless.
- O Editor de Fragmento de Conteúdo para edição baseada em formulário de conteúdo headless.
Saiba como criar um componente personalizado a ser usado com o Editor SPA do AEM. Saiba como desenvolver caixas de diálogo de criação e Modelos Sling para estender o modelo JSON e preencher um componente personalizado.
Objetivo
- Entenda a função dos Modelos do Sling na manipulação da API do modelo JSON fornecida pelo AEM.
- Entenda como criar caixas de diálogo de componente do AEM.
- Saiba como criar um Componente AEM personalizado que seja compatível com a estrutura do editor de SPA.
O que você vai criar
O foco dos capítulos anteriores era desenvolver componentes de SPA e mapeá-los para Componentes principais do AEM existentes. Este capítulo se concentra em como criar e estender novos componentes do AEM e manipular o modelo JSON fornecido pelo AEM.
Um simples Custom Component
ilustra as etapas necessárias para criar um novo componente do AEM.
Pré-requisitos
Revise as ferramentas e instruções necessárias para configurar um ambiente de desenvolvimento local.
Obter o código
-
Baixe o ponto de partida para este tutorial pelo Git:
$ git clone git@github.com:adobe/aem-guides-wknd-spa.git $ cd aem-guides-wknd-spa $ git checkout Angular/custom-component-start
-
Implante a base de código em uma instância do AEM local usando Maven:
$ mvn clean install -PautoInstallSinglePackage
Se estiver usando o AEM 6.x, adicione o perfil
classic
:$ mvn clean install -PautoInstallSinglePackage -Pclassic
-
Instale o pacote concluído para o site de referência WKND tradicional. As imagens fornecidas pelo site de referência WKND são reutilizadas no SPA do WKND. O pacote pode ser instalado usando o Gerenciador de Pacotes da AEM.
Você sempre pode exibir o código concluído em GitHub ou conferir o código localmente alternando para a ramificação Angular/custom-component-solution
.
Definir o componente do AEM
Um componente do AEM é definido como um nó e propriedades. No projeto, esses nós e propriedades são representados como arquivos XML no módulo ui.apps
. Em seguida, crie o componente AEM no módulo ui.apps
.
-
Abra a pasta
ui.apps
no IDE de sua escolha. -
Navegue até
ui.apps/src/main/content/jcr_root/apps/wknd-spa-angular/components
e crie uma pasta chamadacustom-component
. -
Crie um arquivo chamado
.content.xml
abaixo da pastacustom-component
. Preencha ocustom-component/.content.xml
com o seguinte:<?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:primaryType="cq:Component" jcr:title="Custom Component" componentGroup="WKND SPA Angular - Content"/>
jcr:primaryType="cq:Component"
- identifica que este nó é um componente do AEM.jcr:title
é o valor exibido para os Autores de Conteúdo ecomponentGroup
determina o agrupamento de componentes na interface de criação. -
Abaixo da pasta
custom-component
, crie outra pasta chamada_cq_dialog
. -
Abaixo da pasta
_cq_dialog
, crie um arquivo chamado.content.xml
e preencha-o com o seguinte:<?xml version="1.0" encoding="UTF-8"?> <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:granite="http://www.adobe.com/jcr/granite/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0" jcr:primaryType="nt:unstructured" jcr:title="Custom Component" sling:resourceType="cq/gui/components/authoring/dialog"> <content jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/coral/foundation/container"> <items jcr:primaryType="nt:unstructured"> <tabs jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/coral/foundation/tabs" maximized="{Boolean}true"> <items jcr:primaryType="nt:unstructured"> <properties jcr:primaryType="nt:unstructured" jcr:title="Properties" sling:resourceType="granite/ui/components/coral/foundation/container" margin="{Boolean}true"> <items jcr:primaryType="nt:unstructured"> <columns jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns" margin="{Boolean}true"> <items jcr:primaryType="nt:unstructured"> <column jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/coral/foundation/container"> <items jcr:primaryType="nt:unstructured"> <message jcr:primaryType="nt:unstructured" sling:resourceType="granite/ui/components/coral/foundation/form/textfield" fieldDescription="The text to display on the component." fieldLabel="Message" name="./message"/> </items> </column> </items> </columns> </items> </properties> </items> </tabs> </items> </content> </jcr:root>
O arquivo XML acima gera uma caixa de diálogo simples para
Custom Component
. A parte crítica do arquivo é o nó interno<message>
. Esta caixa de diálogo contém umtextfield
simples chamadoMessage
e mantém o valor do campo de texto para uma propriedade chamadamessage
.Um Modelo Sling é criado próximo a expor o valor da propriedade
message
por meio do modelo JSON.NOTE
Você pode exibir muito mais exemplos de caixas de diálogo ao exibir as definições dos Componentes principais. Você também pode exibir campos de formulário adicionais, comoselect
,textarea
,pathfield
, disponíveis em/libs/granite/ui/components/coral/foundation/form
no CRXDE-Lite.Com um componente tradicional do AEM, geralmente é necessário um script HTL. Como o SPA renderiza o componente, nenhum script HTL é necessário.
Criar o modelo do Sling
Os Modelos do Sling são objetos POJO (Plain Old Java™ Objects) do Java™ orientados por anotações que facilitam o mapeamento de dados do JCR para as variáveis do Java™. Os Modelos do Sling geralmente funcionam para encapsular uma lógica de negócios complexa do lado do servidor para Componentes do AEM.
No contexto do Editor SPA, os Modelos Sling expõem o conteúdo de um componente por meio do modelo JSON por meio de um recurso que usa o Exportador de Modelo Sling.
-
No IDE de sua escolha, abra o módulo
core
.CustomComponent.java
eCustomComponentImpl.java
já foram criados e extraídos como parte do código inicial do capítulo.NOTE
Se estiver usando o Visual Studio Code IDE, pode ser útil instalar extensões para o Java™. -
Abra a interface Java™
CustomComponent.java
emcore/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/CustomComponent.java
:Essa é a interface Java™ implementada pelo Modelo Sling.
-
Atualizar
CustomComponent.java
para que ele estenda a interfaceComponentExporter
:package com.adobe.aem.guides.wknd.spa.angular.core.models; import com.adobe.cq.export.json.ComponentExporter; public interface CustomComponent extends ComponentExporter { public String getMessage(); }
A implementação da interface
ComponentExporter
é um requisito para que o Modelo Sling seja selecionado automaticamente pela API do modelo JSON.A interface
CustomComponent
inclui um único método gettergetMessage()
. Esse é o método que expõe o valor da caixa de diálogo do autor por meio do modelo JSON. Somente métodos Getter com parâmetros vazios()
são exportados no modelo JSON. -
Abrir
CustomComponentImpl.java
emcore/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/impl/CustomComponentImpl.java
.Esta é a implementação da interface
CustomComponent
. A anotação@Model
identifica a classe Java™ como um Modelo Sling. A anotação@Exporter
permite que a classe Java™ seja serializada e exportada por meio do Exportador de Modelo do Sling. -
Atualize a variável estática
RESOURCE_TYPE
para apontar para o componente AEMwknd-spa-angular/components/custom-component
criado no exercício anterior.static final String RESOURCE_TYPE = "wknd-spa-angular/components/custom-component";
O tipo de recurso do componente é o que vincula o Modelo do Sling ao componente do AEM e, por fim, mapeia para o componente do Angular.
-
Adicione o método
getExportedType()
à classeCustomComponentImpl
para retornar o tipo de recurso do componente:@Override public String getExportedType() { return CustomComponentImpl.RESOURCE_TYPE; }
Este método é necessário ao implementar a interface
ComponentExporter
e expõe o tipo de recurso que permite o mapeamento para o componente do Angular. -
Atualize o método
getMessage()
para retornar o valor da propriedademessage
persistida pela caixa de diálogo do autor. Use a anotação@ValueMap
para mapear o valor JCRmessage
para uma variável Java™:import org.apache.commons.lang3.StringUtils; ... @ValueMapValue private String message; @Override public String getMessage() { return StringUtils.isNotBlank(message) ? message.toUpperCase() : null; }
Alguma "lógica de negócios" adicional é adicionada para retornar o valor da mensagem como maiúsculas. Isso nos permite ver a diferença entre o valor bruto armazenado pela caixa de diálogo do autor e o valor exposto pelo Modelo do Sling.
NOTE
Você pode exibir o CustomComponentImpl.java concluído aqui.
Atualizar o componente do Angular
O código Angular do componente personalizado já foi criado. Em seguida, faça algumas atualizações para mapear o componente Angular para o componente AEM.
-
No módulo
ui.frontend
, abra o arquivoui.frontend/src/app/components/custom/custom.component.ts
-
Observe a linha
@Input() message: string;
. Espera-se que o valor em maiúsculas transformado seja mapeado para essa variável. -
Importe o objeto
MapTo
do AEM SPA Editor JS SDK e use-o para mapear para o componente AEM:+ import {MapTo} from '@adobe/cq-angular-editable-components'; ... export class CustomComponent implements OnInit { ... } + MapTo('wknd-spa-angular/components/custom-component')(CustomComponent, CustomEditConfig);
-
Abra
cutom.component.html
e observe que o valor de{{message}}
é exibido ao lado de uma tag<h2>
. -
Abra
custom.component.css
e adicione a seguinte regra::host-context { display: block; }
Para que o Espaço Reservado do Editor do AEM seja exibido corretamente, quando o componente estiver vazio, o
:host-context
ou outro<div>
precisa ser definido comodisplay: block;
. -
Implante as atualizações em um ambiente local do AEM a partir da raiz do diretório do projeto, usando suas habilidades em Maven:
$ cd aem-guides-wknd-spa $ mvn clean install -PautoInstallSinglePackage
Atualizar a política do modelo
Em seguida, navegue até o AEM para verificar as atualizações e permitir que o Custom Component
seja adicionado ao SPA.
-
Verifique o registro do novo Modelo do Sling navegando até http://localhost:4502/system/console/status-slingmodels.
com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl - wknd-spa-angular/components/custom-component com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl exports 'wknd-spa-angular/components/custom-component' with selector 'model' and extension '[Ljava.lang.String;@6fb4a693' with exporter 'jackson'
Você deve ver as duas linhas acima que indicam que
CustomComponentImpl
está associado ao componentewknd-spa-angular/components/custom-component
e que ele está registrado por meio do Exportador de Modelo do Sling. -
Navegue até o Modelo de página do SPA em http://localhost:4502/editor.html/conf/wknd-spa-angular/settings/wcm/templates/spa-page-template/structure.html.
-
Atualize a política do Contêiner de Layout para adicionar o novo
Custom Component
como um componente permitido:Salve as alterações na política e observe o
Custom Component
como um componente permitido:
Criar o componente personalizado
Em seguida, crie o Custom Component
usando o Editor SPA do AEM.
-
Navegue até http://localhost:4502/editor.html/content/wknd-spa-angular/us/en/home.html.
-
No modo
Edit
, adicione oCustom Component
aoLayout Container
: -
Abra a caixa de diálogo do componente e insira uma mensagem que contenha algumas letras minúsculas.
Esta é a caixa de diálogo que foi criada com base no arquivo XML mencionado anteriormente no capítulo.
-
Salve as alterações. Observe que a mensagem exibida está em maiúsculas.
-
Exiba o modelo JSON navegando até http://localhost:4502/content/wknd-spa-angular/us/en.model.json. Pesquisar por
wknd-spa-angular/components/custom-component
:"custom_component_208183317": { "message": "HELLO WORLD", ":type": "wknd-spa-angular/components/custom-component" }
Observe que o valor JSON está definido como todas as letras maiúsculas com base na lógica adicionada ao Modelo Sling.
Parabéns!
Parabéns, você aprendeu a criar um componente AEM personalizado e como os Modelos e caixas de diálogo do Sling funcionam com o modelo JSON.
Você sempre pode exibir o código concluído em GitHub ou conferir o código localmente alternando para a ramificação Angular/custom-component-solution
.
Próximas etapas
Estender um Componente Principal - Saiba como estender um Componente Principal existente para ser usado com o Editor SPA do AEM. Entender como adicionar propriedades e conteúdo a um componente existente é uma técnica poderosa para expandir os recursos de uma implementação do Editor SPA do AEM.