Componentes do Adobe Experience Manager (AEM) - Noções básicas aem-components-the-basics

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Tópicos:
Desenvolvimento

Criado para:

Desenvolvedor

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

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

Visão geral overview

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

Planejamento planning

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 todos os estágios de desenvolvimento, teste e entrega. 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 que permitem herdar e estender detalhes de outra definição de componente, incluindo substituição, sobreposição e o Sling Resource Merger.
O componente requer lógica para selecionar ou 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 precisa de formatação CSS?
- A formatação CSS deve ser mantida separada das definições de componentes. Defina convenções para nomear seus elementos de HTML para que você possa modificá-los por meio de arquivos CSS externos.
Quais aspectos de segurança devo considerar?
- Consulte Lista de verificação de segurança - Práticas recomendadas de desenvolvimento para obter mais detalhes.

Interface habilitada para toque vs. interface clássica touch-enabled-vs-classic-ui

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

Interface Habilitada para Toque
A interface de usuário padrão é baseada na experiência de usuário unificada da Adobe Experience Cloud, usando as tecnologias subjacentes da Interface do usuário do Coral e da Interface do usuário do Granite.
Interface clássica
Interface do usuário baseada na tecnologia ExtJS que foi descontinuada com o AEM 6.4.

Consulte Interface de 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 ambas. 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 para ambas.

As noções básicas de ambos são abordadas nesta página e como reconhecê-las.

NOTE

A Adobe recomenda o uso da interface habilitada para toque para se beneficiar da tecnologia mais recente. As Ferramentas de Modernização do AEM podem facilitar a migração.

Lógica de conteúdo e marcação de renderização content-logic-and-rendering-markup

A Adobe recomenda manter o código responsável pela marcação e renderização separado do código que controla a lógica usada para selecionar o conteúdo do componente.

Esta filosofia é suportada pelo HTL, uma linguagem de modelo que é propositalmente limitada para garantir que uma linguagem de programação real seja usada para definir a lógica de negócios subjacente. Essa lógica (opcional) é invocada do HTL com um comando específico. Esse mecanismo destaca o código chamado para uma determinada exibição e, se necessário, permite uma lógica específica para diferentes exibições do mesmo componente.

HTL vs JSP htl-vs-jsp

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

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

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

NOTE

As exceções são Campos de formulário do Granite UI Foundation (como usados em caixas de diálogo). Elas ainda exigem o uso do JSP.

Desenvolver seus próprios componentes developing-your-own-components

Para criar seus próprios componentes para a interface 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:

Desenvolvendo componentes (com foco na interface habilitada para toque)

Mover componentes para a instância do Publish moving-components-to-the-publish-instance

Os componentes que renderizam conteúdo devem ser implantados na mesma instância do AEM que o 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:

Use o Gerenciador de Pacotes para adicionar seus componentes a um pacote e movê-los para outra instância de AEM.
Use a ferramenta de replicação Ativar Á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 que devem ser considerados desde o início components-to-be-aware-of-from-the-start

Página:
- AEM tem o componente página ( 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 com conteúdo para o seu site.
Sistemas de parágrafos:
- O sistema de parágrafos é 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.
- É possível 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-65/sites-authoring/responsive-layout.md)).

Estrutura structure

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

Tipo de recurso
Definição de componente
Propriedades e nós filhos 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 resource-type

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

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

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

Definição de componente component-definition

Noções básicas sobre componentes component-basics

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

Componentes de AEM baseados em Sling.
Os componentes do AEM estão (geralmente) localizados em:
- HTL: /libs/wcm/foundation/components
- JSP: /libs/foundation/components
Os componentes específicos do projeto/site estão (geralmente) localizados em:
- /apps/<myApp>/components
Os componentes padrão do AEM são definidos como cq:Component e têm os seguintes elementos-chave:
- propriedades jcr:
  
  Uma lista de propriedades jcr; elas 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 definição cq:Component
- 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ó hierárquico do componente.
Propriedades Vitais:
- jcr:title - Título do componente; por exemplo, usado como rótulo quando o componente é listado no navegador de componentes ou sidekick.
- jcr:description - Descrição do componente; pode ser usado como dica de passar o mouse sobre o navegador de componentes ou sidekick.
- Interface clássica:
  - icon.png - Ícone para este componente.
  - thumbnail.png - Imagem mostrada se este componente está listado no sistema de parágrafos.
- Interface de toque
  - Consulte a seção Ícone de Componente na Interface para Toque para obter detalhes.
Nós-Filhos Vitais:
- cq:editConfig (cq:EditConfig) - Define as propriedades de edição do componente e habilita o componente para aparecer no navegador de Componentes ou Sidekick.
  
  Observação: se o componente tiver uma caixa de diálogo, ele aparecerá automaticamente no navegador de Componentes ou Sidekick, mesmo se cq:editConfig não existir.
- cq:childEditConfig (cq:EditConfig) - Controla os aspectos da interface do usuário do autor para componentes filho que não definem seu próprio cq:editConfig.
- Interface habilitada para toque:
  - cq:dialog ( nt:unstructured) - Caixa de diálogo para este 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
- Interface clássica:
  - dialog ( cq:Dialog) - Caixa de diálogo para este componente. Define a interface que permite ao usuário configurar o componente ou editar o conteúdo, ou ambos.
  - design_dialog ( cq:Dialog) - Edição de design para este componente.

Ícone de componente na interface para toque component-icon-in-touch-ui

O ícone ou a abreviação do componente é definido por meio das propriedades JCR do componente quando ele é criado pelo desenvolvedor. Essas propriedades são avaliadas na seguinte ordem e a primeira propriedade válida encontrada é usada.

cq:icon - Propriedade de cadeia de caracteres apontando para um ícone padrão na biblioteca de interface do Coral para ser exibida no navegador de componentes
- Use o valor do atributo HTML do ícone Coral.
abbreviation - Propriedade de cadeia de caracteres para personalizar a abreviação do nome do componente no navegador de componentes
- A abreviação deve ser limitada a dois caracteres.
- Fornecer uma cadeia de caracteres vazia cria a abreviação dos dois primeiros caracteres da propriedade jcr:title.
  - Por exemplo, "Im" para "Image"
  - O título localizado é usado para criar a abreviação.
- A abreviação só será traduzida se o componente tiver uma propriedade abbreviation_commentI18n, que será usada como dica de tradução.
cq:icon.png ou cq:icon.svg - Ícone para este componente, que é mostrado no navegador de componentes
- 20 x 20 pixels é o tamanho dos ícones dos componentes padrão.
  - Ícones maiores são reduzidos (lado do cliente).
- A cor recomendada é rgb(112, 112, 112) > #707070
- O plano de fundo dos ícones de componente padrão é transparente.
- Somente .png e .svg arquivos são suportados.
- Se você estiver importando do sistema de arquivos por meio do plug-in Eclipse, os nomes de arquivos devem 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) for encontrada no componente:

O sistema procura as mesmas propriedades nos supercomponentes após a propriedade sling:resourceSuperType.
Se nada ou uma abreviação vazia for encontrada no nível do supercomponente, o sistema criará a abreviação a partir das primeiras letras da propriedade jcr:title do componente atual.

Para cancelar a herança de ícones dos supercomponentes, definir uma propriedade abbreviation vazia no componente reverte para o comportamento padrão.

O Console de Componentes exibe como o ícone de um componente específico é definido.

Exemplo de ícone do SVG svg-icon-example

<?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 filhos de um componente properties-and-child-nodes-of-a-component

Muitos dos nós/propriedades necessários para definir um componente são comuns a ambas as interfaces do usuário, com diferenças permanecendo 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 filhos:

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 Sidekick (interface clássica).
Um valor de .hidden é usado para componentes que não estão disponíveis para seleção na interface do usuário, como os sistemas de parágrafos 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 da 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 da interface clássica.

dialogPath

String

Caminho para uma caixa de diálogo para cobrir o caso quando o componente não tem um nó de caixa de diálogo.

cq:cellName

String

Se definida, essa propriedade será tomada como ID da célula. Para obter mais informações, consulte o artigo da Base de Dados de Conhecimento Como as IDs de Células de Design são criadas.

cq:childEditConfig

cq:EditConfig

Quando o componente é um contêiner, por exemplo, um sistema de parágrafo, ele 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 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 template de conteúdo quando o componente for adicionado do Navegador de componentes ou Sidekick.

cq:templatePath

String

Caminho para um nó a ser usado como modelo de conteúdo quando o componente for adicionado do navegador de Componentes ou 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 é necessário e cq:template é suficiente (veja 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 deste 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

Ícone do componente, aparece ao lado do Título no Sidekick.

thumbnail.png

nt:file

Miniatura opcional que é mostrada enquanto o componente é arrastado para o lugar do Sidekick.

Se você observar o componente Texto (qualquer versão), poderá ver estes elementos:

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

As propriedades de particular interesse incluem:

jcr:title - título do componente; pode ser usado para identificar o componente, por exemplo, ele aparece na lista de componentes dentro do navegador de componentes ou sidekick
jcr:description - descrição do componente; pode ser usado como uma dica de passar o mouse sobre ele na 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 específico incluem:

cq:editConfig ( cq:EditConfig) - controla aspectos visuais; por exemplo, pode definir a aparência de uma barra ou widget, ou pode adicionar controles personalizados
cq:childEditConfig ( cq:EditConfig) - controla os aspectos visuais dos componentes filhos que não têm 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 deste componente
Interface clássica:
- dialog ( cq:Dialog) - define a caixa de diálogo para editar o conteúdo deste componente (específico da interface clássica)
- design_dialog ( cq:Dialog) - especifica as opções de edição de design deste componente
- icon.png - arquivo gráfico a ser usado como um í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 dialogs

As caixas de diálogo são um elemento essencial do componente, pois fornecem uma interface para que os autores configurem e forneçam entrada para esse componente.

Dependendo da complexidade do componente, sua 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 habilitada para toque pode usar a definição de uma caixa de diálogo da interface clássica, quando nenhuma caixa de diálogo foi definida para a interface habilitada para toque.
As Ferramentas de Modernização do AEM também são fornecidas para ajudar a estender/converter componentes que têm apenas caixas de diálogo definidas para a interface clássica.

Interface de usuário habilitada para toque
- Nós de cq:dialog ( nt:unstructured):
  - definir a caixa de diálogo para editar o conteúdo deste componente
  - específico para a interface habilitada para toque
  - são definidos usando componentes de interface do Granite
  - tem uma propriedade sling:resourceType, como estrutura de conteúdo Sling padrão
  - O pode ter uma propriedade helpPath para definir o recurso de ajuda sensível ao contexto (caminho absoluto ou relativo) que é acessado quando o ícone Ajuda (o ícone ?) é selecionado.
    - Para componentes prontos para uso, isso geralmente faz referência a uma página na documentação.
    - Se nenhum helpPath for especificado, a URL padrão (página de visão geral da documentação) será exibida.
Na caixa de diálogo, os campos individuais são definidos:
IU Clássica
- dialog nós ( cq:Dialog)
  - definir a caixa de diálogo para editar o conteúdo deste componente
  - específico para a interface clássica
  - são definidos usando widgets ExtJS
  - tem uma propriedade xtype, que se refere a ExtJS
  - O pode ter uma propriedade helpPath para definir o recurso de ajuda sensível ao contexto (caminho absoluto ou relativo) que é acessado quando o botão Ajuda é selecionado.
    - Para componentes prontos para uso, isso geralmente faz referência a uma página na documentação.
    - Se nenhum helpPath for especificado, a URL padrão (página de visão geral da documentação) será exibida.
Na caixa de diálogo, os 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 com o componente textimage, a caixa de diálogo pode ser definida como cq:TabPanel.
- um cq:WidgetCollection ( items) é usado para fornecer uma base para campos de entrada ( cq:Widget) ou outras guias ( cq:Widget). Essa hierarquia pode ser estendida.

Caixas de diálogo de design design-dialogs

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

As Caixas de diálogo de design estão disponíveis no Modo de Design, embora não sejam necessárias para todos os componentes, por exemplo, Título e Imagem têm caixas de diálogo 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 disponibilize outros componentes específicos para seleção (no navegador de componentes ou sidekick) na página.

Adicionar o componente ao sistema de parágrafos adding-your-component-to-the-paragraph-system

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

Abra o Modo de Design de uma página e habilite o componente necessário.
Adicione os componentes necessários à propriedade components da sua definição de 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 components-and-the-content-they-create

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

Interface de usuário habilitada para toque
IU Clássica

Em seguida, é possível ver a estrutura do conteúdo criado no repositório:

screen_shot_2012-02-13at61405pm

Especificamente, se você observar o texto real de um Título:

a definição (para ambas as interfaces) tem a propriedade name= ./jcr:title
- /libs/foundation/components/title/cq:dialog/content/items/column/items/title
- /libs/foundation/components/title/dialog/items/title
dentro do conteúdo, isso gera a propriedade jcr:title que contém o conteúdo do autor.

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

Hierarquia e herança do componente component-hierarchy-and-inheritance

Os componentes dentro do AEM estão sujeitos a três hierarquias diferentes:

Hierarquia de 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 herda vários atributos do componente padrão.
- scripts (resolvidos pelo Sling)
- caixas de diálogo
- descrições (incluindo imagens em miniatura e ícones)
Hierarquia do contêiner

Isso é usado para preencher as definições de configuração para o componente secundário e é usado com mais frequência 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 principal e propagados para os componentes secundários.

As definições de configuração (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 edit-behavior

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

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

O comportamento de edição de um componente é configurado adicionando um nó cq:editConfig do tipo cq:EditConfig abaixo do nó do componente (do tipo cq:Component) e adicionando propriedades específicas e nós filhos. As seguintes propriedades e nós filhos 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 desktop e são 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 é herdado.
- dialogLayout (Cadeia de caracteres): 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 descarte que podem aceitar um descarte de um ativo do localizador de conteúdo
  - Vários destinos de lançamento estão disponíveis somente na interface clássica.
  - Na interface habilitada para toque, um único destino de soltar é permitido.
- 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): define parâmetros adicionais que são adicionados ao formulário da caixa 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 de uma ação ocorrer no componente.

NOTE

Nesta página, um nó (propriedades e nós filhos) é representado como XML, conforme 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 por propriedades específicas ou nós secundários:

Para procurar uma propriedade do nó cq:editConfig, por exemplo, cq:actions, você pode usar a ferramenta Query em CRXDE Lite e pesquisar 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 procurar por cq:dropTargets, que é do tipo cq:DropTargetConfig; você pode usar a ferramenta Consulta em** CRXDE Lite* e pesquisar com a seguinte sequência de consulta XPath:

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

Marcadores de posição do componente component-placeholders

Os componentes sempre devem renderizar algum HTML que esteja visível para o autor, mesmo quando o componente não tiver conteúdo. Caso contrário, ela poderá desaparecer visualmente da interface do editor, tornando-se tecnicamente presente, mas invisível na página e no editor. Nesse caso, os autores não podem selecionar e interagir com o componente vazio.

Por esse motivo, 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 for edit ou preview).
A marcação de HTML típica de 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 só é verdadeira quando o componente não tem conteúdo e está invisível para o autor.

Para evitar repetição, o Adobe recomenda que os implementadores de componentes usem um modelo HTL para esses espaços reservados, como o fornecido pelos Componentes Principais.

O uso do modelo 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 só é verdadeira quando o conteúdo tem conteúdo e está visível.

Um exemplo de uso deste modelo pode ser visto nos Componentes Principais, como no Componente de Título.

Configuração com propriedades cq:EditConfig configuring-with-cq-editconfig-properties

cq:actions cq-actions

A propriedade cq:actions ( 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 de propriedade

Descrição

text:<some text>

Exibe o valor de texto estático <algum texto>
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 se aplica.

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 se aplica.

edit

Adiciona um botão para editar o componente.

editannotate

Adiciona um botão para editar o componente e 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) cq-layout-classic-ui-only

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

Valor de propriedade

Descrição

rollover

Valor padrão. A edição do componente é acessível "ao passar o mouse" por meio de cliques e/ou menu de contexto.
Para uso avançado, 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, o objeto correspondente do lado do cliente é: CQ.wcm.EditBar.

auto

A escolha é deixada para o código do lado do cliente.

NOTE

Os conceitos de rolagem e barra de edição não se aplicam à interface habilitada para toque.

A configuração a seguir adiciona um botão de ediçã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]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq:dialogMode (somente interface clássica) cq-dialogmode-classic-ui-only

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

Valor de propriedade

Descrição

floating

A caixa de diálogo está flutuando.

inline

(valor padrão). A caixa de diálogo está ancorada no componente.

auto

Se a largura do componente for menor que o valor CQ.themes.wcm.EditBase.INLINE_MINIMUM_WIDTH do lado do cliente, a caixa de diálogo será flutuante, caso contrário, será embutida.

NOTE

Na interface habilitada para toque, as caixas de diálogo estão sempre flutuando no modo de desktop e são 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 cq-emptytext

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

cq:inherit cq-inherit

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

dialogLayout dialoglayout

A propriedade 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 ausência da propriedade é padronizado para abrir a caixa de diálogo normalmente.
O usuário sempre pode alternar o modo de tela cheia na caixa de diálogo.
Não se aplica à interface clássica.

Configuração com nós filhos cq:EditConfig configuring-with-cq-editconfig-child-nodes

cq:dropTarget cq-droptargets

O nó cq:dropTargets (tipo de nó nt:unstructured) define uma lista de destinos de lançamento que podem aceitar o descarte 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 lançamento estão disponíveis somente na interface clássica.

Na interface habilitada para toque, somente o primeiro target é usado.

Cada nó filho do tipo cq:DropTargetConfig define um destino de liberação no componente. O nome do nó é importante porque deve ser usado no JSP, da seguinte maneira, para gerar o nome da classe CSS atribuído ao elemento DOM que é o destino de liberação 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 lançamento na configuração de edição do componente de Download:

String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";

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

Nome de propriedade

Valor de propriedade

accept

Regex aplicado ao tipo MIME do ativo para validar se a remoção é permitida.

groups

Matriz de grupos de destino de lançamento. Cada grupo deve corresponder ao tipo de grupo definido na extensão do localizador de conteúdo e anexado aos ativos.

propertyName

Nome da propriedade que será atualizada após uma queda válida.

A configuração a seguir é retirada do componente de Download. Ela habilita qualquer ativo (o tipo MIME pode ser qualquer cadeia de caracteres) do grupo media a ser descartado do localizador de conteúdo no componente. Após a remoção, a propriedade do componente fileReference está sendo atualizada:

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

cq:actionConfigs (somente interface clássica) cq-actionconfigs-classic-ui-only

O nó cq:actionConfigs (tipo de nó nt:unstructured) define uma lista de novas ações que são anexadas à lista definida pela propriedade cq:actions. 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 os xtypes são ignorados (e os 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 de 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 componente como exemplo para a interface habilitada para toque.

cq:formParameters cq-formparameters

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

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

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

cq:inplaceEditing cq-inplaceediting

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

Nome de propriedade

Valor de propriedade

active

(boolean) Verdadeiro para habilitar 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 sem formatação: para ser usado para conteúdo não-HTML.
título: é um editor de texto sem formatação aprimorado que converte títulos gráficos em texto sem formatação antes de começar a edição. Usado pelo componente Geometrixx title.
text: a ser usado para conteúdo de HTML (usa o Editor de Rich Text).

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

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

cq:listeners cq-listeners

O nó cq:listeners (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 de propriedade

Valor de propriedade

Valor padrão

(Somente interface clássica)

beforedelete

O manipulador é disparado 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.
Operacional somente para a interface habilitada para toque.

beforechildinsert

O manipulador é acionado antes que o componente seja inserido dentro de outro componente (somente contêineres).

afterdelete

O manipulador é acionado após a remoção do componente.

REFRESH_SELF

afteredit

O manipulador é acionado depois que o componente é editado.

REFRESH_SELF

aftercopy

O manipulador é acionado depois que o componente é copiado.

REFRESH_SELF

afterinsert

O manipulador é acionado após a inserção do componente.

REFRESH_INSERTED

aftermove

O manipulador é acionado depois que o componente é movido.

REFRESH_SELFMOVED

afterchildinsert

O manipulador é acionado depois que o componente é inserido dentro de outro componente (somente contêineres).

NOTE

Os manipuladores REFRESH_INSERTED e REFRESH_SELFMOVED 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

Se houver componentes aninhados, há certas restrições nas ações definidas como propriedades no nó cq:listeners:

Para componentes aninhados, os valores das seguintes propriedades devem ser 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 à configuração REFRESH_INSERTED:

afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"

NOTE

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

Com a seguinte configuração, a página é atualizada depois que o componente é excluído, editado, inserido ou movido:

    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afterdelete="REFRESH_PAGE"
        afteredit="REFRESH_PAGE"
        afterinsert="REFRESH_PAGE"
        afterMove="REFRESH_PAGE"/>

recommendation-more-help

19ffd973-7af2-44d0-84b5-d547b0dffee2