Integrar o SPA developer-workflow

Entenda como o código-fonte de um aplicativo de página única (SPA) escrito no React pode ser integrado a um projeto do Adobe Experience Manager (AEM). Saiba como usar ferramentas de front-end modernas, como um servidor de desenvolvimento de webpack, para desenvolver rapidamente o SPA contra a API do modelo AEM JSON.

Objetivo

  1. Entenda como o projeto SPA é integrado ao AEM com bibliotecas do lado do cliente.
  2. Saiba como usar um servidor de desenvolvimento de webpack para desenvolvimento front-end dedicado.
  3. Explore o uso de um proxy e de um arquivo estático mock para desenvolvimento em relação à API do modelo AEM JSON.

O que você vai criar

Neste capítulo você fará várias pequenas alterações no SPA para entender como ele é integrado ao AEM.
Este capítulo adicionará um componente Header simples ao SPA. AEM No processo de construção deste componente estático Header, várias abordagens para o desenvolvimento do SPA são usadas.

Novo cabeçalho no AEM

O SPA foi estendido para adicionar um componente Header estático

Pré-requisitos

Revise as ferramentas e instruções necessárias para configurar um ambiente de desenvolvimento local. Este capítulo é uma continuação do capítulo Criar projeto. No entanto, basta seguir um projeto AEM habilitado para SPA em funcionamento.

Abordagem de integração integration-approach

Dois módulos foram criados como parte do projeto AEM: ui.apps e ui.frontend.

O módulo ui.frontend é um projeto webpack que contém todo o código fonte SPA. A maioria do desenvolvimento e teste do SPA é feita no projeto webpack. Quando um build de produção é acionado, o SPA é criado e compilado usando o webpack. Os artefatos compilados (CSS e Javascript) são copiados no módulo ui.apps que é então implantado no tempo de execução do AEM.

Arquitetura de alto nível ui.frontend

Uma descrição detalhada da integração com o SPA.

Informações adicionais sobre a compilação de front-end podem ser encontradas aqui.

Integração do Inspect ao SPA inspect-spa-integration

Em seguida, inspecione o módulo ui.frontend para entender o SPA que foi gerado automaticamente pelo arquétipo de projeto AEM.

  1. No IDE de sua escolha, abra o projeto AEM. Este tutorial usará o Visual Studio Code IDE.

    VSCode - Projeto AEM WKND SPA

  2. Expanda e inspecione a pasta ui.frontend. Abrir o arquivo ui.frontend/package.json

  3. Em dependencies você deve ver vários relacionados a react incluindo react-scripts

    O ui.frontend é um aplicativo React com base no Criar aplicativo React ou CRA para abreviar. A versão react-scripts indica qual versão do CRA é usada.

  4. Há também várias dependências com o prefixo @adobe:

    code language-json
    "@adobe/aem-react-editable-components": "~1.1.2",
    "@adobe/aem-spa-component-mapping": "~1.1.0",
    "@adobe/aem-spa-page-model-manager": "~1.3.3",
    "@adobe/aem-core-components-react-base": "1.1.8",
    "@adobe/aem-core-components-react-spa": "1.1.7",
    

    Os módulos acima compõem o SPA Editor JS SDK do AEM e fornecem a funcionalidade para possibilitar o mapeamento de componentes do SPA AEM para componentes do.

    Também estão incluídos Componentes WCM do AEM - Implementação do React Core e Componentes WCM do AEM - Editor de Spa - Implementação do React Core. Trata-se de um conjunto de componentes reutilizáveis da interface do usuário que mapeiam para componentes AEM prontos para uso. Elas foram projetadas para serem usadas como estão e estilizadas para atender às necessidades do seu projeto.

  5. No arquivo package.json há vários scripts definidos:

    code language-json
    "scripts": {
        "start": "react-scripts start",
        "build": "react-scripts build && clientlib",
        "test": "react-scripts test",
        "eject": "react-scripts eject",
    }
    

    Estes são os scripts de compilação padrão disponibilizados pela opção Criar Aplicativo React.

    A única diferença é a adição de && clientlib ao script build. Essa instrução extra é responsável por copiar o SPA compilado no módulo ui.apps como uma biblioteca do lado do cliente durante uma compilação.

    O módulo npm aem-clientlib-generator é usado para facilitar isso.

  6. Inspect o arquivo ui.frontend/clientlib.config.js. Este arquivo de configuração é usado por aem-clientlib-generator para determinar como gerar a biblioteca do cliente.

  7. Inspect o arquivo ui.frontend/pom.xml. Este arquivo transforma a pasta ui.frontend em um módulo Maven. O arquivo pom.xml foi atualizado para usar o SPA frontend-maven-plugin para testar e compilar durante uma compilação de Maven.

  8. Inspect o arquivo index.js em ui.frontend/src/index.js:

    code language-js
    //ui.frontend/src/index.js
    ...
    document.addEventListener('DOMContentLoaded', () => {
        ModelManager.initialize().then(pageModel => {
            const history = createBrowserHistory();
            render(
            <Router history={history}>
                <App
                history={history}
                cqChildren={pageModel[Constants.CHILDREN_PROP]}
                cqItems={pageModel[Constants.ITEMS_PROP]}
                cqItemsOrder={pageModel[Constants.ITEMS_ORDER_PROP]}
                cqPath={pageModel[Constants.PATH_PROP]}
                locationPathname={window.location.pathname}
                />
            </Router>,
            document.getElementById('spa-root')
            );
        });
    });
    

    index.js é o ponto de entrada do SPA. ModelManager é fornecido pelo SDK JS do Editor SPA AEM. Ele é responsável por chamar e injetar o pageModel (o conteúdo JSON) no aplicativo.

  9. Inspect o arquivo import-components.js em ui.frontend/src/components/import-components.js. Este arquivo importa os Componentes principais do React prontos para uso e os disponibiliza para o projeto. Vamos inspecionar o mapeamento do conteúdo de AEM para componentes de SPA no próximo capítulo.

Adição de um componente estático do SPA static-spa-component

Em seguida, adicione um novo componente ao SPA e implante as alterações em uma instância local do AEM. É uma mudança simples, apenas para ilustrar como o SPA é atualizado.

  1. No módulo ui.frontend, abaixo de ui.frontend/src/components, crie uma nova pasta chamada Header.

  2. Crie um arquivo chamado Header.js abaixo da pasta Header.

    Pasta e arquivo de cabeçalho

  3. Popular Header.js com o seguinte:

    code language-js
    //Header.js
    import React, {Component} from 'react';
    
    export default class Header extends Component {
    
        render() {
            return (
                    <header className="Header">
                        <div className="Header-container">
                            <h1>WKND</h1>
                        </div>
                    </header>
            );
        }
    }
    

    Acima está um componente React padrão que resultará em uma sequência de caracteres de texto estática.

  4. Abra o arquivo ui.frontend/src/App.js. Este é o ponto de entrada do aplicativo.

  5. Faça as seguintes atualizações em App.js para incluir o Header estático:

    code language-diff
      import { Page, withModel } from '@adobe/aem-react-editable-components';
      import React from 'react';
    + import Header from './components/Header/Header';
    
      // This component is the application entry point
      class App extends Page {
      render() {
          return (
          <div>
    +       <Header />
             {this.childComponents}
             {this.childPages}
         </div>
    
  6. Abra um novo terminal, navegue até a pasta ui.frontend e execute o comando npm run build:

    code language-shell
    $ cd aem-guides-wknd-spa
    $ cd ui.frontend
    $ npm run build
    ...
    Compiled successfully.
    
    File sizes after gzip:
    
    118.95 KB (-33 B)  build/static/js/2.489f399a.chunk.js
    1.11 KB (+48 B)    build/static/js/main.6cfa5095.chunk.js
    806 B              build/static/js/runtime-main.42b998df.js
    451 B              build/static/css/main.e57bbe8a.chunk.css
    
  7. Navegue até a pasta ui.apps. Abaixo de ui.apps/src/main/content/jcr_root/apps/wknd-spa-react/clientlibs/clientlib-react você deve ver que os arquivos SPA compilados foram copiados da pasta ui.frontend/build.

    Biblioteca do cliente gerada em ui.apps

  8. Retorne ao terminal e navegue até a pasta ui.apps. Execute o seguinte comando Maven:

    code language-shell
    $ cd ../ui.apps
    $ mvn clean install -PautoInstallPackage
    ...
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  9.629 s
    [INFO] Finished at: 2020-05-04T17:48:07-07:00
    [INFO] ------------------------------------------------------------------------
    

    Isso implantará o pacote ui.apps em uma instância de AEM local em execução.

  9. Abra uma guia do navegador e navegue até http://localhost:4502/editor.html/content/wknd-spa-react/us/en/home.html. Agora você deve ver o conteúdo do componente Header sendo exibido no SPA.

    Implementação de cabeçalho inicial

    As etapas acima são executadas automaticamente ao acionar uma compilação Maven da raiz do projeto (ou seja, mvn clean install -PautoInstallSinglePackage). Agora você deve entender as noções básicas da integração entre as bibliotecas do lado do cliente SPA e AEM. Observe que você ainda pode editar e adicionar Text componentes no AEM abaixo do componente estático Header.

Servidor de desenvolvimento do Webpack - Criar proxy para a API JSON proxy-json

Como visto nos exercícios anteriores, executar um build e sincronizar a biblioteca do cliente com uma instância local do AEM leva alguns minutos. Isso é aceitável para o teste final, mas não é ideal para a maioria do desenvolvimento de SPA.

Um webpack-dev-server pode ser usado para desenvolver rapidamente o SPA. O SPA é orientado por um modelo JSON gerado pelo AEM. Neste exercício, o conteúdo JSON de uma instância do AEM em execução é encaminhado por proxy para o servidor de desenvolvimento.

  1. Retorne ao IDE e abra o arquivo ui.frontend/package.json.

    Procure uma linha como a seguinte:

    code language-json
    "proxy": "http://localhost:4502",
    

    O Criar aplicativo React fornece um mecanismo fácil para solicitações de API de proxy. Todas as solicitações desconhecidas são encaminhadas por proxy através de localhost:4502, o quickstart AEM local.

  2. Abra uma janela de terminal e navegue até a pasta ui.frontend. Execute o comando npm start:

    code language-shell
    $ cd ui.frontend
    $ npm start
    ...
    Compiled successfully!
    
    You can now view wknd-spa-react in the browser.
    
    Local:            http://localhost:3000
    On Your Network:  http://192.168.86.136:3000
    
    Note that the development build is not optimized.
    To create a production build, use npm run build.
    
  3. Abra uma nova guia do navegador (se ainda não estiver aberta) e navegue até http://localhost:3000/content/wknd-spa-react/us/en/home.html.

    Servidor de desenvolvimento do Webpack - proxy json

    Você deve ver o mesmo conteúdo que no AEM, mas sem nenhum dos recursos de criação ativados.

    note note
    NOTE
    Devido aos requisitos de segurança do AEM, será necessário fazer logon na instância local do AEM (http://localhost:4502) no mesmo navegador, mas em uma guia diferente.
  4. Retorne ao IDE e crie um arquivo chamado Header.css na pasta src/components/Header.

  5. Preencha o Header.css com o seguinte:

    code language-css
    .Header {
        background-color: #FFEA00;
        width: 100%;
        position: fixed;
        top: 0;
        left: 0;
        z-index: 99;
        box-shadow: 0px 0px 10px 0px rgba(0, 0, 0, 0.24);
    }
    
    .Header-container {
        display: flex;
        max-width: 1024px;
        margin: 0 auto;
        padding: 12px;
    }
    
    .Header-container h1 {
        letter-spacing: 0;
        font-size: 48px;
    }
    

    IDE de VSCode

  6. Reabra Header.js e adicione a seguinte linha à referência Header.css:

    code language-diff
      //Header.js
      import React, {Component} from 'react';
    + require('./Header.css');
    

    Salve as alterações.

  7. Navegue até http://localhost:3000/content/wknd-spa-react/us/en/home.html para ver as alterações de estilo refletidas automaticamente.

  8. Abra o arquivo Page.css em ui.frontend/src/components/Page. Faça as seguintes alterações para corrigir o preenchimento:

    code language-css
    .page {
      max-width: 1024px;
      margin: 0 auto;
      padding: 12px;
      padding-top: 50px;
    }
    
  9. Retorne ao navegador em http://localhost:3000/content/wknd-spa-react/us/en/home.html. Você deve ver imediatamente as alterações no aplicativo refletidas.

    Estilo adicionado ao cabeçalho

    Você pode continuar a fazer atualizações de conteúdo no AEM e vê-las refletidas no webpack-dev-server, já que estamos usando o proxy para o conteúdo.

  10. Interrompa o servidor de desenvolvimento do webpack com ctrl+c no terminal.

Implantar atualizações do SPA no AEM

As alterações feitas no Header atualmente só são visíveis por meio do webpack-dev-server. Implante o AEM atualizado para SPA para ver as alterações.

  1. Navegue até a raiz do projeto (aem-guides-wknd-spa) e implante o projeto no AEM usando Maven:

    code language-shell
    $ cd ..
    $ mvn clean install -PautoInstallSinglePackage
    
  2. Navegue até http://localhost:4502/editor.html/content/wknd-spa-react/us/en/home.html. Você deve ver os Header e estilos atualizados aplicados.

    Cabeçalho atualizado no AEM

    Agora que o SPA atualizado está no AEM, a criação pode continuar.

Parabéns. congratulations

Parabéns, você atualizou o SPA e explorou a integração com o AEM! Agora você sabe como desenvolver o SPA contra a API do modelo AEM JSON usando um webpack-dev-server.

Próximas etapas next-steps

Mapear componentes do SPA para componentes do AEM - Saiba como mapear componentes do React para componentes do Adobe Experience Manager AEM AEM SPA () com o SDK JS do editor de. O mapeamento de componentes permite que os usuários façam atualizações dinâmicas nos componentes do SPA no editor SPA AEM, de forma semelhante à criação tradicional do AEM.

(Bônus) Servidor de desenvolvimento Webpack - API JSON simulada mock-json

Outra abordagem para o desenvolvimento rápido é usar um arquivo JSON estático para agir como o modelo JSON. Ao "zombar" do JSON, removemos a dependência em uma instância local do AEM. Ele também permite que um desenvolvedor de front-end atualize o modelo JSON para testar a funcionalidade e direcionar alterações na API JSON, que seria implementada posteriormente por um desenvolvedor de back-end.

A configuração inicial do modelo JSON requer uma instância AEM local.

  1. Retorne ao IDE, navegue até ui.frontend/public e adicione uma nova pasta chamada mock-content.

  2. Crie um novo arquivo com o nome mock.model.json debaixo de ui.frontend/public/mock-content.

  3. No navegador, navegue até http://localhost:4502/content/wknd-spa-react/us/en.model.json.

    Este é o JSON exportado pelo AEM que está direcionando o aplicativo. Copie a saída JSON.

  4. Cole a saída JSON da etapa anterior no arquivo mock.model.json.

    Arquivo Json de Modelo Fictício

  5. Abra o arquivo index.html em ui.frontend/public/index.html. Atualize a propriedade de metadados do modelo de página AEM para apontar para uma variável %REACT_APP_PAGE_MODEL_PATH%:

    code language-html
        <!-- AEM page model -->
        <meta
           property="cq:pagemodel_root_url"
           content="%REACT_APP_PAGE_MODEL_PATH%"
        />
    

    Usar uma variável para o valor de cq:pagemodel_root_url facilitará a alternância entre o modelo proxy e o modelo json fictício.

  6. Abra o arquivo ui.frontend/.env.development e faça as seguintes atualizações para comentar o valor anterior de REACT_APP_PAGE_MODEL_PATH e REACT_APP_API_HOST:

    code language-diff
    + PUBLIC_URL=/
    - PUBLIC_URL=/etc.clientlibs/wknd-spa-react/clientlibs/clientlib-react/resources
    
    - REACT_APP_PAGE_MODEL_PATH=/content/wknd-spa-react/us/en.model.json
    + REACT_APP_PAGE_MODEL_PATH=/mock-content/mock.model.json
    
    - REACT_APP_API_HOST=http://localhost:4502
    + #REACT_APP_API_HOST=http://localhost:4502
    
    REACT_APP_ROOT=/content/wknd-spa-react/us/en/home.html
    
  7. Se estiver em execução, pare o webpack-dev-server. Inicie o webpack-dev-server do terminal:

    code language-shell
    $ cd ui.frontend
    $ npm start
    

    Navegue até http://localhost:3000/content/wknd-spa-react/us/en/home.html e você deverá ver o SPA com o mesmo conteúdo usado no json proxy.

  8. Faça uma pequena alteração no arquivo mock.model.json criado anteriormente. Você deve ver o conteúdo atualizado imediatamente refletido no webpack-dev-server.

    atualização de json do modelo fictício

Ser capaz de manipular o modelo JSON e ver os efeitos em um SPA ao vivo pode ajudar um desenvolvedor a entender a API do modelo JSON. Também permite que o desenvolvimento de front-end e back-end ocorra em paralelo.

Agora é possível alternar onde consumir o conteúdo JSON, alternando as entradas no arquivo env.development:

# JSON API via proxy to AEM
#REACT_APP_PAGE_MODEL_PATH=/content/wknd-spa-react/us/en.model.json
#REACT_APP_API_HOST=http://localhost:4502

# JSON API via static mock file
REACT_APP_PAGE_MODEL_PATH=/mock-content/mock.model.json
recommendation-more-help
e25b6834-e87f-4ff3-ba56-4cd16cdfdec4