Personalizar os Componentes principais

Os Componentes principais implementam vários padrões que permitem a fácil personalização, desde o estilo simples até a reutilização de funcionalidade avançada.

Arquitetura flexível

Os Componentes principais foram projetados desde o início para serem flexíveis e extensíveis. Uma visão geral de sua arquitetura revela onde as personalizações podem ser feitas.

Arquitetura dos componentes principais

  • A caixa de diálogo de design define o que os autores podem ou não fazer na caixa de diálogo de edição.
  • A caixa de diálogo de edição mostra aos autores apenas as opções que eles têm permissão para usar.
  • O modelo do Sling verifica e prepara o conteúdo para a exibição (modelo).
  • O resultado do modelo Sling pode ser serializado para JSON para casos de uso SPA.
  • O HTL renderiza o lado do servidor HTML para renderização tradicional do lado do servidor.
  • O HTML gera semântica, acessível, mecanismo de pesquisa otimizado e de fácil estilo.

E todos os componentes principais implementam o Sistema de estilos.

Arquétipo de projeto do AEM

O Arquétipo de projeto AEM cria um projeto Adobe Experience Manager mínimo como ponto de partida para seus próprios projetos, incluindo um exemplo de componente HTL personalizado com SlingModels para a lógica e a implementação adequada dos Componentes principais com o padrão de proxy recomendado.

Padrões de personalização

Personalizar caixas de diálogo

Talvez seja desejável personalizar as opções de configuração disponíveis em uma caixa de diálogo de componente principal, seja na Caixa de diálogo Design ou na caixa de diálogo Editar.

Cada caixa de diálogo tem uma estrutura de nó consistente. Recomenda-se que esta estrutura seja replicada em um componente herdado para que Sling Resource Merger e Ocultar Condições possam ser usadas para ocultar, substituir ou reordenar seções da caixa de diálogo original. A estrutura a ser replicada é definida como qualquer coisa até o nível do nó do item de guia.

Para ser totalmente compatível com qualquer alteração feita em uma caixa de diálogo na versão atual, é muito importante que as estruturas abaixo do nível do item de guia não sejam tocadas (ocultas, adicionadas, substituídas, reordenadas, etc.). Em vez disso, um item de guia do pai deve ser oculto por meio da propriedade sling:hideResource (consulte Propriedades de Fusão de Recursos de Sling) e novos itens de guia adicionados que contêm os campos de configuração do bespoke. sling:orderBefore pode ser usada para reordenar os itens da guia, se necessário.

A caixa de diálogo abaixo demonstra a estrutura de diálogo recomendada, bem como ocultar e substituir uma guia herdada, conforme descrito acima:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0"
          xmlns:jcr="https://www.jcp.org/jcr/1.0"
          xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
          xmlns:granite="https://www.adobe.com/jcr/granite/1.0"
          jcr:primaryType="nt:unstructured">
    <content jcr:primaryType="nt:unstructured">
        <items jcr:primaryType="nt:unstructured">
            <tabs jcr:primaryType="nt:unstructured">
                <items jcr:primaryType="nt:unstructured">
                        <originalTab
                                jcr:primaryType="nt:unstructured"
                                sling:hideResource="true"/>
                        </originalTab>
                        <myTab
                               jcr:primaryType="nt:unstructured"
                               jcr:title="My Tab"
                               sling:resourceType="granite/ui/components/coral/foundation/container"/>
                               <!-- myTab content -->
                        </myTab>
                </items>
            </basic>
        </items>
    </content>
</jcr:root>

Personalização da lógica de um componente principal

A lógica de negócios dos componentes principais é implementada nos Modelos do Sling. Essa lógica pode ser estendida usando um padrão de delegação do Sling.

Por exemplo, o componente principal do título usa a propriedade jcr:title do recurso solicitado para fornecer o texto do título. Se nenhuma propriedade jcr:title for definida, um fallback para o título da página atual será implementado. Queremos alterar o comportamento para que o título da página atual seja sempre exibido.

Como a implementação dos modelos dos Componentes principais é privada, eles devem ser estendidos com um padrão de delegação.

@Model(adaptables = SlingHttpServletRequest.class,
       adapters = Title.class,
       resourceType = "myproject/components/pageHeadline")
public class PageHeadline implements Title {
    @ScriptVariable private Page currentPage;
    @Self @Via(type = ResourceSuperType.class)
    private Title title;
    @Override public String getText() {
        return currentPage.getTitle();
    }
    @Override public String getType() {
        return title.getType();
    }
}

Para obter mais detalhes sobre o padrão de delegação, consulte o artigo Wiki do GitHub dos Componentes principais Padrão de delegação para modelos do Sling.

Personalização da marcação

Às vezes, o estilo avançado requer uma estrutura de marcação diferente do componente.

Isso pode ser feito facilmente copiando os arquivos HTL que precisam ser modificados do Componente principal no componente proxy .

Levando novamente o exemplo do Componente de navegação estrutural principal, para personalizar sua saída de marcação, o arquivo breadcrumb.html teria que ser copiado para o componente específico do site que tem um sling:resourceSuperTypes que aponta para o Componente de navegação estrutural principal.

Alterar estilo dos componentes

A primeira forma de personalização é aplicar estilos de CSS.

Para facilitar isso, os Componentes principais renderizam a marcação semântica e seguem uma convenção de nomenclatura padronizada inspirada pelo Bootstrap. Além disso, para direcionar e namespace facilmente os estilos dos componentes individuais, cada Componente principal é embutido em um elemento DIV com as classes " cmp" e " cmp-<name>".

Por exemplo, olhando para o arquivo HTL do Componente de navegação estrutural principal v1: breadcrumb.html, vemos que a saída da hierarquia de elementos é ol.breadcrumb > li.breadcrumb-item > a. Portanto, para garantir que uma regra CSS afete apenas a classe de navegação estrutural desse componente, todas as regras devem ser nomeadas conforme mostrado abaixo:

.cmp-breadcrumb .breadcrumb {}  
.cmp-breadcrumb .breadcrumb-item {}  
.cmp-breadcrumb a {}

Além disso, cada um dos Componentes principais aproveita o AEM recurso do Sistema de estilos que permite que os autores do modelo definam nomes de classe CSS adicionais que podem ser aplicados ao componente pelos autores da página. Isso permite definir para cada modelo uma lista de estilos de componente permitidos e se um deles deve ser aplicado por padrão a todos os componentes desse tipo.

Atualização da compatibilidade de personalizações

São possíveis três tipos diferentes de atualizações:

  • atualização da versão do AEM
  • atualização dos Componentes principais para uma nova versão secundária
  • atualização dos Componentes principais para uma versão principal

Geralmente, atualizar AEM para uma nova versão não afetará os Componentes principais ou as personalizações feitas, desde que as versões dos componentes também sejam compatíveis com a nova versão de AEM para a qual está sendo migrada e que as personalizações não usem APIs que foram obsoletas ou removidas.

Atualizar os Componentes principais sem alternar para uma versão principal mais recente não deve afetar as personalizações, desde que os padrões de personalização descritos nesta página sejam usados.

A alternância para uma versão principal mais recente dos Componentes principais é compatível somente com a estrutura de conteúdo, mas as personalizações podem precisar ser refatoradas. Os registros de alterações claros serão publicados para cada versão do componente para destacar as alterações que afetariam o tipo de personalizações descritas nesta página.

Suporte a personalizações

Como para qualquer componente de AEM, há várias coisas que devem ser levadas em conta em relação às personalizações:

  1. Nunca modifique o código dos Componentes principais diretamente.

    Isso os tornaria totalmente incompatíveis e tornaria atualizações futuras dos componentes um processo doloroso. Em vez disso, use os métodos de personalização descritos nesta página.

  2. O código personalizado é de sua própria responsabilidade.

    Nosso programa de suporte não abrange o código personalizado e os problemas relatados que não podem ser reproduzidos com os Componentes principais baunilha usados conforme documentado não serão qualificados.

  3. Assista à funcionalidade obsoleta e removida.

    Com cada nova versão do AEM sendo atualizada para , verifique se todas as APIs usadas ainda são atuais, mantendo um olho na página Recursos obsoletos e removidos.

Consulte também a seção Suporte a componentes principais .

Leia a seguir:

Nesta página