Desenvolvimento de componentes do AEM developing-aem-components
Os componentes do AEM são usados para reter, formatar e renderizar o conteúdo disponibilizado em suas páginas da Web.
-
Quando criação de páginas, os componentes permitem que os autores editem e configurem o conteúdo.
-
Ao construir um Commerce site, os componentes podem, por exemplo, coletar e renderizar informações do catálogo.
Consulte Desenvolvimento do comércio eletrônico para obter mais informações. -
Ao construir um Communities site, os componentes podem fornecer informações e coletar informações de seus visitantes.
Consulte Comunidades de desenvolvimento 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.
/libs/cq/gui/components/authoring/dialog
devem ser usados somente no Editor (caixas de diálogo de componentes na Criação). Se forem usados em outro lugar (como em uma caixa de diálogo de assistente, por exemplo), talvez eles não se comportem conforme esperado.Amostras de código code-samples
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 do AEM - Amostras de código para obter alguns exemplos práticos.
Estrutura structure
A estrutura básica de um componente é abordada na página Componentes do AEM - Noções básicas. Esse documento abrange as interfaces habilitadas para toque e as interfaces clássicas. Mesmo que você não precise usar as configurações clássicas no novo componente, pode ser útil estar ciente delas ao herdar de componentes existentes.
Extensão de componentes e caixas de diálogo existentes extending-existing-components-and-dialogs
Dependendo do componente que você deseja implementar, talvez seja possível estender ou personalizar uma instância existente, em vez de definir e desenvolver a instância inteira estrutura do zero.
Ao estender ou personalizar um componente ou caixa de diálogo existente, você pode copiar ou replicar toda a estrutura ou a estrutura necessária para a caixa de diálogo antes de fazer as alterações.
Extensão de um componente existente extending-an-existing-component
A extensão de um componente existente pode ser obtida com Hierarquia de tipo de recurso e os mecanismos de herança relacionados.
/apps
deve definir toda a sobreposição.Personalização de uma caixa de diálogo Componente existente customizing-a-existing-component-dialog
Também é possível substituir um caixa de diálogo componente usando o Fusão de recursos do Sling e definição da 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
). Este método agora é recomendado para estender uma caixa de diálogo de componente
Consulte a Fusão de recursos do Sling para obter mais detalhes.
Definição da marcação defining-the-markup
Seu componente será renderizado com HTML. Seu componente precisa definir o HTML necessário para obter o conteúdo necessário e, em seguida, renderizá-lo conforme necessário nos ambientes do autor e de publicação.
Uso da Linguagem de modelo do HTML using-the-html-template-language
A variável Linguagem de modelo HTML (HTL), introduzido com o AEM 6.0, substitui o JSP (JavaServer Pages) como o sistema de modelo preferencial e recomendado do lado do servidor para o 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.
Desenvolvimento da lógica do conteúdo developing-the-content-logic
Essa lógica opcional seleciona e/ou calcula o conteúdo a ser renderizado. É chamado a partir de 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 é necessário para uma determinada visualização. Também permite lógicas diferentes para visualizações diferentes do mesmo recurso.
Uso do Java using-java
A API de uso Java do HTL permite que um arquivo HTL acesse métodos de ajuda 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.
Utilização do JavaScript using-javascript
A API de uso do JavaScript do HTL permite que um arquivo HTL acesse o código de ajuda gravado 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.
Uso de bibliotecas de HTML do lado do cliente using-client-side-html-libraries
Sites modernos dependem muito do processamento do lado do cliente orientado por códigos JavaScript e CSS complexos. Organizar e otimizar a veiculação desse código pode ser um problema complicado.
Para ajudar a lidar com esse problema, o AEM fornece Pastas de biblioteca do lado cliente, que permitem armazenar o código do lado do cliente no repositório, organizá-lo em categorias e definir quando e como cada categoria de código deve ser entregue ao cliente. O sistema de biblioteca do lado do cliente cuida de produzir os links corretos na página final da Web para carregar o código correto.
Ler Uso de bibliotecas de HTML do lado do cliente para obter mais informações.
Configuração do comportamento de edição configuring-the-edit-behavior
É possível 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 à interface clássica, embora com determinadas diferenças específicas.
A variável editar comportamento de um componente está configurado adicionando 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 filhos.
Configuração do comportamento de visualização configuring-the-preview-behavior
A variável Modo WCM o cookie é definido ao alternar para Visualizar mesmo quando a página não é atualizada.
Para componentes com uma renderização sensível ao Modo WCM, eles precisam ser definidos para se atualizarem especificamente e, em seguida, confiar no valor do cookie.
EDIT
e PREVIEW
são usados para o Modo WCM cookie.Criando e configurando uma caixa de diálogo creating-and-configuring-a-dialog
As caixas de diálogo são usadas para permitir que o autor interaja com o componente. Usar uma caixa de diálogo permite que autores e/ou administradores editem conteúdo, configurem o componente ou definam parâmetros de design (usando um Caixa de diálogo Design)
Interface do usuário do Coral e do Granite coral-ui-and-granite-ui
Coral UI e Interface do Granite definir a aparência moderna do AEM.
A interface do usuário do Granite fornece uma grande variedade de componentes básicos (widgets) necessário para criar sua caixa de diálogo no ambiente de criação. Quando necessário, é possível estender essa seleção e criar seu próprio widget.
Para obter detalhes completos, consulte:
-
Coral UI
- Fornece uma interface consistente em todas as soluções em nuvem
- Conceitos da interface habilitada para toque por AEM - interface do Coral
- Guia da interface de usuário do Coral
-
Interface do Granite
- Fornece marcação da interface Coral encapsulada em componentes Sling para construir consoles e caixas de diálogo da interface
- Conceitos da interface habilitada para toque por AEM - Interface do usuário do Granite
- Documentação da interface de usuário do Granite
Criando uma nova caixa de diálogo creating-a-new-dialog
Caixas de diálogo para a interface habilitada para toque:
-
são nomeados
cq:dialog
. -
são definidos como um
nt:unstructured
com o nósling:resourceType
conjunto de propriedades. -
estão localizados sob sua
cq:Component
e ao lado da definição do componente. -
são renderizados no lado do servidor (como componentes do Sling), com base em sua estrutura de conteúdo e na
sling:resourceType
propriedade. -
usar a estrutura da interface de usuário do Granite.
-
contém uma estrutura de nó que descreve os campos na caixa de diálogo.
- esses nós são
nt:unstructured
com o necessáriosling:resourceType
propriedade.
- esses nós são
Um exemplo de estrutura de nó 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, pois a caixa de diálogo é, em si, um componente (ou seja, uma marcação renderizada por um script de componente juntamente com o comportamento/estilo fornecido por uma biblioteca do cliente).
Para obter exemplos, consulte:
/libs/foundation/components/text/cq:dialog
/libs/foundation/components/download/cq:dialog
Personalizar campos de diálogo customizing-dialog-fields
- a sessão AEM Gems em Personalizar campos de diálogo.
- o código de amostra relacionado abrangido pelo Amostra de código - Como personalizar campos de diálogo.
Criação de um novo campo creating-a-new-field
Os dispositivos para a interface habilitada para toque são implementados como componentes de interface do Granite.
Para criar um widget para usar em uma caixa de diálogo de componente para a interface habilitada para toque, é necessário criar um componente de campo da interface de usuário do Granite.
Se você considerar sua caixa de diálogo como um contêiner simples para um elemento de formulário, também poderá ver o conteúdo principal do seu conteúdo da caixa de diálogo como campos de formulário. A criação de um campo de formulário requer a criação de um tipo de recurso; é equivalente à criação de um componente. Para ajudá-lo nessa tarefa, a interface do usuário do Granite oferece um componente de campo genérico do qual herdar (usando sling:resourceSuperType
):
/libs/granite/ui/components/coral/foundation/form/field
Mais especificamente, o Granite UI fornece uma variedade de componentes de campo adequados para uso em diálogos (ou, de forma mais geral, em formulários).
cq:Widgets
nós, cada um com um determinado xtype
para estabelecer a relação com o widget ExtJS correspondente. Do ponto de vista da implementação, esses widgets foram renderizados no lado do cliente pela estrutura ExtJS.Depois de criar o tipo de recurso, é possível instanciar o campo adicionando um novo nó na caixa de diálogo, com a propriedade sling:resourceType
referindo-se ao tipo de recurso que acabou de introduzir.
Criação de uma biblioteca do cliente para estilo e comportamento creating-a-client-library-for-style-and-behavior
Se quiser definir o estilo e o comportamento do componente, você poderá criar um biblioteca do cliente que define seus CSS/LESS e JS personalizados.
Para carregar a biblioteca do cliente exclusivamente para a caixa de diálogo do componente (ou seja, ela não será carregada para outro componente), é necessário definir a propriedade extraClientlibs
da caixa de diálogo para o nome da categoria da biblioteca do cliente que você criou. Isso é aconselhável se a biblioteca do cliente for muito grande e/ou se o campo for específico para essa caixa de diálogo e não for necessário em outras caixas de diálogo.
Para carregar a biblioteca do cliente para todas as caixas de diálogo, defina a propriedade category da biblioteca do cliente como cq.authoring.dialog
. Esse é o nome da categoria da biblioteca do cliente que é incluído 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
- fornecido pelo Amostra de código
Estender (herdar de) um campo extending-inheriting-from-a-field
Dependendo das suas necessidades, você pode:
- Estender um determinado campo da interface do usuário do Granite por herança de componente (
sling:resourceSuperType
) - Estender um determinado widget da biblioteca de widgets subjacente (se houver uma interface de usuário do Granite, essa é a Coral UI), seguindo a API da biblioteca de widgets (herança JS/CSS)
Acesso aos campos da caixa de diálogo access-to-dialog-fields
Também é possível usar as 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"]
Manipulação de eventos de campo handling-field-events
O método de manipulação de eventos em campos de diálogo agora é feito com ouvintes em uma biblioteca de cliente personalizada. Essa é uma alteração do método mais antigo de ter ouvintes na estrutura de conteúdo.
Ouvintes em uma biblioteca de cliente personalizada listeners-in-a-custom-client-library
Para inserir lógica no campo, você deve:
- Marque o campo com uma determinada classe CSS (a variável gancho).
- Defina, na biblioteca do cliente, um ouvinte JS conectado a esse nome de classe CSS (isso garante que a lógica personalizada tenha escopo somente para o campo e não afete outros campos do mesmo tipo).
Para fazer isso, você precisa saber sobre a biblioteca de widgets subjacente com a qual deseja interagir. Consulte a Documentação da interface do Coral para identificar a qual evento você deseja reagir. Isso é muito semelhante ao processo que você teve que executar com ExtJS no passado: localize a página de documentação de um determinado widget e, em seguida, verifique os detalhes da API de evento.
Para ver um exemplo, consulte:
-
cqgems/customizingfield/components/clientlibs/customizingfield
- fornecido pelo Amostra de código
Ouvintes na estrutura de conteúdo listeners-in-the-content-structure
Na interface clássica com ExtJS, era comum ter ouvintes de um determinado widget na estrutura do conteúdo. Fazer o mesmo na interface habilitada para toque é diferente, pois o código de ouvinte JS (ou qualquer código) não é mais definido no conteúdo.
A estrutura de conteúdo descreve a estrutura semântica; ela não deve (deve) implicar a natureza do widget subjacente. Ao não ter o código JS na estrutura do conteúdo, é possível alterar os detalhes da implementação sem precisar alterar a estrutura do conteúdo. Em outras palavras, você pode alterar a biblioteca de widgets sem precisar tocar na estrutura de conteúdo.
Detectando Disponibilidade da Caixa de Diálogo dialog-ready
Se você tiver um JavaScript personalizado que precisa ser executado somente quando a caixa de diálogo estiver disponível e pronta, você deve ouvir o dialog-ready
evento.
Esse evento é acionado sempre que a caixa de diálogo é carregada (ou recarregada) e está pronta para uso, o que significa que sempre que há uma alteração (criar/atualizar) no DOM da caixa de diálogo.
dialog-ready
O pode ser usado para conectar o código personalizado JavaScript que executa personalizações nos campos dentro de uma caixa de diálogo ou tarefas semelhantes.
Validação de campo field-validation
Campo obrigatório mandatory-field
Para marcar um determinado campo como obrigatório, defina a seguinte propriedade no nó de conteúdo do campo:
- Nome:
required
- Tipo:
Boolean
Para ver um exemplo, consulte:
/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title
Validação de campo (interface do usuário do Granite) field-validation-granite-ui
A validação de campo na interface do usuário do Granite e nos componentes da interface do usuário do Granite (equivalente a widgets) é feita usando foundation-validation
API. Consulte a foundation-valdiation
Documentação do Granite para obter detalhes.
Para obter exemplos, consulte:
-
cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js
- fornecido pelo Amostra de código
-
/libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js
Criando e configurando uma caixa de diálogo de design creating-and-configuring-a-design-dialog
A caixa de diálogo Design é fornecida quando um componente tem detalhes de design que podem ser editados no Modo Design.
A definição é muito semelhante à de um caixa de diálogo usada para editar conteúdo, com a diferença de que é definido como um nó:
- Nome do nó:
cq:design_dialog
- Tipo:
nt:unstructured
Criação e configuração de um editor local creating-and-configuring-an-inplace-editor
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 Texto e Título padrão 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 de local para obter mais informações.
Personalização da barra de ferramentas do componente customizing-the-component-toolbar
A variável Component Toolbar fornece ao usuário acesso a uma variedade de ações para o componente, como editar, configurar, copiar e excluir.
Consulte Extensão de criação de página - Adicionar nova ação a uma barra de ferramentas do componente para obter mais informações.
Configurar um componente para o painel de referências (emprestado/concedido) configuring-a-component-for-the-references-rail-borrowed-lent
Se o novo componente fizer referência ao conteúdo de outras páginas, você poderá considerar se deseja que ele afete a Conteúdo Emprestado e Conteúdo concedido seções do Referências Ferroviário.
O AEM pronto para uso 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 entrada na definição, especificando seu componente, juntamente com a propriedade a ser verificada. Por exemplo:
/apps/<*your-Project*>/components/reference@parentPath
Ativação e adição do componente ao sistema de parágrafos enabling-and-adding-your-component-to-the-paragraph-system
Depois que o componente tiver sido desenvolvido, ele precisará ser ativado para uso em um sistema de parágrafo apropriado, para que possa ser usado nas páginas necessárias.
Isso pode ser feito:
- usar Modo de design ao editar uma página específica.
- definição do
components
propriedade no sistema de parágrafo de um modelo.
Configurar um sistema de parágrafo para que arrastar um ativo crie uma instância de componente configuring-a-paragraph-system-so-that-dragging-an-asset-creates-a-component-instance
O AEM oferece a possibilidade de configurar um sistema de parágrafos em sua página para que uma instância do novo componente é criada automaticamente 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).
Esse comportamento e a relação necessária entre ativo e componente podem ser configurados:
-
Na definição de parágrafo do design da página. Por exemplo:
/etc/designs/<myApp>/page/par
Criar um nó:
- Nome:
cq:authoring
- Tipo:
nt:unstructured
-
Em, crie um nó para manter todos os mapeamentos de ativo para componente:
- Nome:
assetToComponentMapping
- Tipo:
nt:unstructured
- Nome:
-
Para cada mapeamento de ativo para componente, crie um nó:
- Nome: texto; recomenda-se que o nome indique o ativo e o tipo de componente relacionado; por exemplo, imagem
- Tipo:
nt:unstructured
Cada um com as seguintes propriedades:
-
assetGroup
:- Tipo:
String
- Valor: o grupo ao qual o ativo relacionado pertence; por exemplo,
media
- Tipo:
-
assetMimetype
:- Tipo:
String
- Valor: o tipo MIME do ativo relacionado; por exemplo,
image/*
- Tipo:
-
droptarget
:- Tipo:
String
- Valor: o alvo de liberação; por exemplo,
image
- Tipo:
-
resourceType
:- Tipo:
String
- Valor: o recurso componente relacionado; por exemplo,
foundation/components/image
- Tipo:
-
type
:- Tipo:
String
- Valor: o tipo, por exemplo,
Images
- Tipo:
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
- Abrir projeto aem-project-archetype no GitHub
- Baixar o projeto como um arquivo ZIP
Uso da extensão AEM Brackets using-the-aem-brackets-extension
A variável Extensão de Colchetes AEM O fornece um fluxo de trabalho suave para editar componentes do AEM e bibliotecas de clientes. Baseia-se no Colchetes editor de código.
A extensão:
- Facilita a sincronização (sem a necessidade de Maven ou File Vault) para ajudar a aumentar a eficiência do desenvolvedor e também ajuda desenvolvedores de front-end com conhecimento limitado em AEM a participar de projetos.
- Fornece alguns HTL suporte, a linguagem de modelo criada para simplificar o desenvolvimento de componentes e aumentar a segurança.
Migração de um componente clássico migrating-from-a-classic-component
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 (exclusiva ou conjuntamente), os seguintes problemas devem ser considerados:
-
HTL
- Uso do HTL não é obrigatório, mas se o componente precisar ser atualizado, é o momento ideal para considerar migração de JSP para HTL.
-
Componentes
- Migrar
cq:listener
código que usa funções específicas da interface clássica - Plug-in RTE. Para obter mais informações, consulte Configuração do editor de rich text.
- Migrar
cq:listener
código que usa funções específicas para a interface clássica
- Migrar
-
Caixas de diálogo
- Crie uma caixa de diálogo para usar na interface habilitada para toque. No entanto, 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.
- A variável Ferramentas de modernização do AEM são fornecidos para ajudar a estender os componentes existentes.
- Mapeamento de ExtJS para componentes de interface do usuário do Granite O fornece uma visão geral conveniente dos tipos xtypes ExtJS e tipos de nós com seus tipos de recursos equivalentes da interface do usuário do Granite.
- Personalização de campos, para obter mais informações, consulte a sessão Gems do AEM em Personalizar campos de diálogo.
- Migrar de vtypes para Validação da interface do usuário do Granite
- Usando ouvintes JS, para obter mais informações, consulte Manipulação de eventos de campo e a sessão AEM Gems em Personalizar campos de diálogo.
Migrando o código cq:listener migrating-cq-listener-code
Se você estiver migrando um projeto criado para a interface clássica, a variável cq:listener
o código (e clientlibs relacionadas ao componente) pode 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 projeto estiver sendo completamente migrado para a interface habilitada para toque, será necessário substituir esse código para usar os objetos e funções relevantes para a interface habilitada para toque.
No entanto, se o seu projeto precisar atender à interface clássica e à interface habilitada para toque durante o período de migração (o cenário normal), você deverá implementar uma opção para diferenciar o código separado que faz referência aos objetos apropriados.
Esse mecanismo de switch pode ser implementado como:
if (Granite.author) {
// touch UI
} else {
// classic UI
}
Documentação do componente documenting-your-component
Como desenvolvedor, você deseja obter acesso fácil à documentação de componentes para compreender rapidamente:
- Descrição
- Uso previsto
- Estrutura de conteúdo e propriedades
- APIs e pontos de extensão expostos
- E assim por diante
Por isso, é fácil criar qualquer marcação de documentação existente disponível no próprio componente.
Colocar um README.md
na estrutura do componente. Essa marcação é exibida no campo console do componente.
A marcação compatível é a mesma para fragmentos de conteúdo.