Documentação AEM 6.4 Guia de desenvolvimento

Componentes AEM - Noções básicas

Última atualização: 4 de maio de 2023

Tópicos:
Desenvolvimento

Criado para:

Desenvolvedor

CAUTION

AEM 6.4 chegou ao fim do suporte estendido e esta documentação não é mais atualizada. Para obter mais detalhes, consulte nossa períodos de assistência técnica. Encontre as versões compatíveis here.

Quando você começa a desenvolver novos componentes, é necessário compreender as noções básicas de sua estrutura e configuração.

Esse processo envolve a leitura da teoria e a análise da grande variedade de implementações de componentes em uma instância de AEM padrão. Essa última abordagem é um pouco complicada pelo fato de que, embora a AEM tenha mudado para uma nova interface padrão, moderna e habilitada para toque, ela continua a oferecer suporte à interface clássica.

Visão geral

Esta seção aborda os principais conceitos e problemas como uma introdução aos detalhes necessários ao desenvolver seus próprios componentes.

Planejamento

Antes de começar a realmente configurar ou codificar seu componente, você deve perguntar:

O que exatamente você precisa que o novo componente faça?
- Uma especificação clara ajuda em todas as etapas de desenvolvimento, teste e transferência.
  
  Os detalhes podem mudar com o tempo, mas a especificação pode ser atualizada (embora as alterações também devam ser documentadas).
Você precisa criar seu componente do zero ou pode herdar as noções básicas de um componente existente?
- Não há necessidade de reinventar a roda.
- Há vários mecanismos fornecidos pelo AEM para permitir herdar e estender detalhes de outra definição de componente, incluindo substituição, sobreposição e o Fusão de Recursos Sling.
Seu componente precisará de lógica para selecionar/manipular o conteúdo?
- A lógica deve ser mantida separada da camada da interface do usuário. O HTL foi projetado para ajudar a garantir que isso aconteça.
Seu componente precisará de formatação CSS?
- A formatação de CSS deve ser mantida separada das definições do componente. Defina as convenções para nomear seus elementos HTML para que você possa modificá-los por meio de arquivos CSS externos.
Que aspectos de segurança devo ter em consideração?
- Consulte Lista de verificação de segurança - Práticas recomendadas de desenvolvimento para obter mais detalhes.

Interface habilitada para toque vs clássica

Antes de qualquer discussão séria começar sobre o desenvolvimento de componentes, você precisa saber qual interface de usuário seus autores usarão:

Interface habilitada para toque
A interface de usuário padrão que foi introduzido no AEM 5.6.0 como visualização e estendido no 6.x. É baseado na experiência unificada do usuário para a Adobe Marketing Cloud, usando as tecnologias subjacentes de Interface do usuário do Coral e Interface do usuário do Granite.
Interface clássica
Interface do usuário baseada na tecnologia ExtJS que foi introduzida com o CQ 5.1.

Consulte Interface da interface do usuário do Recommendations para clientes para obter mais detalhes.

Os componentes podem ser implementados para suportar a interface habilitada para toque, a interface clássica ou ambos. Ao observar uma instância padrão, você também verá componentes prontos para uso que foram originalmente projetados para a interface clássica, para a interface habilitada para toque ou ambos.

Por isso, abordaremos as noções básicas de ambas as páginas e como reconhecê-las, nesta página.

NOTE

O Adobe recomenda o aproveitamento da interface habilitada para toque para se beneficiar da tecnologia mais recente. Ferramentas de Modernização AEM pode facilitar a migração.

Lógica de conteúdo e marcação de renderizaçã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. Essa lógica (opcional) é invocada do HTL com um comando específico. 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.

HTL vs JSP

HTL é uma linguagem de modelo do HTML introduzida com o AEM 6.0.

A discussão sobre se usar HTL ou JSP (Java Server Pages) ao desenvolver seus próprios componentes deve ser simples, pois o HTL agora é a linguagem de script recomendada para o AEM.

O HTL e o JSP podem ser usados para desenvolver componentes para a interface clássica e a interface habilitada para toque. Embora possa haver uma tendência de supor que HTL seja somente para a interface habilitada para toque e JSP para a interface clássica, isso é um equívoco e mais devido ao tempo. A interface do usuário habilitada para toque e o HTL foram incorporados ao AEM aproximadamente no mesmo período. Como o HTL agora é o idioma recomendado, ele está sendo usado para novos componentes, que tendem a ser para a interface habilitada para toque.

NOTE

As exceções são Campos de formulário da interface do usuário do Granite (conforme usado em caixas de diálogo). Elas ainda exigem o uso do JSP.

Desenvolvimento de seus próprios componentes

Para criar seus próprios componentes para a interface do usuário apropriada, consulte (após ler esta página):

Uma maneira rápida de começar é copiar um componente existente e fazer as alterações desejadas. Para saber como criar seus próprios componentes e adicioná-los ao sistema de parágrafos, consulte:

Componentes de desenvolvimento (focado na interface habilitada para toque)

Mover componentes para a instância de publicação

Os componentes que renderizam o conteúdo devem ser implantados na mesma instância AEM do conteúdo. Portanto, todos os componentes usados para criar e renderizar páginas na instância do autor devem ser implantados na instância de publicação. Quando implantados, os componentes ficam disponíveis para renderizar páginas ativadas.

Use as seguintes ferramentas para mover seus componentes para a instância de publicação:

Usar o Gerenciador de Pacotes para adicionar seus componentes a um pacote e movê-los para outra instância do AEM.
Use a ferramenta Ativar replicação da árvore para replicar os componentes.

NOTE

Esses mecanismos também podem ser usados para transferir o componente entre outras instâncias, por exemplo, do desenvolvimento para a instância de teste.

Componentes a serem conhecidos desde o início

Página:
- AEM tem a variável página componente ( cq:Page).
- Esse é um tipo específico de recurso, importante para o gerenciamento de conteúdo.
  - Uma página corresponde a uma página da Web que contém conteúdo para seu site.
Sistemas de parágrafo:
- O sistema de parágrafo é uma parte essencial de um site, pois gerencia uma lista de parágrafos. É usado para manter e estruturar os componentes individuais que contêm o conteúdo real.
- Você pode criar, mover, copiar e excluir parágrafos no sistema de parágrafos.
- Você também pode selecionar os componentes que estarão disponíveis para uso em um sistema de parágrafos específico.
- Há vários sistemas de parágrafo disponíveis em uma instância padrão (por exemplo, parsys, [responsivegrid](/docs/experience-manager-64/sites-authoring/responsive-layout.md)).

Estrutura

A estrutura de um componente de AEM é poderosa e flexível, as principais considerações são:

Tipo de recurso
Definição do componente
Propriedades e nós secundários de um componente
Caixas de diálogo
Caixas de diálogo de design
Disponibilidade de componentes
Componentes e o conteúdo que eles criam

Tipo de recurso

Um elemento-chave da estrutura é o tipo de recurso.

A estrutura de conteúdo declara intenções.
O tipo de recurso implementa-os.

Essa é uma abstração que ajuda a garantir que, mesmo quando a aparência muda com o tempo, a intenção permanece o tempo.

Definição do componente

Noções básicas sobre componentes

A definição de um componente pode ser dividida da seguinte maneira:

AEM componentes se baseiam em Sling.
AEM componentes estão (normalmente) localizados em:
- HTL: /libs/wcm/foundation/components
- JSP: /libs/foundation/components
Os componentes específicos do projeto/site estão (normalmente) localizados em:
- /apps/<myApp>/components
AEM componentes padrão são definidos como cq:Component e ter os elementos principais:
- propriedades do jcr:
  
  Uma lista de propriedades do jcr; são variáveis e algumas podem ser opcionais por meio da estrutura básica de um nó de componente, suas propriedades e subnós são definidos pela variável cq:Component definição
- Recursos:
  
  Eles definem elementos estáticos usados pelo componente.
- Scripts:
São usados para implementar o comportamento da instância resultante do componente.
Nó raiz:
- <mycomponent> (cq:Component) - Nó de hierarquia do componente.
Propriedades vitais:
- jcr:title - Título do componente; por exemplo, usado como um rótulo quando o componente está listado no navegador de componentes ou no sidekick.
- jcr:description - Descrição do componente; pode ser usado como dica de mouse sobre o navegador de componentes ou sidekick.
- IU Clássica:
  - icon.png - Ícone para este componente.
  - thumbnail.png - Imagem exibida se esse componente estiver listado no sistema de parágrafo.
- Interface de toque
  - Consulte a seção Ícone de componente na interface do usuário de toque para obter detalhes.
Nós Secundários Vitais:
- cq:editConfig (cq:EditConfig) - Define as propriedades de edição do componente e permite que o componente apareça no navegador Componentes ou no Sidekick.
  
  Observação: se o componente tiver uma caixa de diálogo, ela aparecerá automaticamente no navegador Componentes ou no Sidekick, mesmo se cq:editConfig não existir.
- 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.
- Interface habilitada para toque:
  - 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 componente
- IU Clássica:
  - dialog ( cq:Dialog) - Caixa de diálogo desse componente. Define a interface que permite ao usuário configurar o componente e/ou editar conteúdo.
  - design_dialog ( cq:Dialog) - Edição de design para este componente.

Ícone de componente na interface do usuário de toque

O í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
- Use o valor do atributo HTML do ícone Coral.
abbreviation - Propriedade String para personalizar a abreviação do nome do componente no navegador do componente
- A abreviação deve ser limitada a dois caracteres.
- Fornecer uma string vazia criará a abreviação dos dois primeiros caracteres do jcr:title propriedade.
  - Por exemplo, "Im" para "Image"
  - O título localizado será usado para criar a abreviação.
- A abreviação só é traduzida se o componente tiver uma abbreviation_commentI18n , que é usada como dica de tradução.
cq:icon.png ou cq:icon.svg - Ícone para esse componente, que é mostrado no navegador de componentes
- 20 x 20 pixels é o tamanho dos ícones dos componentes padrão.
  - Os ícones maiores serão baixados (no lado do cliente).
- A cor recomendada é rgb(112, 112, 112) > #707070
- O plano de fundo dos ícones de componentes padrão é transparente.
- Somente .png e .svg os arquivos são suportados.
- Ao importar do sistema de arquivos por meio do plug-in Eclipse, os nomes de arquivo precisam ser evitados como _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 :

O sistema pesquisará as mesmas propriedades nos supercomponentes seguindo o sling:resourceSuperType propriedade.
Se nada ou uma abreviação vazia for encontrada no nível do supercomponente, o sistema criará a abreviação das primeiras letras do 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.

Exemplo de ícone SVG

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

Propriedades e nós secundários de um componente

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`	Componente atual. Um componente é do tipo de nó `cq:Component`.
`componentGroup`	`String`	Grupo no qual o componente pode ser selecionado no navegador Componentes (interface habilitada para toque) ou no Sidekick (interface clássica). Um valor de `.hidden` é usada para componentes que não estão disponíveis para seleção na interface do usuário, como os sistemas de parágrafo reais.
`cq:isContainer`	`Boolean`	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`	Definição da caixa de diálogo de edição para a interface habilitada para toque.
`dialog`	`cq:Dialog`	Definição da caixa de diálogo de edição para a interface clássica.
`cq:design_dialog`	`nt:unstructured`	Definição da caixa de diálogo de design para a interface habilitada para toque.
`design_dialog`	`cq:Dialog`	Definição da caixa de diálogo de design para a interface clássica.
`dialogPath`	`String`	Caminho para uma caixa de diálogo para abranger o caso em que o componente não tem um nó de diálogo.

`cq:cellName`	`String`	Se definida, essa propriedade será considerada como ID da célula. Para obter mais informações, consulte o artigo da Base de conhecimento Como as IDs de células de design são criadas.
`cq:childEditConfig`	`cq:EditConfig`	Quando o componente é um contêiner, como por exemplo um sistema de parágrafo, isso direciona a configuração de edição dos nós filhos.
`cq:editConfig`	`cq:EditConfig`	Editar configuração do componente.
`cq:htmlTag`	`nt:unstructured`	Retorna atributos de tag adicionais que são adicionados à tag html circundante. 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 ou do Sidekick.
`cq:templatePath`	`String`	Caminho para um nó a ser usado como um modelo de conteúdo quando o componente for adicionado do navegador Componentes ou do Sidekick. Deve ser um caminho absoluto, não relativo ao nó do componente. A menos que você queira reutilizar o conteúdo já disponível em outro lugar, isso não é obrigatório e `cq:template` é suficiente (ver abaixo).
`jcr:created`	`Date`	Data de criação do componente.
`jcr:description`	`String`	Descrição do componente.
`jcr:title`	`String`	Título do componente.
`sling:resourceSuperType`	`String`	Quando definido, o componente herda desse componente.
`virtual`	`sling:Folder`	Permite a criação de componentes virtuais. Para ver um exemplo, verifique o componente de contato em: `/libs/foundation/components/profile/form/contact`
`<breadcrumb.jsp>`	`nt:file`	Arquivo de script.
`icon.png`	`nt:file`	O ícone do componente aparece ao lado do Título no Sidekick.
`thumbnail.png`	`nt:file`	Miniatura opcional mostrada enquanto o componente é arrastado do Sidekick para o lugar.

Se olharmos para a Texto componente (qualquer versão), podemos ver estes elementos:

HTL ( /libs/wcm/foundation/components/text)
JSP ( /libs/foundation/components/text)

As propriedades de interesses específicos incluem:

jcr:title - o título do componente; isso pode ser usado para identificar o componente, por exemplo, ele aparece na lista de componentes no navegador de componentes ou no sidekick
jcr:description - descrição do componente; pode ser usado como dica de mouse sobre a lista de componentes dentro do sidekick
sling:resourceSuperType: isso indica o caminho da herança ao estender um componente (substituindo uma definição)

Os nós filhos de interesse especial incluem:

cq:editConfig ( cq:EditConfig) - controlo dos aspectos visuais; por exemplo, ele pode definir a aparência de uma barra ou de um widget ou pode adicionar controles personalizados
cq:childEditConfig ( cq:EditConfig) - controla os aspectos visuais dos componentes filhos que não têm as suas próprias definições
Interface habilitada para toque:
- cq:dialog ( nt:unstructured) - define a caixa de diálogo para editar o conteúdo desse componente
- cq:design_dialog ( nt:unstructured) - especifica as opções de edição de design para este componente
IU Clássica:
- dialog ( cq:Dialog) - define a caixa de diálogo para editar o conteúdo desse componente (específico da interface clássica)
- design_dialog ( cq:Dialog) - especifica as opções de edição de design para este componente
- icon.png - arquivo gráfico a ser usado como ícone para o componente no Sidekick
- thumbnail.png - arquivo gráfico a ser usado como miniatura do componente ao arrastá-lo do Sidekick

Caixas de diálogo

As caixas de diálogo são um elemento essencial do seu componente, pois fornecem uma interface para os autores configurar e fornecer entrada para esse componente.

Dependendo da complexidade do componente, a caixa de diálogo pode precisar de uma ou mais guias, para manter a caixa de diálogo curta e classificar os campos de entrada.

As definições de caixa de diálogo são específicas da interface do usuário:

NOTE

Para fins de compatibilidade, a interface do usuário habilitada para toque pode usar a definição de uma caixa de diálogo da interface do usuário clássica, quando nenhuma caixa de diálogo tiver sido definida para a interface do usuário habilitada para toque.
O Ferramentas de Modernização AEM O também é fornecido para ajudá-lo a estender/converter componentes que tenham apenas caixas de diálogo definidas para a interface clássica.

Interface habilitada para toque
- cq:dialog ( nt:unstructured) nós:
  - definir a caixa de diálogo para editar o conteúdo deste componente
  - específico da interface habilitada para toque
  - são definidas usando componentes da interface do usuário do Granite
  - ter uma propriedade sling:resourceType, como estrutura de conteúdo padrão do Sling
  - pode ter uma propriedade helpPath para definir o recurso de ajuda sensível ao contexto (caminho absoluto ou relativo) que é acessado quando o ícone de Ajuda (o ? ) está selecionada.
    - Para componentes prontos para uso, isso geralmente faz referência a uma página na documentação.
    - Se não helpPath for especificada, o URL padrão (página de visão geral da documentação) será exibido.
Na caixa de diálogo , campos individuais são definidos:
IU Clássica
- dialog ( cq:Dialog) nós
  - definir a caixa de diálogo para editar o conteúdo deste componente
  - específico da interface clássica
  - são definidas usando widgets ExtJS
  - ter uma propriedade xtype, que se refere a ExtJS
  - pode ter uma propriedade helpPath para definir o recurso de ajuda sensível ao contexto (caminho absoluto ou relativo) que é acessado quando a variável Ajuda é selecionado.
    - Para componentes prontos para uso, isso geralmente faz referência a uma página na documentação.
    - Se não helpPath for especificada, o URL padrão (página de visão geral da documentação) será exibido.
Na caixa de diálogo , campos individuais são definidos:

Em uma caixa de diálogo clássica:
- você pode criar a caixa de diálogo como cq:Dialog, que fornecerá uma única guia - como no componente de texto, ou se você precisar de várias guias, como no componente de tempo de texto, a caixa de diálogo poderá ser definida como cq:TabPanel.
- a cq:WidgetCollection ( items) é usada para fornecer uma base para qualquer campo de entrada ( cq:Widget) ou outras guias ( cq:Widget). Essa hierarquia pode ser estendida.

Caixas de diálogo de design

As caixas de diálogo Design são muito semelhantes às caixas de diálogo usadas para editar e configurar o conteúdo, mas fornecem a interface para os autores configurar e fornecer detalhes de design para esse componente.

As caixas de diálogo Design estão disponíveis no Modo Design, embora não sejam necessários para todos os componentes, por exemplo Título e Imagem ambos têm diálogos de design, enquanto Texto não.

A caixa de diálogo de design do sistema de parágrafo (por exemplo, parsys) é um caso especial, pois permite que o usuário defina outros componentes específicos para serem selecionados (do navegador de componentes ou do sidekick) na página.

Adicionar seu componente ao sistema de parágrafos

Depois que um componente é definido, ele deve ser disponibilizado para uso. Para disponibilizar um componente para uso em um sistema de parágrafo, é possível:

Abrir Modo Design para uma página e habilite o componente desejado.
Adicione os componentes necessários ao components propriedade da definição do modelo em:

/etc/designs/<*yourProject*>/jcr:content/<*yourTemplate*>/par

Por exemplo, consulte:

/etc/designs/geometrixx/jcr:content/contentpage/par

Componentes e o conteúdo que eles criam

Se criarmos e configurarmos uma instância do Título componente na página: <content-path>/Prototype.html

Interface habilitada para toque
IU Clássica

Então podemos ver a estrutura do conteúdo criado no repositório:

screen_shot_2012-02-13at61405pm

Em particular, se você observar o texto real para uma Título:

a definição (para ambas as interfaces de usuário) tem a propriedade name= ./jcr:title
- /libs/foundation/components/title/cq:dialog/content/items/column/items/title
- /libs/foundation/components/title/dialog/items/title
no conteúdo, isso gera a propriedade jcr:title mantendo o conteúdo do autor.

As propriedades definidas dependem das definições individuais. Embora possam ser mais complexas do que acima, seguem ainda os mesmos princípios básicos.

Hierarquia e herança de componentes

Os componentes no AEM estão sujeitos a 3 hierarquias diferentes:

Hierarquia do Tipo de Recurso

Isso é usado para estender componentes usando a propriedade sling:resourceSuperType. Isso permite que o componente herde. Por exemplo, um componente de texto herdará vários atributos do componente padrão.
- scripts (resolvido pelo Sling)
- caixas de diálogo
- descrições (incluindo imagens em miniatura, ícones, etc.)
Hierarquia do contêiner

Isso é usado para preencher as configurações para o componente filho e é mais usado em um cenário parsys.

Por exemplo, as configurações dos botões da barra de edição, o layout do conjunto de controle (barras de edição, rolagem), o layout da caixa de diálogo (em linha, flutuante) podem ser definidos no componente pai e propagados para os componentes filho.

Configurações (relacionadas à funcionalidade de edição) em cq:editConfig e cq:childEditConfig são propagadas.
Incluir hierarquia

Isso é imposto no tempo de execução pela sequência de inclusões.

Essa hierarquia é usada pelo Designer, que, por sua vez, atua como base para vários aspectos de design da renderização; incluindo informações de layout, informações de css, os componentes disponíveis em um parsys, entre outros.

Editar comportamento

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 local e ouvintes relacionados a eventos no componente.

A configuração é comum à interface habilitada para toque e clássica, embora com determinadas diferenças específicas.

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:actions ( String array): define as ações que podem ser executadas no componente.
- cq:layout ( String): : define como o componente é editado na interface clássica.
- cq:dialogMode ( String): define como a caixa de diálogo do componente é aberta na interface clássica
  - Na interface habilitada para toque, as caixas de diálogo estão sempre flutuando no modo de desktop e abertas automaticamente como tela cheia em dispositivos móveis.
- cq:emptyText ( String): define o texto que é exibido quando nenhum conteúdo visual está presente.
- cq:inherit ( Boolean): define se os valores ausentes são herdados do componente do qual ele herda.
- dialogLayout (String): define como a caixa de diálogo deve ser aberta.
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
  - Vários destinos de soltar estão disponíveis somente na interface clássica.
  - Na interface habilitada para toque, é permitido um único destino de soltar.
- cq:actionConfigs (tipo de nó) nt:unstructured): define uma lista de novas ações que são anexadas à lista cq:actions.
- cq:formParameters (tipo de nó) nt:unstructured): O define parâmetros adicionais que são adicionados ao formulário de diálogo.
- cq:inplaceEditing (tipo de nó) cq:InplaceEditingConfig): define uma configuração de edição local para o componente.
- cq:listeners (tipo de nó) cq:EditListenersConfig): define o que acontece antes ou depois que uma ação ocorre no componente.

NOTE

Nesta página, um nó (propriedades e nós filhos) é representado como XML, como mostrado no exemplo a seguir.

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afteredit="REFRESH_PAGE"/>
</jcr:root>

Há muitas configurações existentes no repositório. Você pode pesquisar facilmente propriedades específicas ou nós secundários:

Para procurar uma propriedade do cq:editConfig nó, por exemplo cq:actions, você pode usar a ferramenta Query no CRXDE Lite e pesquise com a seguinte sequência de consulta XPath:

//element(cq:editConfig, cq:EditConfig)[@cq:actions]
Para procurar um nó filho de cq:editConfig, por exemplo, você pode pesquisar por cq:dropTargets, que é do tipo cq:DropTargetConfig; você pode usar a ferramenta Consulta em ** CRXDE Lite* e pesquisar com a seguinte string de consulta XPath:

//element(cq:dropTargets, cq:DropTargetConfig)

Marcadores de posição de componente

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.

Configurar com cq:EditConfig Properties

cq:actions

O cq:actions propriedade ( String array) define uma ou várias ações que podem ser executadas no componente. Os seguintes valores estão disponíveis para configuração:

Valor da propriedade	Descrição
`text:<some text>`	Exibe o valor do texto estático <some text=""> Visível somente na interface clássica. A interface habilitada para toque não exibe ações em um menu contextual, portanto, isso não é aplicável.
-	Adiciona um espaçador. Visível somente na interface clássica. A interface habilitada para toque não exibe ações em um menu contextual, portanto, isso não é aplicável.
`edit`	Adiciona um botão para editar o componente.
`editannotate`	Adiciona um botão para editar o componente, bem como permitir anotações.
`delete`	Adiciona um botão para excluir o componente
`insert`	Adiciona um botão para inserir um novo componente antes do atual
`copymove`	Adiciona um botão para copiar e recortar o componente.

A configuração a seguir adiciona um botão de edição, um espaçador, um botão de exclusão e um botão de inserção à barra de edição do componente:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit,-,delete,insert]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

A configuração a seguir adiciona o texto "Configurações herdadas da estrutura base" à barra de edição do componente:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[text:Inherited Configurations from Base Framework]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

cq:layout (somente interface clássica)

O cq:layout propriedade ( String) define como o componente pode ser editado na interface clássica. Os seguintes valores estão disponíveis:

Valor da propriedade	Descrição
`rollover`	Valor padrão. A edição do componente pode ser acessada "ao passar o mouse" por meio de cliques e/ou do menu de contexto. Para uso avançado, observe que o objeto correspondente do lado do cliente é: `CQ.wcm.EditRollover`.
`editbar`	A edição do componente é acessível por meio de uma barra de ferramentas. Para uso avançado, observe que o objeto correspondente do lado do cliente é: `CQ.wcm.EditBar`.
`auto`	A escolha é deixada ao código do lado do cliente.

NOTE

Os conceitos de sobreposição e barra de edição não são aplicáveis na interface habilitada para toque.

A configuração a seguir adiciona um botão de edição à barra de edição de componentes:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq:dialogMode (somente interface clássica)

O componente pode ser vinculado a uma caixa de diálogo de edição. O cq:dialogMode propriedade ( String) define como a caixa de diálogo do componente será aberta na interface clássica. Os seguintes valores estão disponíveis:

Valor da propriedade	Descrição
`floating`	A caixa de diálogo está flutuando.
`inline`	(Valor padrão). A caixa de diálogo é ancorada sobre o componente.
`auto`	Se a largura do componente for menor que o lado do cliente `CQ.themes.wcm.EditBase.INLINE_MINIMUM_WIDTH` , a caixa de diálogo está flutuando, caso contrário, está em linha.

NOTE

Na interface habilitada para toque, as caixas de diálogo estão sempre flutuando no modo de desktop e abertas automaticamente como tela cheia em dispositivos móveis.

A configuração a seguir define uma barra de edição com um botão de edição e uma caixa de diálogo flutuante:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq:emptyText

O cq:emptyText propriedade ( String) define o texto que é exibido quando nenhum conteúdo visual está presente. O padrão é: Drag components or assets here.

cq:herit

O cq:inherit propriedade ( boolean) define se os valores ausentes são herdados do componente do qual ele herda. O padrão é false.

dialogLayout

O dialogLayout define como uma caixa de diálogo deve ser aberta por padrão.

Um valor de fullscreen abre a caixa de diálogo em tela cheia.
Um valor vazio ou a ausência da propriedade assumem o padrão de abrir a caixa de diálogo normalmente.
Observe que o usuário sempre pode alternar o modo de tela cheia na caixa de diálogo.
Não se aplica à interface clássica.

Configurar com nós filho cq:EditConfig

cq:dropTargets

O cq:dropTargets nó (tipo de nó) nt:unstructured) define uma lista de destinos de soltar que podem aceitar uma queda de um ativo arrastado do localizador de conteúdo. Ele serve como uma coleção de nós do tipo cq:DropTargetConfig.

NOTE

Vários destinos de soltar estão disponíveis somente na interface clássica.

Na interface habilitada para toque, somente o primeiro destino será usado.

Cada nó filho do tipo cq:DropTargetConfig define um destino de soltar no componente. O nome do nó é importante porque ele deve ser usado no JSP, da seguinte maneira, para gerar o nome da classe CSS atribuído ao elemento DOM que é o destino final efetivo:

<drop target css class> = <drag and drop prefix> +
 <node name of the drop target in the edit configuration>

O <*drag and drop prefix*> é definido pela propriedade Java:

com.day.cq.wcm.api.components.DropTarget.CSS_CLASS_PREFIX.

Por exemplo, o nome da classe é definido da seguinte maneira no JSP do componente de Download
( /libs/foundation/components/download/download.jsp), onde file é o nome do nó do destino de soltar na configuração de edição do componente de Download:

String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";

O nó do tipo cq:DropTargetConfig precisa ter as seguintes propriedades:

Nome da Propriedade	Valor da propriedade
`accept`	Regex aplicado ao tipo MIME do ativo para validar se a queda é permitida.
`groups`	Matriz de grupos de destino de soltar. Cada grupo deve corresponder ao tipo de grupo definido na extensão do localizador de conteúdo e que está anexado aos ativos.
`propertyName`	Nome da propriedade que será atualizada após uma queda válida.

A configuração a seguir é obtida do componente Download . Ela ativa qualquer ativo (o tipo MIME pode ser qualquer string) da variável media grupo a ser descartado do localizador de conteúdo no componente. Após a queda, a propriedade do componente fileReference está sendo atualizado:

    <cq:dropTargets jcr:primaryType="nt:unstructured">
        <file
            jcr:primaryType="cq:DropTargetConfig"
            accept="[.*]"
            groups="[media]"
            propertyName="./fileReference"/>
    </cq:dropTargets>

cq:actionConfigs (somente interface clássica)

O cq:actionConfigs nó (tipo de nó) nt:unstructured) define uma lista de novas ações que são anexadas à lista definida pelo cq:actions propriedade. Cada nó filho de cq:actionConfigs define uma nova ação definindo um widget.

O exemplo de configuração a seguir define um novo botão (com um separador para a interface clássica):

um separador, definido pelo xtype tbseparator;
- Isso é usado somente pela interface clássica.
- Essa definição é ignorada pela interface habilitada para toque, pois xtypes são ignorados (e separadores são desnecessários, pois a barra de ferramentas de ação é construída de forma diferente na interface habilitada para toque).
um botão chamado Gerenciar comentários que executa a função do manipulador CQ_collab_forum_openCollabAdmin().

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
    cq:actions="[EDIT,COPYMOVE,DELETE,INSERT]"
    jcr:primaryType="cq:EditConfig">
    <cq:actionConfigs jcr:primaryType="nt:unstructured">
        <separator0
            jcr:primaryType="nt:unstructured"
            xtype="tbseparator"/>
        <manage
            jcr:primaryType="nt:unstructured"
            handler="function(){CQ_collab_forum_openCollabAdmin();}"
            text="Manage comments"/>
    </cq:actionConfigs>
</jcr:root>

NOTE

Consulte Adicionar nova ação a uma barra de ferramentas de componentes como exemplo para a interface habilitada para toque.

cq:formParameters

O cq:formParameters nó (tipo de nó) nt:unstructured) define parâmetros adicionais que são adicionados ao formulário de diálogo. Cada propriedade é mapeada para um parâmetro de formulário.

A configuração a seguir adiciona um parâmetro chamado name, defina com o valor photos/primary ao formulário de diálogo:

    <cq:formParameters
        jcr:primaryType="nt:unstructured"
        name="photos/primary"/>

cq:inplaceEditing

O cq:inplaceEditing nó (tipo de nó) cq:InplaceEditingConfig) define uma configuração de edição local para o componente. Pode ter as seguintes propriedades:

Nome da Propriedade	Valor da propriedade
`active`	(`boolean`) Verdadeiro para ativar a edição local do componente.
`configPath`	(`String`) Caminho da configuração do editor. A configuração pode ser especificada por um nó de configuração.
`editorType`	(`String`) Tipo de editor. Os tipos disponíveis são: texto simples: a ser usado para conteúdo não HTML. Título: é um editor de texto simples aprimorado que converte títulos gráficos em um texto simples antes do início da edição. Usado pelo componente de título do Geometrixx. texto: a ser usado para o conteúdo do HTML (usa o Editor de Rich Text).

A configuração a seguir permite a edição local do componente e define plaintext como tipo de editor:

    <cq:inplaceEditing
        jcr:primaryType="cq:InplaceEditingConfig"
        active="{Boolean}true"
        editorType="plaintext"/>

cq:listeners

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	Valor padrão (Somente interface clássica)
`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.
`beforemove`	O manipulador é acionado antes que o componente seja movido.
`beforeinsert`	O manipulador é acionado antes da inserção do componente. Somente operacional para a interface habilitada para toque.
`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.	`REFRESH_SELF`
`afteredit`	O manipulador é acionado após a edição do componente.	`REFRESH_SELF`
`aftercopy`	O manipulador é acionado após o componente ser copiado.	`REFRESH_SELF`
`afterinsert`	O manipulador é acionado após a inserção do componente.	`REFRESH_INSERTED`
`aftermove`	O manipulador é acionado após o componente ser movido.	`REFRESH_SELFMOVED`
`afterchildinsert`	O manipulador é acionado após o componente ser inserido em outro componente (somente contêineres).

NOTE

O REFRESH_INSERTED e REFRESH_SELFMOVED os manipuladores só estão disponíveis na interface clássica.

NOTE

Os valores padrão para os ouvintes são definidos somente na interface clássica.

NOTE

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); }"

NOTE

Para a interface clássica, para ver quais parâmetros podem ser usados nos manipuladores, consulte o before<action> e after<action> seção de eventos da CQ.wcm.EditBar e CQ.wcm.EditRollover documentação do widget.

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

Página anterior

Próxima página

Componentes AEM - Noções básicas

Visão geral

Planejamento

Interface habilitada para toque vs clássica

Lógica de conteúdo e marcação de renderização

HTL vs JSP

Desenvolvimento de seus próprios componentes

Mover componentes para a instância de publicação

Componentes a serem conhecidos desde o início

Estrutura

Tipo de recurso

Definição do componente

Noções básicas sobre componentes

Ícone de componente na interface do usuário de toque

Exemplo de ícone SVG

Propriedades e nós secundários de um componente

Caixas de diálogo

Caixas de diálogo de design

Adicionar seu componente ao sistema de parágrafos

Componentes e o conteúdo que eles criam

Hierarquia e herança de componentes

Editar comportamento

Marcadores de posição de componente

Configurar com cq:EditConfig Properties

cq:actions

cq:layout (somente interface clássica)

cq:dialogMode (somente interface clássica)

cq:emptyText

cq:herit

dialogLayout

Configurar com nós filho cq:EditConfig

cq:dropTargets

cq:actionConfigs (somente interface clássica)

cq:formParameters

cq:inplaceEditing

cq:listeners

Experience Manager