AEM componentes são usados para manter, formatar e renderizar o conteúdo disponibilizado em suas páginas da Web.
Quando páginas de criação, os componentes permitem que os autores editem e configurem o conteúdo.
Ao construir um site Commerce, os componentes podem, por exemplo, coletar e renderizar informações do catálogo.
Consulte Desenvolvimento do eCommerce para obter mais informações.
Ao construir um site Communities, os componentes podem fornecer informações e coletar informações de seus visitantes.
Consulte Desenvolvimento de comunidades para obter mais informações.
Na instância de publicação, os componentes renderizam o conteúdo, apresentando-o conforme necessário aos visitantes do site.
Esta página é uma continuação do documento AEM Componentes - Informações básicas.
Os componentes abaixo de /libs/cq/gui/components/authoring/dialog
devem ser usados somente no Editor (caixas de diálogo de componentes em Criação). Se forem usados em outro lugar (como em uma caixa de diálogo do assistente, por exemplo), eles podem não se comportar como esperado.
Esta página fornece a documentação de referência (ou links para a documentação de referência) necessária para desenvolver novos componentes para AEM. Consulte Desenvolvimento de componentes AEM - Exemplos de código para obter alguns exemplos práticos.
A estrutura básica de um componente é abordada na página AEM Componentes - Informações básicas. Esse documento abrange as interfaces de usuário habilitadas para toque e clássica. Mesmo que você não precise usar as configurações clássicas em seu novo componente, pode ajudar a conhecê-las ao herdar dos componentes existentes.
Dependendo do componente que você deseja implementar, talvez seja possível estender ou personalizar uma instância existente, em vez de definir e desenvolver toda a estrutura do zero.
Ao estender ou personalizar um componente ou uma caixa de diálogo existente, é possível copiar ou replicar toda a estrutura ou a estrutura necessária para a caixa de diálogo antes de fazer as alterações.
A extensão de um componente existente pode ser alcançada com Hierarquia de Tipo de Recurso e os mecanismos de herança relacionados.
Os componentes também podem ser redefinidos com uma sobreposição baseada na lógica do caminho de pesquisa. Entretanto, nesse caso, Fusão de recursos Sling não será acionada e /apps
deverá definir a sobreposição inteira.
O componente de fragmento de conteúdo também pode ser personalizado e estendido, embora a estrutura completa e os relacionamentos com Ativos devam ser considerados.
Também é possível substituir uma caixa de diálogo componente usando Fusão de Recursos de Sling 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 (usando sling:resourceSuperType
). Esse método agora é recomendado para estender uma caixa de diálogo de componente
Consulte Fusão de recursos Sling para obter mais detalhes.
Seu componente será renderizado com HTML. Seu componente precisa definir o HTML necessário para pegar o conteúdo necessário e, em seguida, renderizá-lo conforme necessário, nos ambientes de autor e publicação.
O HTML Templating Language (HTL), introduzido com AEM 6.0, substitui o JSP (JavaServer Pages) como o sistema de modelo preferencial e recomendado do lado do servidor para HTML. Para desenvolvedores da Web que precisam criar sites corporativos robustos, o HTL ajuda a aumentar a segurança e a eficiência do desenvolvimento.
Embora o HTL e o JSP possam ser usados para desenvolver componentes, ilustraremos o desenvolvimento com o HTL nesta página, já que é a linguagem de script recomendada para AEM.
Essa lógica opcional seleciona e/ou calcula o conteúdo a ser renderizado. Ele é chamado das expressões HTL com o padrão Use-API apropriado.
O mecanismo para separar a lógica da aparência ajuda a esclarecer o que é chamado para uma determinada visualização. Também permite lógica diferente para visualizações diferentes do mesmo recurso.
A HTL Java Use-API permite que um arquivo HTL acesse métodos auxiliares em uma classe Java personalizada. Isso permite usar o código Java para implementar a lógica de seleção e configuração do conteúdo do componente.
A API de uso do JavaScript HTL permite que um arquivo HTL acesse o código auxiliar escrito em JavaScript. Isso permite usar o código JavaScript para implementar a lógica de seleção e configuração do conteúdo do componente.
Sites modernos dependem muito do processamento no cliente, conduzido por códigos complexos de JavaScript e CSS. Organizar e otimizar a entrega desse código pode ser um problema complicado.
Para ajudar a lidar com esse problema, AEM fornece Pastas de biblioteca do lado do cliente, que permitem armazenar o código do lado do cliente no repositório, organizá-lo no categoria e definir quando e como cada categoria de código deve ser fornecida ao cliente. O sistema de biblioteca do lado do cliente cuida de produzir os links corretos em sua página da Web final para carregar o código correto.
Leia Usando bibliotecas HTML do lado do cliente para obter mais informações.
Você pode configurar o comportamento de edição de um componente incluindo atributos, como ações disponíveis para o componente, características do editor local e os ouvintes relacionados aos eventos no componente. A configuração é comum à interface habilitada para toque e clássica, embora com certas diferenças específicas.
O comportamento editar 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 e nós secundários específicos.
O cookie WCM Mode é definido ao alternar para o modo Pré-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 se atualizarem especificamente e, em seguida, dependem do valor do cookie.
Na interface habilitada para toque, somente os valores EDIT
e PREVIEW
são usados para o cookie WCM Mode.
As caixas de diálogo são usadas para permitir que o autor interaja com o componente. O uso de uma caixa de diálogo permite que autores e/ou administradores editem conteúdo, configurem o componente ou definam parâmetros de design (usando uma Caixa de diálogo de design)
A interface do usuário do Coral e a interface do usuário do Granite definem a aparência moderna do AEM.
A interface do usuário do Granite fornece uma grande variedade dos componentes básicos (widgets) necessários para criar sua caixa de diálogo no ambiente de criação. Quando necessário, você pode estender essa seleção e criar seu próprio widget.
Para obter mais informações sobre como desenvolver componentes usando os tipos de recursos Coral e Granite, consulte: Construção de componentes Experience Manager usando os tipos de recursos Coral/Granite.
Para obter detalhes completos, consulte:
Interface do usuário do Coral
Interface do usuário Granite
Caixas de diálogo para a interface habilitada para toque:
são nomeados como cq:dialog
.
são definidos como um nó nt:unstructured
com o conjunto de propriedades sling:resourceType
.
estão localizados no nó cq:Component
e ao lado da definição do componente.
são renderizados no lado do servidor (como componentes Sling), com base em sua estrutura de conteúdo e na propriedade sling:resourceType
.
use a estrutura da interface do usuário do Granite.
contém uma estrutura de nó que descreve os campos na caixa de diálogo.
nt:unstructured
com a propriedade sling:resourceType
necessária.Uma estrutura de nó de exemplo pode ser:
newComponent (cq:Component)
cq:dialog (nt:unstructured)
content
layout
items
column
items
file
description
A personalização de uma caixa de diálogo é semelhante ao desenvolvimento de um componente, já que a caixa de diálogo é um componente (isto é, uma marcação renderizada por um script de componente junto com o comportamento/estilo fornecido por uma biblioteca de cliente).
Para obter exemplos, consulte:
/libs/foundation/components/text/cq:dialog
/libs/foundation/components/download/cq:dialog
Se um componente não tiver uma caixa de diálogo definida para a interface habilitada para toque, a caixa de diálogo clássica da interface do usuário será usada como um fallback dentro de uma camada de compatibilidade. Para personalizar essa caixa de diálogo, é necessário personalizar a caixa de diálogo da interface clássica. Consulte AEM Componentes para a interface clássica.
Consulte:
Os widgets da interface habilitada para toque são implementados como componentes da interface de usuário Granite.
Para criar um novo widget para uso em uma caixa de diálogo de componente para a interface do usuário habilitada para toque, é necessário criar um novo componente de campo da interface do usuário do Granite.
Para obter detalhes completos sobre a interface do usuário do Granite, consulte a documentação da interface do usuário do Granite.
Se você considerar sua caixa de diálogo como um container simples para um elemento de formulário, 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 ajudá-lo nessa tarefa, a interface do usuário do Granite oferta 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 diálogos (ou, de modo mais geral, em formulários).
Isso difere da interface clássica, onde os widgets são representados por nós cq:Widgets
, cada um com um xtype
específico para estabelecer a relação com seu widget ExtJS correspondente. Do ponto de vista da implementação, esses widgets foram renderizados no lado do cliente pela estrutura ExtJS.
Depois de criar seu tipo de recurso, você pode instanciar seu campo adicionando um novo nó na caixa de diálogo, com a propriedade sling:resourceType
referindo-se ao tipo de recurso que você acabou de apresentar.
Se quiser definir o estilo e o comportamento do seu componente, você pode criar uma biblioteca do cliente que defina seu CSS/LESS e JS personalizados.
Para que a biblioteca do cliente seja carregada exclusivamente para a caixa de diálogo do seu componente (isto é, ela não será carregada para outro componente), é necessário definir a propriedade extraClientlibs
* da sua caixa de diálogo com o nome da categoria da biblioteca do cliente que você acabou de criar. Isso é aconselhável se a biblioteca do cliente for muito grande e/ou seu campo for específico dessa caixa de diálogo e não for necessário em outras caixas de diálogo.
Para que a biblioteca do cliente seja carregada para todas as caixas de diálogo, defina a propriedade de categoria da biblioteca do cliente como cq.authoring.dialog
. Esse é o nome da categoria da biblioteca do cliente que é incluída por padrão ao renderizar todas as caixas de diálogo. Você deseja fazer isso se a biblioteca do cliente for pequena e/ou seu campo for genérico e puder ser reutilizado em outras caixas de diálogo.
Para ver um exemplo, consulte:
cqgems/customizingfield/components/colorpicker/clientlibs
Dependendo dos seus requisitos, você pode:
sling:resourceSuperType
)Você também pode 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"]
O método de manipulação de eventos nos campos de diálogo agora é feito com ouvintes em uma biblioteca cliente personalizada. Esta é uma alteração do método mais antigo de ter ouvintes na estrutura de conteúdo.
Para injetar lógica no seu campo, deve:
Para isso, é necessário saber mais sobre a biblioteca de widgets subjacente com a qual você deseja interagir. Consulte a documentação da interface do usuário coral para identificar a qual evento você deseja reagir. Isso é muito semelhante ao processo que você tinha que executar com ExtJS no passado: localize a página de documentação de um determinado widget e verifique os detalhes de sua API de evento.
Para ver um exemplo, consulte:
cqgems/customizingfield/components/clientlibs/customizingfield
Na interface clássica com ExtJS, era comum ter ouvintes para um determinado widget na estrutura de conteúdo. Alcançar o mesmo na interface habilitada para toque é diferente do código de ouvinte JS (ou qualquer código) não é mais definido no conteúdo.
A estrutura do conteúdo descreve a estrutura semântica; não deve (deve) implicar a natureza do widget subjacente. Ao não ter o código JS na estrutura de conteúdo, você pode alterar os detalhes da implementação sem precisar alterar a estrutura de conteúdo. Em outras palavras, é possível alterar a biblioteca de widgets sem precisar tocar na estrutura de conteúdo.
Se você tiver um JavaScript personalizado que precisa ser executado somente quando a caixa de diálogo estiver disponível e pronta, você deve acompanhar o evento dialog-ready
.
Esse evento é acionado sempre que a caixa de diálogo é carregada (ou recarregada) e está pronto 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 usado para conectar-se ao código personalizado JavaScript que executa personalizações nos campos dentro de uma caixa de diálogo ou tarefas semelhantes.
Para marcar um determinado campo como obrigatório, defina a seguinte propriedade no nó de conteúdo do seu campo:
required
Boolean
Para ver um exemplo, consulte:
/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title
A validação de campo na interface do usuário do Granite e nos Componentes da interface do usuário do Granite (equivalente aos widgets) é feita usando a API foundation-validation
. Consulte a documentação do foundation-valdiation
Granite para obter detalhes.
Para obter exemplos, consulte:
cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js
/libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js
A caixa de diálogo Design é fornecida quando um componente tem detalhes de design que podem ser editados em Modo Design.
A definição é muito semelhante à de uma caixa de diálogo usada para editar conteúdo, com a diferença de que ela é definida como um nó:
cq:design_dialog
nt:unstructured
Um editor local permite que o usuário edite o conteúdo diretamente no fluxo de parágrafo, sem a necessidade de abrir uma caixa de diálogo. Por exemplo, os componentes padrão Texto e Título têm um editor local.
Um editor local não é necessário/significativo para cada tipo de componente.
Consulte Extensão da criação de páginas - Adicionar novo editor local para obter mais informações.
A Barra de ferramentas do componente dá ao usuário acesso a uma variedade de ações para o componente, como editar, configurar, copiar e excluir.
Consulte Extensão da criação de páginas - Adicionar nova ação a uma barra de ferramentas de componentes para obter mais informações.
Se o novo componente fizer referência ao conteúdo de outras páginas, você poderá considerar se deseja que ele afete as seções Conteúdo emprestado e Conteúdo emprestado do painel Referências.
A AEM predefinida verifica apenas o componente de referência. Para adicionar seu componente, é necessário configurar o pacote OSGi Configuração de referência de conteúdo de criação do WCM.
Crie uma nova entrada na definição, especificando seu componente, junto com a propriedade a ser verificada. Por exemplo:
/apps/<*your-Project*>/components/reference@parentPath
Ao trabalhar com AEM existem vários métodos de gerenciamento das configurações para esses serviços. Consulte Configuração do OSGi para obter mais detalhes e as práticas recomendadas.
Depois que o componente é desenvolvido, ele precisa ser habilitado para uso em um sistema de parágrafo apropriado, para que possa ser usado nas páginas necessárias.
Isso pode ser feito:
components
propriedade no sistema de parágrafo de um modelo.AEM oferta a possibilidade de configurar um sistema de parágrafo em sua página para que uma instância do novo componente seja automaticamente criada quando um usuário arrasta um ativo (apropriado) para uma instância dessa página (em vez de sempre ter que arrastar um componente vazio para a página).
Este comportamento e a relação entre ativos e componentes necessária podem ser configurados:
Na definição de parágrafo do design da página. Por exemplo:
/etc/designs/<myApp>/page/par
Criar um novo nó:
cq:authoring
nt:unstructured
Sob isso, crie um novo nó para manter todos os mapeamentos ativo-componente:
assetToComponentMapping
nt:unstructured
Para cada mapeamento de ativo para componente, crie um nó:
nt:unstructured
Cada um com as seguintes propriedades:
assetGroup
:
String
media
assetMimetype
:
String
image/*
droptarget
:
String
image
resourceType
:
String
foundation/components/image
type
:
String
Images
Para obter exemplos, consulte:
/etc/designs/geometrixx/jcr:content/page/par/cq:authoring
/etc/designs/geometrixx-outdoors/jcr:content/page/par/cq:authoring
/etc/designs/geometrixx-media/jcr:content/article/article-content-par/cq:authoring
CÓDIGO NO GITHUB
Você pode encontrar o código desta página no GitHub
A criação automática de instâncias de componentes agora pode ser configurada facilmente na interface do usuário ao usar Componentes principais e Modelos editáveis. Consulte Criação de modelos de página para obter mais informações sobre como definir quais componentes são associados automaticamente a determinados tipos de mídia.
O AEM Brackets Extension fornece um fluxo de trabalho suave para editar AEM componentes e bibliotecas de clientes. Ele é baseado no editor de códigos Colchetes.
A extensão:
Os suportes são o mecanismo recomendado para a criação de componentes. Substitui a funcionalidade CRXDE Lite - Criar componente, que foi projetada para a interface clássica.
Ao migrar um componente projetado para uso com a interface clássica para um componente que pode ser usado com a interface habilitada para toque (individual ou conjuntamente), os seguintes problemas devem ser considerados:
HTL
Componentes
cq:listener
que usa funções específicas da interface clássicacq:listener
código que usa funções específicas para a interface clássicaCaixas de diálogo
Se você estiver migrando um projeto projetado para a interface clássica, o código cq:listener
(e clientlibs relacionados a componentes) poderá usar funções específicas para a interface clássica (como CQ.wcm.*
). Para a migração, você deve atualizar esse código usando os objetos/funções equivalentes na interface habilitada para toque.
Se o seu projeto estiver sendo completamente migrado para a interface habilitada para toque, é necessário substituir esse código para usar os objetos e as funções relevantes para a interface habilitada para toque.
No entanto, se o projeto precisar atender tanto à interface clássica quanto à interface habilitada para toque durante o período de migração (o cenário normal), será necessário implementar uma opção para diferenciar o código separado que faz referência aos objetos apropriados.
Este mecanismo de comutação pode ser implementado como:
if (Granite.author) {
// touch UI
} else {
// classic UI
}
Como desenvolvedor, você quer acesso fácil à documentação do componente para que você possa entender rapidamente:
Por essa razão, é muito fácil disponibilizar qualquer marcação de documentação existente no próprio componente.
Tudo o que você precisa fazer é colocar um arquivo README.md
na estrutura do componente. Esta marcação será então exibida no console do componente.
A marcação suportada é a mesma para fragmentos de conteúdo.