SPA Blueprint

Para permitir que o autor use o AEM SPA Editor para editar o conteúdo de um SPA, há requisitos que o SPA deve atender, descritos neste documento.

Introdução

Este documento descreve o contrato geral que qualquer estrutura SPA deve cumprir (isto é, o tipo de camada de suporte AEM) para implementar componentes SPA editáveis dentro do AEM.

Para permitir que o autor use o Editor de páginas AEM para editar os dados expostos por uma estrutura de aplicativo de página única, um projeto deve ser capaz de interpretar a estrutura do modelo que representa a semântica dos dados armazenados para um aplicativo no repositório AEM. Para atingir esse objetivo, são fornecidas duas bibliotecas agnósticas de estrutura: as PageModelManager e ComponentMapping.

PageModelManager

A biblioteca PageModelManager é fornecida como um pacote NPM a ser usado por um projeto SPA. Acompanha o SPA e atua como um gerenciador de modelo de dados.

Em nome do SPA, abstrai a recuperação e o gerenciamento da estrutura JSON que representa a estrutura de conteúdo real. Também é responsável por sincronizar com o SPA para informá-lo quando ele precisa renderizar novamente seus componentes.

Consulte o pacote NPM @adobe/aem-spa-page-model-manager

Ao inicializar o PageModelManager, a biblioteca primeiro carrega o modelo raiz fornecido do aplicativo (por parâmetro, propriedade meta ou URL atual). Se a biblioteca identificar que o modelo da página atual não faz parte do modelo raiz, ele o busca e o inclui como o modelo de uma página secundária.

ComponentMapping

O módulo ComponentMapping é fornecido como um pacote NPM para o projeto front-end. Ele armazena componentes de front-end e fornece uma maneira para o SPA mapear componentes de front-end para AEM tipos de recursos. Isso permite uma resolução dinâmica de componentes ao analisar o modelo JSON do aplicativo.

Cada item presente no modelo contém um campo :type que expõe um tipo de recurso AEM. Quando montado, o componente front-end pode se renderizar usando o fragmento do modelo recebido das bibliotecas subjacentes.

Modelo dinâmico para mapeamento de componentes

Para obter detalhes sobre como o modelo dinâmico para mapeamento de componentes ocorre no Javascript SPA SDK para AEM, consulte o artigo Modelo dinâmico para mapeamento de componentes para SPA.

Camada específica da estrutura

Deve ser implementada uma terceira camada para cada estrutura de front-end. Esta terceira biblioteca é responsável por interagir com as bibliotecas subjacentes e fornece uma série de pontos de entrada bem integrados e fáceis de usar para interagir com o modelo de dados.

O restante deste documento descreve os requisitos desta camada específica do quadro intermediário e aspira a ser independente da estrutura. Respeitando os requisitos a seguir, pode ser fornecida uma camada específica para a estrutura, para que os componentes do projeto interajam com as bibliotecas subjacentes responsáveis pelo gerenciamento do modelo de dados.

Conceitos gerais

Modelo de página

A estrutura de conteúdo da página é armazenada em AEM. O modelo da página é usado para mapear e instanciar componentes SPA. Os desenvolvedores SPA criam componentes SPA que mapeiam para AEM componentes. Para fazer isso, eles usam o tipo de recurso (ou caminho para o componente AEM) como uma chave exclusiva.

Os componentes SPA devem estar em sincronia com o modelo de página e ser atualizados com quaisquer alterações em seu conteúdo de acordo. Um padrão que potencialize componentes dinâmicos deve ser usado para instanciar componentes dinamicamente após a estrutura do modelo de página fornecida.

Campos de meta

O modelo de página aproveita o Exportador de Modelo JSON, que se baseia na API Sling Model. Os modelos de sling exportáveis expõem a seguinte lista de campos para permitir que as bibliotecas subjacentes interpretem o modelo de dados:

• :type: Tipo do recurso AEM (padrão = tipo de recurso)

• :children: Filhos hierárquicos do recurso atual. Os filhos não fazem parte do conteúdo interno do recurso atual (pode ser encontrado em itens que representam uma página)

• :hierarchyType: Tipo hierárquico de um recurso. O PageModelManager suporta atualmente o tipo de página

• :items: Recursos de conteúdo filho do recurso atual (estrutura aninhada, presente apenas em container)

• :itemsOrder: Lista ordenada das crianças. O objeto de mapa JSON não garante a ordem de seus campos. Com o mapa e o array atual, o consumidor da API tem os benefícios de ambas as estruturas

• :path: Caminho do conteúdo de um item (presente em itens que representam uma página)

Consulte também Introdução ao AEM Content Services.

Módulo Específico da Estrutura

A separação de preocupações ajuda a facilitar a implementação do projeto. Por conseguinte, deve ser fornecido um pacote específico para as npm. Este pacote é responsável por agregar e expor os módulos, serviços e componentes básicos. Esses componentes devem encapsular a lógica de gerenciamento do modelo de dados e fornecer acesso aos dados que o componente do projeto espera. O módulo também é responsável por expor transitoriamente pontos de entrada úteis das bibliotecas subjacentes.

Para facilitar a interoperabilidade das bibliotecas, o Adobe aconselha o módulo específico da estrutura a agrupar as seguintes bibliotecas. Se necessário, a camada pode encapsular e adaptar as APIs subjacentes antes de expô-las ao projeto.

• @adobe/aem-spa-page-model-manager
• @adobe/aem-spa-component-mapping

Implementações

Reagir

módulo npm: @adobe/aem-response-editable-components

Angular

módulo npm: em breve

Principais serviços e componentes

As seguintes entidades devem ser implementadas em conformidade com as orientações específicas de cada quadro. Com base na arquitetura-quadro, a implementação pode variar bastante, mas as funcionalidades descritas devem ser fornecidas.

O Provedor de Modelo

Os componentes do projeto devem delegar acesso aos fragmentos de um modelo a um Provedor de modelos. O Provedor de modelos é responsável por acompanhar as alterações feitas no fragmento especificado do modelo e retornar o modelo atualizado ao componente de delegação.

Para fazer isso, o Provedor de modelos deve se registrar no PageModelManager. Em seguida, quando uma alteração ocorre, ele recebe e transmite os dados atualizados para o componente de delegação. Por convenção, a propriedade disponibilizada para o componente de delegação que carregará o fragmento do modelo é chamada cqModel. A implementação é gratuita para fornecer essa propriedade ao componente, mas deve considerar aspectos como a integração com a arquitetura da estrutura, a descoberta e a facilidade de uso.

O Decorador HTML do Componente

O Decorador de componentes é responsável por decorar o HTML externo do elemento de cada instância de componente com uma série de atributos de dados e nomes de classe esperados pelo Editor de páginas.

Declaração de componente

Os metadados a seguir devem ser adicionados ao elemento HTML externo produzido pelo componente do projeto. Eles permitem que o Editor de páginas recupere a configuração de edição correspondente.

• data-cq-data-path: Caminho para o recurso relativo ao jcr:content

Editando Declaração de Recurso e Marcador de Posição

Os metadados e nomes de classe a seguir devem ser adicionados ao elemento HTML externo produzido pelo componente do projeto. Eles permitem que o Editor de páginas oferta funcionalidades relacionadas.

• cq-placeholder: Nome da classe que identifica o espaço reservado para um componente vazio
• data-emptytext: Rótulo a ser exibido pela sobreposição quando uma instância do componente estiver vazia

Espaço reservado para componentes vazios

Cada componente deve ser estendido com uma funcionalidade que decorará o elemento HTML externo com atributos de dados e nomes de classe específicos para espaços reservados e sobreposições relacionadas quando o componente for identificado como vazio.

Sobre o vazio de um componente

• O componente está logicamente vazio?
• Qual deve ser o rótulo exibido pela sobreposição quando o componente está vazio?

Container

Um container é um componente destinado a conter e renderizar componentes filhos. Para fazer isso, o container repete as propriedades :itemsOrder, :items e :children do modelo.

O container obtém dinamicamente os componentes filho da loja da biblioteca ComponentMapping. O container estende o componente filho com os recursos do Provedor de modelos e, por fim, instanciá-lo.

Página

O componente Page estende o componente Container. Um container é um componente destinado a conter e renderizar componentes filhos, incluindo páginas secundárias. Para fazer isso, o container repete as propriedades :itemsOrder, :items e :children do modelo. O componente Page obtém dinamicamente os componentes secundários da loja da biblioteca ComponentMapping. O Page é responsável pela instanciação de componentes secundários.

Grade responsiva

O componente Grade responsiva é um container. Ele contém uma variante específica do Provedor de modelos que representa suas colunas. A Grade responsiva e suas colunas são responsáveis por decorar o elemento HTML externo do componente do projeto com os nomes de classe específicos contidos no modelo.

O componente de Grade responsiva deve vir pré-mapeado para sua AEM contrapartida, pois esse componente é complexo e raramente personalizado.

Campos de Modelo Específicos

• gridClassNames: Nomes de classe fornecidos para a grade responsiva
• columnClassNames: Nomes de classe fornecidos para a coluna responsiva

Consulte também o recurso npm @adobe/aem-response-editable-components#srccomponentsresponsivegridjsx

Espaço reservado da grade responsiva

O componente SPA é mapeado para um container gráfico, como a Grade responsiva, e deve adicionar um espaço reservado para filho virtual quando o conteúdo está sendo criado. Quando o conteúdo do SPA está sendo criado pelo Editor de páginas, esse conteúdo é incorporado ao editor usando um iframe e o atributo data-cq-editor é adicionado ao nó do documento desse conteúdo. Quando o atributo data-cq-editor estiver presente, o container deverá incluir um HTMLElement para representar a área com a qual o autor interage ao inserir um novo componente na página.

Por exemplo:

<div data-cq-data-path={"path/to/the/responsivegrid/*"} className="new section aem-Grid-newComponent"/>

Mapeamento de componentes

A biblioteca subjacente Component Mapping e sua função MapTo podem ser encapsuladas e estendidas para fornecer as funcionalidades relativas à configuração de edição fornecida ao lado da classe de componente atual.

const EditConfig = {
 
    emptyLabel: 'My Component',
 
    isEmpty: function() {
        return !this.props || !this.props.cqModel || this.props.cqModel.isEmpty;
    }
};
 
class MyComponent extends Component {
 
    render() {
        return <div className={'my-component'}></div>;
    }
}
 
MapTo('component/resource/path')(MyComponent, EditConfig);

Na implementação acima, o componente do projeto é estendido com a funcionalidade vazia antes de ser realmente registrado na loja Mapeamento de componentes. Isso é feito encapsulando e estendendo a biblioteca ComponentMapping para introduzir o suporte do objeto de configuração EditConfig:

/**
 * Configuration object in charge of providing the necessary data expected by the page editor to initiate the authoring. The provided data will be decorating the associated component
 *
 * @typedef {{}} EditConfig
 * @property {String} [dragDropName]       If defined, adds a specific class name enabling the drag and drop functionality
 * @property {String} emptyLabel           Label to be displayed by the placeholder when the component is empty. Optionally returns an empty text value
 * @property {function} isEmpty            Should the component be considered empty. The function is called using the context of the wrapper component giving you access to the component model
 */
 
/**
 * Map a React component with the given resource types. If an {@link EditConfig} is provided the <i>clazz</i> is wrapped to provide edition capabilities on the AEM Page Editor
 *
 * @param {string[]} resourceTypes                      - List of resource types for which to use the given <i>clazz</i>
 * @param {class} clazz                                 - Class to be instantiated for the given resource types
 * @param {EditConfig} [editConfig]                     - Configuration object for enabling the edition capabilities
 * @returns {class}                                     - The resulting decorated Class
 */
ComponentMapping.map = function map (resourceTypes, clazz, editConfig) {};

Contrato com o editor de página

Os componentes do projeto devem gerar no mínimo os seguintes atributos de dados para permitir que o editor interaja com eles.

• data-cq-data-path: Caminho relativo do componente conforme fornecido pelo PageModel (por exemplo, "root/responsivegrid/image"). Este atributo não deve ser adicionado às páginas.

Em resumo, para ser interpretado pelo editor de página como editável, um componente de projeto deve respeitar o seguinte contrato:

• Forneça os atributos esperados para associar uma instância de componente front-end a um recurso AEM.
• Forneça a série esperada de atributos e nomes de classe que permitem a criação de espaços reservados vazios.
• Forneça os nomes de classe esperados, permitindo a ação de arrastar e soltar ativos.

Estrutura típica do elemento HTML

O fragmento a seguir ilustra a representação HTML típica de uma estrutura de conteúdo de página. Estes são alguns pontos importantes:

• O elemento de grade responsivo carrega nomes de classe com prefixo aem-Grid--
• O elemento de coluna responsiva carrega nomes de classe com prefixo aem-GridColumn--
• Uma grade responsiva que também é a coluna de uma grade pai está encapsulada, como os dois prefixos anteriores não aparecem no mesmo elemento
• Os elementos correspondentes a recursos editáveis possuem uma propriedade data-cq-data-path. Consulte a seção Contrato com o Editor de páginas deste documento.

<div data-cq-data-path="/content/page?lang=pt-BR">
    <div class="aem-Grid aem-Grid--12 aem-Grid--default--12">
        <div class="aem-container aem-GridColumn aem-GridColumn--default--12" data-cq-data-path="/content/page/jcr:content/root/responsivegrid?lang=pt-BR">
            <div class="aem-Grid aem-Grid--12 aem-Grid--default--12">
                <div class="cmp-image cq-dd-image aem-GridColumn aem-GridColumn--default--12" data-cq-data-path="/root/responsivegrid/image?lang=pt-BR">
                    <img src="/content/we-retail-spa-sample/react/jcr%3acontent/root/responsivegrid/image.img.jpeg/1512113734019.jpeg?lang=pt-BR">
                </div>
            </div>
        </div>
    </div>
</div>

Navegação e Roteamento

O aplicativo é o proprietário do roteamento. Primeiro, o desenvolvedor front-end precisa implementar um componente de Navegação (mapeado para um componente de navegação AEM). Esse componente renderizaria links de URL a serem usados em conjunto com uma série de rotas que exibirão ou ocultarão fragmentos de conteúdo.

A biblioteca subjacente PageModelManager e seu módulo ModelRouter (ativado por padrão) são responsáveis pela busca prévia e pelo acesso ao modelo associado a um determinado caminho de recurso.

As duas entidades se relacionam à noção de roteamento, mas ModelRouter é responsável apenas por ter `PageModelManager carregado com um modelo de dados estruturado em sincronia com o estado atual do aplicativo.

Consulte o artigo SPA Model Roteamento para obter mais informações.

SPA na Ação

Veja como um SPA simples funciona e experimente com um SPA você mesmo continuando com o documento Introdução ao SPA em AEM.

Leitura adicional

Para obter mais informações sobre SPA em AEM, consulte os seguintes documentos:

• SPA Visão geral de criação para obter uma visão geral do SPA em AEM e do modelo de comunicação

• Introdução ao SPA no AEMpara obter um guia sobre um SPA simples e como ele funciona