Desenvolvimento de componentes AEM (Interface clássica)

A interface clássica usa o ExtJS para criar widgets que fornecem a aparência dos componentes. Devido à natureza desses widgets, há algumas diferenças entre a forma como os componentes interagem com a interface clássica e a interface habilitada para toque.

Estrutura

A estrutura básica de um componente é abordada na página AEM Componentes - Informações básicas, que aplica as interfaces de toque e clássica. Mesmo se você não precisar usar as configurações para a interface habilitada para toque em seu novo componente, pode ajudar a conhecê-las ao herdar dos componentes existentes.

Scripts JSP

Scripts ou Servlets JSP podem ser usados para renderizar componentes. De acordo com as regras de processamento de solicitação de Sling, o nome do script padrão é:

<*componentname*>.jsp

global.jsp

O arquivo de script JSP global.jsp é usado para fornecer acesso rápido a objetos específicos (isto é, para acessar conteúdo) a qualquer arquivo de script JSP usado para renderizar um componente.

Portanto, global.jsp deve ser incluído em cada script JSP de renderização de componente onde um ou mais dos objetos fornecidos em global.jsp são usados.

O local padrão global.jsp é:

/libs/foundation/global.jsp

Função de global.jsp, APIs usadas e Taglibs

A seguir, são listas os objetos mais importantes fornecidos pelo padrão global.jsp:

Resumo:

• <cq:defineObjects />

  • slingRequest - O objeto de solicitação encapsulado ( SlingHttpServletRequest).
  • slingResponse - O objeto de resposta encapsulado ( SlingHttpServletResponse).
  • resource - O Objeto De Recurso Sling ( slingRequest.getResource();).
  • resourceResolver - O Objeto Sling Resource Resolver ( slingRequest.getResoucreResolver();).
  • currentNode - O nó JCR resolvido para a solicitação.
  • log - O registrador padrão ().
  • sling - O auxiliar de script Sling.
  • properties - As propriedades do recurso endereçado ( resource.adaptTo(ValueMap.class);).
  • pageProperties - As propriedades da página do recurso endereçado.
  • pageManager - O gerenciador de páginas para acessar AEM páginas de conteúdo ( resourceResolver.adaptTo(PageManager.class);).
  • component - O objeto componente do componente AEM atual.
  • designer - O objeto designer para recuperar informações de design ( resourceResolver.adaptTo(Designer.class);).
  • currentDesign - A concepção do recurso endereçado.
  • currentStyle - O estilo do recurso endereçado.

Acessar conteúdo

Existem três métodos para acessar o conteúdo AEM WCM:

• Pelo objeto properties introduzido em global.jsp:

  O objeto properties é uma instância de um ValueMap (consulte Sling API) e contém todas as propriedades do recurso atual.

  Exemplo: String pageTitle = properties.get("jcr:title", "no title"); usado no script de renderização de um componente de página.

  Exemplo: String paragraphTitle = properties.get("jcr:title", "no title"); usado no script de renderização de um componente de parágrafo padrão.

• Pelo objeto currentPage introduzido em global.jsp:

  O objeto currentPage é uma instância de uma página (consulte AEM API). A classe page fornece alguns métodos para acessar o conteúdo.

  Exemplo: String pageTitle = currentPage.getTitle();

• Via currentNode objeto introduzido em global.jsp:

  O objeto currentNode é uma instância de um nó (consulte API JCR). As propriedades de um nó podem ser acessadas pelo método getProperty().

  Exemplo: String pageTitle = currentNode.getProperty("jcr:title");

Bibliotecas de tags JSP

As bibliotecas de tags CQ e Sling fornecem acesso a funções específicas para uso no script JSP dos seus modelos e componentes.

Para obter mais informações, consulte o documento Bibliotecas de tags.

Usando bibliotecas HTML do lado do cliente

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.

Consulte o documento Usando bibliotecas HTML do lado do cliente para obter mais informações.

Caixa de diálogo

Seu componente precisará de uma caixa de diálogo para que os autores adicionem e configurem o conteúdo.

Consulte AEM Componentes - Informações básicas para obter mais detalhes.

Configuração do comportamento de edição

Você pode 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 às interfaces de usuário habilitadas 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.

Uso e extensão de widgets ExtJS

Consulte Usar e estender widgets ExtJS para obter mais detalhes.

Uso de xtypes para widgets ExtJS

Consulte Usando xtypes para obter mais detalhes.

Desenvolvimento de novos componentes

Esta seção descreve como criar seus próprios componentes e adicioná-los ao sistema de parágrafo.

Uma maneira rápida de começar é copiar um componente existente e fazer as alterações desejadas.

Um exemplo de como desenvolver um componente é descrito detalhadamente em Extensão do Componente de Texto e Imagem - Um Exemplo.

Desenvolver um novo componente (Adaptar componente existente)

Para desenvolver novos componentes para AEM com base no componente existente, você pode copiar o componente, criar um arquivo javascript para o novo componente e armazená-lo em um local acessível para AEM (consulte também Personalizando componentes e outros elementos):

1. Usando o CRXDE Lite, crie uma nova pasta de componentes em:

   / apps/<myProject>/components/<myComponent>

   Recrie a estrutura do nó como em libs e copie a definição de um componente existente, como o componente de Texto. Por exemplo, para personalizar a cópia do componente de Texto:

   • de /libs/foundation/components/text
   • para /apps/myProject/components/text

2. Modifique jcr:title para refletir seu novo nome.

3. Abra a nova pasta de componentes e faça as alterações necessárias. Além disso, exclua quaisquer informações estranhas na pasta.

   É possível fazer alterações como:

   • adição de um novo campo na caixa de diálogo

     • cq:dialog - caixa de diálogo para a interface habilitada para toque
     • dialog - caixa de diálogo para a interface clássica

   • substituição do arquivo .jsp (nomeie-o após seu novo componente)

   • ou retrabalhar completamente o componente inteiro se desejar

   Por exemplo, se você pegar uma cópia do componente Texto padrão, poderá adicionar um campo adicional à caixa de diálogo e, em seguida, atualizar o .jsp para processar a entrada feita lá.

   OBSERVAÇÃO

   Um componente para:

   • A interface habilitada para toque usa componentes Granite
   • A interface clássica usa widgets ExtJS
   OBSERVAÇÃO

   Uma caixa de diálogo definida para a interface clássica funcionará dentro da interface habilitada para toque.

   Uma caixa de diálogo definida para a interface habilitada para toque não funcionará na interface clássica.

   Dependendo da instância e do ambiente do autor, talvez você queira definir ambos os tipos de diálogo para o seu componente.

4. Um dos nós a seguir deve estar presente e ser inicializado corretamente para que o novo componente seja exibido:

   • cq:dialog - caixa de diálogo para a interface habilitada para toque
   • dialog - caixa de diálogo para a interface clássica
   • cq:editConfig - como os componentes se comportam no ambiente de edição (por exemplo, arrastar e soltar)
   • design_dialog - caixa de diálogo para o modo de design (somente interface clássica)

5. Ative o novo componente no sistema de parágrafo:

   • usando a CRXDE Lite para adicionar o valor <path-to-component> (por exemplo, /apps/geometrixx/components/myComponent) aos componentes de propriedade do nó /etc/designs/geometrixx/jcr:content/contentpage/par
   • seguindo as instruções em Adicionar novos componentes aos sistemas de parágrafo

6. Em AEM WCM, abra uma página no site e insira um novo parágrafo do tipo que você acabou de criar para garantir que o componente esteja funcionando corretamente.

Adicionar um novo componente ao Sistema de parágrafo (Modo de design)

Depois que o componente for desenvolvido, você o adicionará ao sistema de parágrafo, que permite que os autores selecionem e usem o componente ao editar uma página.

1. Acesse uma página no ambiente de criação que usa o sistema de parágrafo, por exemplo <contentPath>/Test.html.

2. Alterne para o modo Design:

   • adicionar ?wcmmode=design ao final do URL e acessar novamente, por exemplo:

     <contextPath>/ Test.html?wcmmode=design

   • clicando em Design no Sidekick

   Agora você está no modo de design e pode editar o sistema de parágrafo.

3. Clique em Editar.

   Uma lista de componentes pertencentes ao sistema de parágrafo é mostrada. Seu novo componente também está listado.

   Os componentes podem ser ativados (ou desativados) para determinar quais são oferecidos ao autor ao editar uma página.

4. Ative seu componente e retorne ao modo de edição normal para confirmar que ele está disponível para uso.

Extensão do componente de texto e imagem - um exemplo

Esta seção fornece um exemplo de como estender o texto amplamente usado e o componente padrão de imagem com um recurso de posicionamento de imagem configurável.

A extensão para o componente de texto e imagem permite que os editores usem toda a funcionalidade existente do componente, além de ter uma opção extra para especificar o posicionamento da imagem:

• No lado esquerdo do texto (comportamento atual e o novo padrão)
• Assim como no lado direito

Após estender esse componente, é possível configurar o posicionamento da imagem por meio da caixa de diálogo do componente.

As seguintes técnicas são descritas neste exercício:

• Copiar o nó do componente existente e modificar seus metadados
• Modificação da caixa de diálogo do componente, incluindo herança de widgets de caixas de diálogo pai
• Modificação do script do componente para implementar a nova funcionalidade

Extensão do componente de tempo de textura existente

Para criar o novo componente, usamos o componente de textura padrão como base e o modificamos. Armazenamos o novo componente no aplicativo de exemplo AEM WCM do Geometrixx.

1. Copie o componente de mensagem de texto padrão de /libs/foundation/components/textimage para a pasta do componente do Geometrixx, /apps/geometrixx/components, usando a mensagem de tempo como o nome do nó do público alvo. (Copie o componente navegando até o componente, clicando com o botão direito do mouse e selecionando Copiar e navegando até o diretório do público alvo.)

   

2. Para manter esse exemplo simples, navegue até o componente que você copiou e exclua todos os subnós do novo nó de tempo de textura, exceto os seguintes:

   • definição da caixa de diálogo: textimage/dialog
   • script de componente: textimage/textimage.jsp
   • editar nó de configuração (permitindo arrastar e soltar ativos): textimage/cq:editConfig
   OBSERVAÇÃO

   A definição da caixa de diálogo depende da interface do usuário:

   • Interface habilitada para toque: textimage/cq:dialog
   • Interface clássica: textimage/dialog

3. Edite os metadados do componente:

   • Nome do componente

     • Defina jcr:description como Text Image Component (Extended)
     • Defina jcr:title como Text Image (Extended)

   • Grupo, onde o componente está listado no sidekick (deixe como está)

     • Deixe componentGroup definido como General

   • Componente pai do novo componente (o componente de tempo de textura padrão)

     • Defina sling:resourceSuperType como foundation/components/textimage

   Após esta etapa, o nó do componente terá a seguinte aparência:

   

4. Altere a propriedade sling:resourceType do nó de configuração de edição da imagem (propriedade: textimage/cq:editConfig/cq:dropTargets/image/parameters/sling:resourceType) para geometrixx/components/textimage.

   Dessa forma, quando uma imagem é solta no componente na página, a propriedade sling:resourceType do componente de tempo de textura estendida é definida como: geometrixx/components/textimage.

5. Modifique a caixa de diálogo do componente para incluir a nova opção. O novo componente herda as partes da caixa de diálogo que são as mesmas do original. A única adição que fazemos é estender a guia Avançado, adicionando uma lista suspensa Posição da imagem, com as opções Esquerda e Direita:

   • Deixe as propriedades textimage/dialoginalteradas.

   Observe como textimage/dialog/items tem quatro subnós, tab1 a tab4, representando as quatro guias da caixa de diálogo de tempo de texto.

   • Para as duas primeiras guias (guia1 e guia2):

     • Altere xtype para cqinclude (para herdar do componente padrão).
     • Adicione uma propriedade path com valores /libs/foundation/components/textimage/dialog/items/tab1.infinity.jsone /libs/foundation/components/textimage/dialog/items/tab2.infinity.json, respectivamente.
     • Remova todas as outras propriedades ou subnós.

   • Para a guia3:

     • Deixe as propriedades e os subnós sem alterações

     • Adicionar uma nova definição de campo a tab3/items, posição do nó do tipo cq:Widget

     • Defina as seguintes propriedades (do tipo String) para o novo nó tab3/items/position:

       • name: ./imagePosition
       • xtype: selection
       • fieldLabel: Image Position
       • type: select

     • Adicione o subnó position/options do tipo cq:WidgetCollection para representar as duas opções de posicionamento de imagem e, sob ele, crie dois nós, o1 e o2 do tipo nt:unstructured.

     • Para o nó position/options/o1 defina as propriedades: text para Left e value para left.

     • Para o nó position/options/o2 defina as propriedades: text para Right e value para right.

   • Excluir guia4.

   A posição da imagem é persistente no conteúdo como a propriedade imagePositiondo nó que representa o parágrafo textimage. Após essas etapas, a caixa de diálogo do componente terá a seguinte aparência:

   

6. Amplie o script de componente, textimage.jsp, com a manipulação extra do novo parâmetro:

   Image image = new Image(resource, "image");
   
   if (image.hasContent() || WCMMode.fromRequest(request) == WCMMode.EDIT) {
        image.loadStyleData(currentStyle);
   

   Vamos substituir o fragmento de código enfatizado %><div class="image"><% por um novo código que gera um estilo personalizado para essa tag.

   // todo: add new CSS class for the 'right image' instead of using 
   // the style attribute 
   String style="";
        if (properties.get("imagePosition", "left").equals("right")) { 
             style = "style=\"float:right\""; 
        } 
        %><div <%= style %> class="image"><%
   

7. Salve o componente no repositório. O componente está pronto para teste.

Verificando o novo componente

Depois que o componente for desenvolvido, você poderá adicioná-lo ao sistema de parágrafo, que permite que os autores selecionem e usem o componente ao editar uma página. Essas etapas permitem testar o componente.

1. Abra uma página em Geometrixx, como inglês / Empresa.
2. Alterne para o modo de design clicando em Design no Sidekick.
3. Edite o design do sistema de parágrafo clicando em Editar no sistema de parágrafo no meio da página. Uma lista de componentes, que pode ser colocada no sistema de parágrafo, é mostrada e deve incluir seu componente recém-desenvolvido, Imagem de texto (estendida). Ative-o para o sistema de parágrafo selecionando-o e clicando em OK.
4. Volte para o modo de edição.
5. Adicione o parágrafo Imagem de texto (estendida) ao sistema de parágrafo, inicialize o texto e a imagem com conteúdo de amostra. Salve as alterações.
6. Abra a caixa de diálogo do texto e do parágrafo da imagem, altere a Posição da imagem na guia Avançado para Direita e clique em OK para salvar as alterações.
7. O parágrafo é renderizado com a imagem à direita.
8. O componente agora está pronto para uso.

O componente armazena seu conteúdo em um parágrafo na página Empresa.

Desativar a capacidade de carregamento do componente de imagem

Para desativar esse recurso, usamos o componente de imagem padrão como base e o modificamos. Armazenamos o novo componente no aplicativo de exemplo de Geometrixx.

1. Copie o componente de imagem padrão de /libs/foundation/components/image para a pasta do componente do Geometrixx, /apps/geometrixx/components, usando a imagem como o nome do nó do público alvo.

   

2. Edite os metadados do componente:

   • Defina jcr:title como Image (Extended)

3. Vá até /apps/geometrixx/components/image/dialog/items/image.

4. Adicionar uma nova propriedade:

   • Nome: allowUpload
   • Tipo: String
   • Valor: false

   

5. Clique em Salvar tudo. O componente está pronto para teste.

6. Abra uma página em Geometrixx, como inglês / Empresa.

7. Alterne para o modo de design e ative Imagem (estendida).

8. Volte para o modo de edição e adicione-o ao sistema de parágrafo. Nas próximas imagens, você pode ver as diferenças entre o componente de imagem original e aquele que você acabou de criar.

   Componente de imagem original:

   

   Seu novo componente de imagem:

   

9. O componente agora está pronto para uso.