Os componentes estão no centro da criação de uma experiência no AEM. O Componentes principais e Arquétipo de projeto AEM facilita começar a usar um conjunto de ferramentas de componentes robustos e prontos. O Tutorial WKND O leva o desenvolvedor a usar essas ferramentas e como criar componentes personalizados para criar um novo site de AEM.
Antes de fazer referência a este documento, verifique se você concluiu a Tutorial WKND e, portanto, familiarizar-se com a Componentes principais e AEM Arquétipo de projeto.
Como o tutorial WKND aborda a maioria dos casos de uso, este documento destina-se somente a complementar esses recursos. Ele fornece especificações técnicas detalhadas sobre como os componentes são estruturados e configurados em AEM e não se destina a ser um guia de introdução.
Esta seção aborda os principais conceitos e problemas como uma introdução aos detalhes necessários ao desenvolver seus próprios componentes.
Antes de começar a realmente configurar ou codificar seu componente, você deve perguntar:
Antes de investir tempo na criação de um componente totalmente novo, considere personalizar ou estender os componentes existentes. Os componentes principais oferecem um conjunto de componentes flexíveis, robustos e bem testados prontos para produção.
Os Componentes principais também oferecem limpar padrões de personalização que você pode usar para adaptá-las às necessidades do seu próprio projeto.
Os componentes também podem ser redefinidos com um sobreposição com base na lógica do caminho de pesquisa. No entanto, nesse caso, o Fusão de Recursos Sling não será acionado e /apps
deve definir a sobreposição inteira.
Também é possível substituir uma caixa de diálogo de componente usando o Sling Resource Merger e definindo a propriedade sling:resourceSuperType
.
Isso significa que você só precisa redefinir as diferenças necessárias, em vez de redefinir toda a caixa de diálogo.
Seu componente será renderizado com HTML. Seu componente precisa definir o HTML necessário para obter o conteúdo necessário e, em seguida, renderizá-lo conforme necessário, nos ambientes de autor e publicação.
É recomendável manter o código responsável pela marcação e renderização separadas do código que controla a lógica usada para selecionar o conteúdo do componente.
Essa filosofia é apoiada por HTL, uma linguagem de modelo que é propositalmente limitada para garantir uma linguagem de programação real é usada para definir a lógica comercial subjacente. Esse mecanismo destaca o código chamado para uma determinada visualização e, se necessário, permite uma lógica específica para diferentes visualizações do mesmo componente.
Essa lógica (opcional) pode ser implementada de diferentes maneiras e é invocada do HTL com comandos específicos:
A estrutura de um componente de AEM é poderosa e flexível. As principais partes são:
Um elemento-chave da estrutura é o tipo de recurso.
Essa é uma abstração que ajuda a garantir que, mesmo quando a aparência muda com o tempo, a intenção permanece o tempo.
A definição de um componente pode ser dividida da seguinte maneira:
/libs/core/wcm/components
./apps/<myApp>/components
.cq:Component
e ter os elementos principais:
cq:Component
definição.<mycomponent> (cq:Component)
- Nó de hierarquia do componente.jcr:title
- Título do componente; por exemplo, usado como um rótulo quando o componente está listado no Navegador de componentes e Console de componentesjcr:description
- Descrição do componente; usado como dica de mouse sobre o console Navegador de componentes e Componentescq:editConfig (cq:EditConfig)
- Define as propriedades de edição do componente e permite que o componente apareça no Navegador de componentes
cq:childEditConfig (cq:EditConfig)
- Controla os aspectos da interface do usuário do autor para componentes filhos que não definem seus próprios cq:editConfig
.cq:dialog (nt:unstructured)
- Caixa de diálogo desse componente. Define a interface que permite ao usuário configurar o componente e/ou editar conteúdo.cq:design_dialog (nt:unstructured)
- Edição de design para este componenteO ícone ou a abreviação do componente é definido por meio das propriedades do JCR do componente quando ele é criado pelo desenvolvedor. Essas propriedades são avaliadas na ordem a seguir e a primeira propriedade válida encontrada é usada.
cq:icon
- Propriedade da string que aponta para um ícone padrão na Biblioteca da interface do usuário do Coral para exibir no navegador de componentes
abbreviation
- Propriedade String para personalizar a abreviação do nome do componente no navegador do componente
jcr:title
propriedade.
abbreviation_commentI18n
, que é usada como dica de tradução.cq:icon.png
ou cq:icon.svg
- Ícone para este componente, que é mostrado no Navegador de componentes
.png
e .svg
os arquivos são suportados._cq_icon.png
ou _cq_icon.svg
por exemplo..png
tem precedência sobre .svg
se ambos estiverem presentes.Se nenhuma das propriedades acima (cq:icon
, abbreviation
, cq:icon.png
ou cq:icon.svg
) são encontradas no componente :
sling:resourceSuperType
propriedade.jcr:title
propriedade do componente atual.Para cancelar a herança de ícones de supercomponentes, defina um valor vazio abbreviation
no componente será revertido para o comportamento padrão.
O Console do componente exibe como o ícone de um componente específico é definido.
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "https://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="https://www.w3.org/2000/svg" xmlns:xlink="https://www.w3.org/1999/xlink" x="0px" y="0px"
width="20px" height="20px" viewBox="0 0 20 20" enable-background="new 0 0 20 20" xml:space="preserve">
<ellipse cx="5" cy="5" rx="3" ry="3" fill="#707070"/>
<ellipse cx="15" cy="5" rx="4" ry="4" fill="#707070"/>
<ellipse cx="5" cy="15" rx="5" ry="5" fill="#707070"/>
<ellipse cx="15" cy="15" rx="4" ry="4" fill="#707070"/>
</svg>
Muitos dos nós/propriedades necessários para definir um componente são comuns a ambas as interfaces do usuário, com diferenças que permanecem independentes para que seu componente possa funcionar em ambos os ambientes.
Um componente é um nó do tipo cq:Component
e tem as seguintes propriedades e nós secundários:
Nome | Tipo | Descrição |
---|---|---|
. |
cq:Component |
Representa o componente atual. Um componente é do tipo de nó cq:Component . |
componentGroup |
String |
Representa o grupo sob o qual o componente pode ser selecionado no Navegador de componentes. Um valor que começa com . é usada para componentes que não estão disponíveis para seleção na interface do usuário, como componentes base dos quais outros componentes herdam. |
cq:isContainer |
Boolean |
Isso indica se o componente é um componente de contêiner e, portanto, pode conter outros componentes, como um sistema de parágrafo. |
cq:dialog |
nt:unstructured |
Essa é a definição da caixa de diálogo de edição do componente. |
cq:design_dialog |
nt:unstructured |
Esta é a definição da caixa de diálogo de design do componente. |
cq:editConfig |
cq:EditConfig |
Isso define o edite a configuração do componente. |
cq:htmlTag |
nt:unstructured |
Isso retorna atributos de tag adicionais que são adicionados à tag HTML ao redor. Permite a adição de atributos aos divs gerados automaticamente. |
cq:noDecoration |
Boolean |
Se verdadeiro, o componente não é renderizado com classes div e css geradas automaticamente. |
cq:template |
nt:unstructured |
Se encontrado, esse nó será usado como um modelo de conteúdo quando o componente for adicionado do Navegador de componentes. |
jcr:created |
Date |
Esta é a data de criação do componente. |
jcr:description |
String |
Esta é a descrição do componente. |
jcr:title |
String |
Este é o título do componente. |
sling:resourceSuperType |
String |
Quando definido, o componente herda desse componente. |
component.html |
nt:file |
Este é o arquivo de script HTL do componente. |
cq:icon |
String |
Esse valor aponta para a variável ícone do componente e é exibido no Navegador de componentes. |
Se olharmos para a Texto , podemos ver vários desses elementos:
As propriedades de interesses específicos incluem:
jcr:title
- Este é o título do componente usado para identificar o componente no Navegador de componentes.jcr:description
- Esta é a descrição do componente.sling:resourceSuperType
- Indica o caminho da herança ao estender um componente (substituindo uma definição).Os nós filhos de interesse especial incluem:
cq:editConfig
- Isso controla os aspectos visuais do componente durante a edição.cq:dialog
- Isso define a caixa de diálogo para edição de conteúdo desse componente.cq:design_dialog
- Especifica as opções de edição de design para este componente.As caixas de diálogo são um elemento essencial do seu componente, pois fornecem uma interface para os autores configurar o componente em uma página de conteúdo e fornecer entrada para esse componente. Consulte a documentação de criação para obter detalhes sobre como os autores de conteúdo interagem com componentes.
Dependendo da complexidade do componente, a caixa de diálogo pode precisar de uma ou mais guias.
Caixas de diálogo para componentes AEM:
cq:dialog
nós do tipo nt:unstructured
.cq:Component
e ao lado de suas definições de componentes.sling:resourceType
propriedade.nt:unstructured
com o sling:resourceType
propriedade.Na caixa de diálogo , campos individuais são definidos:
As caixas de diálogo de design são semelhantes às caixas de diálogo usadas para editar e configurar o conteúdo, mas fornecem a interface para os autores de modelo pró-configurar e fornecer detalhes de design para esse componente em um modelo de página. Os modelos de página são então usados pelos autores de conteúdo para criar páginas de conteúdo. Consulte a documentação do modelo para obter detalhes sobre como os modelos são criados.
As caixas de diálogo de design são usadas ao editar um modelo de página, embora não sejam necessários para todos os componentes. Por exemplo, a variável Título e Componentes de imagem ambos têm diálogos de design, enquanto que a variável Componente de compartilhamento de mídia social não.
A interface do usuário do Coral e a interface do Granite definem a aparência do AEM.
A interface do usuário do Granite fornece uma grande variedade de widgets básicos necessários para criar sua caixa de diálogo no ambiente de criação. Quando necessário, é possível estender essa seleção e criar seu próprio widget.
Para obter detalhes adicionais, consulte os seguintes recursos:
Para criar um novo widget para uso em uma caixa de diálogo de componente, é necessário criar um novo componente de campo da interface do usuário do Granite.
Se sua caixa de diálogo for considerada um contêiner simples para um elemento de formulário, você também poderá ver o conteúdo principal do conteúdo da caixa de diálogo como campos de formulário. A criação de um novo campo de formulário requer a criação de um tipo de recurso; isso equivale a criar um novo componente. Para ajudar você nessa tarefa, a interface do usuário do Granite oferece um componente de campo genérico do qual herdar (usando sling:resourceSuperType
):
/libs/granite/ui/components/coral/foundation/form/field
Mais especificamente, a interface do usuário do Granite fornece uma variedade de componentes de campo adequados para uso em caixas de diálogo ou, de modo mais geral, em formulários.
Depois de criar o tipo de recurso, é possível instanciar o campo adicionando um novo nó na caixa de diálogo, com a propriedade sling:resourceType
referência ao tipo de recurso que acabou de apresentar.
Também é possível usar condições de renderização (rendercondition
) para controlar quem tem acesso a guias/campos específicos na caixa de diálogo; por exemplo:
+ mybutton
- sling:resourceType = granite/ui/components/coral/foundation/button
+ rendercondition
- sling:resourceType = myapp/components/renderconditions/group
- groups = ["administrators"]
Depois de criar um componente, é necessário ativá-lo para usá-lo. Usar isso mostra como a estrutura do componente está relacionada à estrutura do conteúdo resultante no repositório.
Depois que um componente é definido, ele deve ser disponibilizado para uso. Para disponibilizar um componente para uso em um modelo, você deve habilitar o componente na política do contêiner de layout do modelo.
Consulte a documentação do modelo para obter detalhes sobre como os modelos são criados.
Se criarmos e configurarmos uma instância do Título componente na página: /content/wknd/language-masters/en/adventures/extreme-ironing.html
Então podemos ver a estrutura do conteúdo criado no repositório:
Em particular, se você observar o texto real de uma Componente de título:
jcr:title
propriedade contendo o texto real do título inserido pelo autor.sling:resourceType
referência à definição do componente.As propriedades definidas dependem das definições individuais. Embora possam ser mais complexas do que acima, seguem ainda os mesmos princípios básicos.
Os componentes no AEM estão sujeitos ao Hierarquia do Tipo de Recurso. Isso é usado para estender componentes usando a propriedade sling:resourceSuperType
. Isso permite que o componente herde de outro componente.
Consulte a seção Reutilizar componentes para obter mais informações.
Esta seção explica como configurar o comportamento de edição de um componente. Isso inclui atributos como ações disponíveis para o componente, características do editor in.place e os ouvintes relacionados a eventos no componente.
O comportamento de edição de um componente é configurado ao adicionar um cq:editConfig
nó do tipo cq:EditConfig
abaixo do nó do componente (do tipo cq:Component
) e adicionando propriedades específicas e nós secundários. As seguintes propriedades e nós secundários estão disponíveis:
cq:editConfig
propriedades do nócq:editConfig
nós filhos:
cq:dropTargets
(tipo de nó) nt:unstructured
): define uma lista de destinos de soltar que podem aceitar uma queda de um ativo do localizador de conteúdo (um único destino de soltar é permitido)cq:inplaceEditing
(tipo de nó) cq:InplaceEditingConfig
): define uma configuração de edição no local para o componentecq:listeners
(tipo de nó) cq:EditListenersConfig
): define o que acontece antes ou depois que uma ação ocorre no componenteHá muitas configurações existentes no AEM. Você pode pesquisar facilmente propriedades específicas ou nós secundários usando a ferramenta Query em CRXDE Lite.
Os componentes devem sempre renderizar algum HTML visível para o autor, mesmo quando o componente não tiver conteúdo. Caso contrário, pode desaparecer visualmente da interface do editor, tornando-a tecnicamente presente, mas invisível, na página e no editor. Nesse caso, os autores não poderão selecionar e interagir com o componente vazio.
Por isso, os componentes devem renderizar um espaço reservado, desde que não renderizem nenhuma saída visível quando a página for renderizada no editor de páginas (quando o modo WCM estiver edit
ou preview
).
A marcação de HTML típica para um espaço reservado é a seguinte:
<div class="cq-placeholder" data-emptytext="Component Name"></div>
O script HTL típico que renderiza o HTML de espaço reservado acima é o seguinte:
<div class="cq-placeholder" data-emptytext="${component.properties.jcr:title}"
data-sly-test="${(wcmmode.edit || wcmmode.preview) && isEmpty}"></div>
No exemplo anterior, isEmpty
é uma variável que é verdadeira somente quando o componente não tem conteúdo e é invisível para o autor.
Para evitar a repetição, o Adobe recomenda que os implementadores de componentes usem um template HTL para esses espaços reservados, como o fornecido pelos Componentes principais.
O uso do template no link anterior é feito com a seguinte linha de HTL:
<sly data-sly-use.template="core/wcm/components/commons/v1/templates.html"
data-sly-call="${template.placeholder @ isEmpty=!model.text}"></sly>
No exemplo anterior, model.text
é a variável que é verdadeira somente quando o conteúdo tem conteúdo e é visível.
Um exemplo de uso desse modelo pode ser visto nos Componentes principais, como no Componente de título.
O cq:dropTargets
nó (tipo de nó) nt:unstructured
) define o público-alvo que pode aceitar uma queda de um ativo arrastado do localizador de conteúdo. É um nó do tipo cq:DropTargetConfig
.
O nó filho do tipo cq:DropTargetConfig
define um destino de soltar no componente.
Um editor local permite que o usuário edite conteúdo diretamente no fluxo de conteúdo, sem a necessidade de abrir uma caixa de diálogo. Por exemplo, o padrão Texto e Título ambos os componentes têm um editor inp-lace.
Um editor local não é necessário/significativo para cada tipo de componente.
O cq:inplaceEditing
nó (tipo de nó) cq:InplaceEditingConfig
) define uma configuração de edição no local para o componente. Pode ter as seguintes propriedades:
Nome da Propriedade | Tipo de propriedade | Valor da propriedade |
---|---|---|
active |
Boolean |
true para ativar a edição no local do componente. |
configPath |
String |
Caminho da configuração do editor, que pode ser especificado por um nó de configuração |
editorType |
String |
Os tipos disponíveis são: plaintext para conteúdo não HTML, title converte títulos gráficos em um texto simples antes do início da edição, e text O usa o Editor de Rich Text |
A configuração a seguir permite a edição no local do componente e define plaintext
como tipo de editor:
<cq:inplaceEditing
jcr:primaryType="cq:InplaceEditingConfig"
active="{Boolean}true"
editorType="plaintext"/>
O método de tratamento de eventos em campos de diálogo é feito com ouvintes em um biblioteca do cliente.
Para inserir lógica em seu campo, você deve:
Para isso, você precisa saber sobre a biblioteca de widgets subjacente com a qual deseja interagir. Consulte a documentação da interface do usuário do Coral para identificar a qual evento você deseja reagir.
O cq:listeners
nó (tipo de nó) cq:EditListenersConfig
) define o que acontece antes ou depois de uma ação no componente. A tabela a seguir define suas possíveis propriedades.
Nome da Propriedade | Valor da propriedade |
---|---|
beforedelete |
O manipulador é acionado antes da remoção do componente. |
beforeedit |
O manipulador é acionado antes que o componente seja editado. |
beforecopy |
O manipulador é acionado antes que o componente seja copiado. |
beforeremove |
O manipulador é acionado antes que o componente seja movido. |
beforeinsert |
O manipulador é acionado antes da inserção do componente. |
beforechildinsert |
O manipulador é acionado antes que o componente seja inserido em outro componente (somente contêineres). |
afterdelete |
O manipulador é acionado após a remoção do componente. |
afteredit |
O manipulador é acionado após a edição do componente. |
aftercopy |
O manipulador é acionado após o componente ser copiado. |
afterinsert |
O manipulador é acionado após a inserção do componente. |
aftermove |
O manipulador é acionado após o componente ser movido. |
afterchildinsert |
O manipulador é acionado após o componente ser inserido em outro componente (somente contêineres). |
No caso de componentes aninhados, há certas restrições nas ações definidas como propriedades na variável cq:listeners
nó . Para componentes aninhados, os valores das seguintes propriedades must be REFRESH_PAGE
:
aftermove
aftercopy
O manipulador de eventos pode ser implementado com uma implementação personalizada. Por exemplo (onde project.customerAction
é um método estático):
afteredit = "project.customerAction"
O exemplo a seguir é equivalente ao REFRESH_INSERTED
configuração:
afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"
Com a seguinte configuração, a página é atualizada após o componente ter sido excluído, editado, inserido ou movido:
<cq:listeners
jcr:primaryType="cq:EditListenersConfig"
afterdelete="REFRESH_PAGE"
afteredit="REFRESH_PAGE"
afterinsert="REFRESH_PAGE"
afterMove="REFRESH_PAGE"/>
A validação de campo na interface do usuário do Granite e nos widgets da interface do usuário do Granite é feita usando o foundation-validation
API. Consulte a foundation-valdiation
Documentação do Granite para obter detalhes.
Se você tiver um JavaScript personalizado que precisa ser executado somente quando a caixa de diálogo estiver disponível e pronta, você deve ouvir a dialog-ready
evento.
Esse evento é acionado sempre que a caixa de diálogo é carregada (ou recarregada) e está pronta para uso, o que significa que sempre que há uma alteração (criar/atualizar) no DOM da caixa de diálogo.
dialog-ready
pode ser usada para conectar o código personalizado JavaScript que executa personalizações nos campos dentro de uma caixa de diálogo ou tarefas semelhantes.
O Modo WCM é definido ao alternar para o modo de Visualização mesmo quando a página não é atualizada.
Para componentes com uma renderização que são sensíveis ao modo WCM, eles precisam ser definidos para serem atualizados especificamente e, em seguida, dependem do valor do cookie.
Como desenvolvedor, você deseja obter acesso fácil à documentação do componente, para que você possa entender rapidamente o componente:
Por isso, é muito fácil tornar qualquer marcação de documentação existente disponível no próprio componente.
Tudo o que você precisa fazer é colocar um README.md
na estrutura do componente.
Essa marcação será exibida no Console de componentes.
O Markdown suportado é igual ao do Fragmentos de conteúdo.