Integrare l’SPA developer-workflow

Comprendere come il codice sorgente di un’applicazione a pagina singola (SPA) scritto in React può essere integrato con un progetto Adobe Experience Manager (AEM). Scopri come utilizzare strumenti front-end moderni, come un server di sviluppo Webpack, per sviluppare rapidamente l’SPA contro l’API modello JSON dell’AEM.

Obiettivo

  1. Comprendere come il progetto SPA viene integrato con l’AEM con le librerie lato client.
  2. Scopri come utilizzare un server di sviluppo Webpack per lo sviluppo front-end dedicato.
  3. Esplora l'utilizzo di un file proxy e di un file fittizio statico per lo sviluppo in base all'API del modello JSON AEM.

Cosa verrà creato

In questo capitolo verranno apportate diverse piccole modifiche all’SPA per comprendere come questo viene integrato con l’AEM.
Questo capitolo aggiungerà un semplice componente Header all'SPA. Nel processo di compilazione di questo componente static Header vengono utilizzati diversi approcci allo sviluppo dell'SPA AEM.

Nuova intestazione in AEM

L'SPA è stato esteso per aggiungere un componente Header statico

Prerequisiti

Esaminare gli strumenti e le istruzioni necessari per configurare un ambiente di sviluppo locale. Questo capitolo è una continuazione del capitolo Crea progetto, ma seguire tutto ciò che ti serve è un progetto AEM funzionante abilitato per SPA.

Approccio all’integrazione integration-approach

Nel progetto AEM sono stati creati due moduli: ui.apps e ui.frontend.

Il modulo ui.frontend è un progetto webpack che contiene tutto il codice sorgente SPA. La maggior parte dello sviluppo e dei test dell’SPA viene effettuata nel progetto webpack. Quando viene attivata una build di produzione, l’SPA viene generato e compilato utilizzando Webpack. Gli artefatti compilati (CSS e JavaScript) vengono copiati nel modulo ui.apps che viene quindi distribuito nel runtime AEM.

architettura di alto livello ui.frontend

Rappresentazione di alto livello dell'integrazione SPA.

Ulteriori informazioni sulla build front-end sono disponibili qui.

Integrazione di Inspect con l’SPA inspect-spa-integration

Esaminare quindi il modulo ui.frontend per comprendere l'SPA generato automaticamente dall'archetipo progetto AEM.

  1. Nell’IDE che preferisci, apri il Progetto AEM. Questa esercitazione utilizzerà l'IDE codice di Visual Studio.

    VSCode - Progetto SPA WKND AEM

  2. Espandere ed esaminare la cartella ui.frontend. Apri il file ui.frontend/package.json

  3. Sotto dependencies dovresti vedere diversi relativi a react incluso react-scripts

    ui.frontend è un'applicazione React basata su Crea app React o CRA in breve. La versione react-scripts indica quale versione di CRA viene utilizzata.

  4. Ci sono anche diverse dipendenze con il prefisso @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",
    

    I moduli di cui sopra costituiscono l'SDK JS per l'editor SPA dell'AEM e forniscono la funzionalità che consente di mappare i componenti SPA ai componenti AEM.

    Sono inclusi anche Componenti WCM AEM - Implementazione React Core e Componenti WCM AEM - Editor SPA - Implementazione React Core. Si tratta di un set di componenti riutilizzabili dell’interfaccia utente mappati su componenti AEM predefiniti. Sono progettati per essere utilizzati così come sono e progettati per soddisfare le esigenze del progetto.

  5. Nel file package.json sono definiti diversi scripts:

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

    Si tratta di script di build standard resi disponibili dalla funzione Crea app React.

    L'unica differenza consiste nell'aggiunta di && clientlib allo script build. Questa istruzione aggiuntiva è responsabile della copia dell'SPA compilato nel modulo ui.apps come libreria lato client durante una compilazione.

    Per facilitare questa operazione, viene utilizzato il modulo npm aem-clientlib-generator.

  6. Inspect il file ui.frontend/clientlib.config.js. Questo file di configurazione viene utilizzato da aem-clientlib-generator per determinare come generare la libreria client.

  7. Inspect il file ui.frontend/pom.xml. Questo file trasforma la cartella ui.frontend in un modulo Maven. Il file pom.xml è stato aggiornato per utilizzare frontend-maven-plugin per test e build l'SPA durante una build Maven.

  8. Inspect il file index.js in 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 è il punto di ingresso dell'SPA. ModelManager è fornito dall'SDK JS dell'editor SPA dell'AEM. È responsabile della chiamata e dell'inserimento di pageModel (contenuto JSON) nell'applicazione.

  9. Inspect il file import-components.js in ui.frontend/src/components/import-components.js. Questo file importa i Componenti core React predefiniti e li rende disponibili per il progetto. Nel prossimo capitolo verrà esaminata la mappatura dei contenuti AEM sui componenti SPA.

Aggiungere un componente SPA statico static-spa-component

Quindi, aggiungi un nuovo componente all’SPA e implementa le modifiche in un’istanza AEM locale. Questo è un semplice cambiamento, giusto per illustrare come l'SPA viene aggiornato.

  1. Nel modulo ui.frontend, sotto ui.frontend/src/components, creare una nuova cartella denominata Header.

  2. Creare un file denominato Header.js sotto la cartella Header.

    Cartella intestazione e file

  3. Popolare Header.js con quanto segue:

    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>
            );
        }
    }
    

    Il precedente è un componente React standard che genererà una stringa di testo statica.

  4. Aprire il file ui.frontend/src/App.js. Questo è il punto di ingresso dell'applicazione.

  5. Effettuare i seguenti aggiornamenti a App.js per includere Header statico:

    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. Aprire un nuovo terminale, passare alla cartella ui.frontend ed eseguire il 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. Passare alla cartella ui.apps. Sotto ui.apps/src/main/content/jcr_root/apps/wknd-spa-react/clientlibs/clientlib-react dovresti vedere che i file SPA compilati sono stati copiati dalla cartella ui.frontend/build.

    Libreria client generata in ui.apps

  8. Tornare al terminale e spostarsi nella cartella ui.apps. Esegui il seguente 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] ------------------------------------------------------------------------
    

    Il pacchetto ui.apps verrà distribuito a un'istanza in esecuzione locale di AEM.

  9. Apri una scheda del browser e passa a http://localhost:4502/editor.html/content/wknd-spa-react/us/en/home.html. Il contenuto del componente Header dovrebbe essere visualizzato nell'SPA.

    Implementazione intestazione iniziale

    I passaggi precedenti vengono eseguiti automaticamente quando si attiva una build Maven dalla radice del progetto (ovvero mvn clean install -PautoInstallSinglePackage). Ora dovresti comprendere le basi dell’integrazione tra l’SPA e le librerie lato client dell’AEM. È comunque possibile modificare e aggiungere Text componenti in AEM sotto il componente Header statico.

Server di sviluppo Webpack: proxy dell’API JSON proxy-json

Come visto negli esercizi precedenti, l’esecuzione di una build e la sincronizzazione della libreria client con un’istanza locale dell’AEM richiedono alcuni minuti. Questo è accettabile per i test finali, ma non è ideale per la maggior parte dello sviluppo dell'SPA.

È possibile utilizzare un webpack-dev-server per sviluppare rapidamente l'SPA. L’SPA è guidato da un modello JSON generato dall’AEM. In questo esercizio il contenuto JSON di un'istanza in esecuzione di AEM è inviato al server di sviluppo.

  1. Tornare all'IDE e aprire il file ui.frontend/package.json.

    Cerca una riga simile alla seguente:

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

    Crea app React fornisce un semplice meccanismo per inoltrare le richieste API. Tutte le richieste sconosciute vengono elaborate tramite proxy localhost:4502, l'avvio rapido dell'AEM locale.

  2. Aprire una finestra del terminale e passare alla cartella ui.frontend. Eseguire il 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. Apri una nuova scheda del browser (se non è già aperta) e passa a http://localhost:3000/content/wknd-spa-react/us/en/home.html.

    Server di sviluppo Webpack - proxy json

    Dovresti visualizzare gli stessi contenuti dell’AEM, ma senza le funzionalità di authoring abilitate.

    note note
    NOTE
    A causa dei requisiti di sicurezza dell’AEM, dovrai aver effettuato l’accesso all’istanza AEM locale (http://localhost:4502) nello stesso browser ma in una scheda diversa.
  4. Tornare all'IDE e creare un file denominato Header.css nella cartella src/components/Header.

  5. Popolare Header.css con quanto segue:

    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 VSCode

  6. Riapri Header.js e aggiungi la seguente riga al riferimento Header.css:

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

    Salva le modifiche.

  7. Passa a http://localhost:3000/content/wknd-spa-react/us/en/home.html per vedere le modifiche di stile riflesse automaticamente.

  8. Aprire il file Page.css in ui.frontend/src/components/Page. Apporta le seguenti modifiche per correggere la spaziatura:

    code language-css
    .page {
      max-width: 1024px;
      margin: 0 auto;
      padding: 12px;
      padding-top: 50px;
    }
    
  9. Torna al browser in http://localhost:3000/content/wknd-spa-react/us/en/home.html. Dovresti vedere immediatamente le modifiche apportate all’app.

    Stile aggiunto allintestazione

    Puoi continuare a eseguire aggiornamenti dei contenuti in AEM e vederli riflessi in webpack-dev-server, dal momento che stiamo eseguendo il proxy del contenuto.

  10. Arrestare il server di sviluppo Webpack con ctrl+c nel terminale.

Distribuire gli aggiornamenti SPA all’AEM

Le modifiche apportate a Header sono attualmente visibili solo tramite webpack-dev-server. Distribuire l’SPA aggiornato nell’AEM per visualizzare le modifiche.

  1. Passare alla radice del progetto (aem-guides-wknd-spa) e distribuire il progetto in AEM utilizzando Maven:

    code language-shell
    $ cd ..
    $ mvn clean install -PautoInstallSinglePackage
    
  2. Passa a http://localhost:4502/editor.html/content/wknd-spa-react/us/en/home.html. Dovresti vedere Header aggiornato e gli stili applicati.

    Intestazione aggiornata in AEM

    Ora che l’SPA aggiornato è in AEM, la creazione può continuare.

Congratulazioni. congratulations

Congratulazioni, hai aggiornato l’SPA ed esplorato l’integrazione con l’AEM! Ora sai come sviluppare l'SPA contro l'API del modello JSON AEM utilizzando un webpack-dev-server.

Passaggi successivi next-steps

Mappare i componenti SPA ai componenti AEM - Scopri come mappare i componenti React ai componenti Adobe Experience Manager (AEM) con l'SDK JS dell'editor SPA dell'AEM. La mappatura dei componenti consente agli utenti di apportare aggiornamenti dinamici ai componenti SPA nell’Editor SPA dell’AEM, in modo simile all’authoring AEM tradizionale.

(Bonus) Server di sviluppo Webpack - Mock dell’API JSON mock-json

Un altro approccio allo sviluppo rapido consiste nell’utilizzare un file JSON statico come modello JSON. "Deridendo" il JSON, rimuoviamo la dipendenza da un’istanza AEM locale. Consente inoltre a uno sviluppatore front-end di aggiornare il modello JSON per testare la funzionalità e apportare modifiche all’API JSON che verrebbero successivamente implementate da uno sviluppatore back-end.

La configurazione iniziale del JSON fittizio richiede un'istanza AEM locale.

  1. Tornare all'IDE, passare a ui.frontend/public e aggiungere una nuova cartella denominata mock-content.

  2. Crea un nuovo file denominato mock.model.json sotto a ui.frontend/public/mock-content.

  3. Nel browser passa a http://localhost:4502/content/wknd-spa-react/us/en.model.json.

    Questo è il JSON esportato dall’AEM che sta guidando l’applicazione. Copia l’output JSON.

  4. Incolla l'output JSON del passaggio precedente nel file mock.model.json.

    File Json modello fittizio

  5. Aprire il file index.html in ui.frontend/public/index.html. Aggiornare la proprietà dei metadati per il modello di pagina AEM per puntare a una variabile %REACT_APP_PAGE_MODEL_PATH%:

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

    L'utilizzo di una variabile per il valore di cq:pagemodel_root_url semplificherà l'alternanza tra proxy e modello json fittizio.

  6. Aprire il file ui.frontend/.env.development e apportare i seguenti aggiornamenti per commentare il valore precedente per 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 è in esecuzione, arrestare webpack-dev-server. Avvia webpack-dev-server dal terminale:

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

    Passa a http://localhost:3000/content/wknd-spa-react/us/en/home.html per visualizzare l'SPA con lo stesso contenuto utilizzato nel json proxy.

  8. Apportare una piccola modifica al file mock.model.json creato in precedenza. Dovresti vedere il contenuto aggiornato immediatamente riflesso nel webpack-dev-server.

    aggiornamento json modello fittizio

La capacità di manipolare il modello JSON e di vedere gli effetti su un SPA in tempo reale può aiutare uno sviluppatore a comprendere l’API del modello JSON. Consente inoltre lo sviluppo sia front-end che back-end in parallelo.

È ora possibile cambiare la posizione in cui utilizzare il contenuto JSON attivando/disattivando le voci nel file 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