Modifica di una SPA esterna in AEM

Quando si decide quale livello di integrazione si desidera avere tra il SPA esterno e il AEM, spesso è necessario essere in grado di modificare e visualizzare il SPA all'interno AEM.

Panoramica

Questo documento descrive i passaggi consigliati per caricare un SPA standalone in un’istanza AEM, aggiungere sezioni di contenuto modificabili e abilitare l’authoring.

Prerequisiti

I prerequisiti sono semplici.

  • Assicurarsi che un'istanza di AEM sia in esecuzione localmente.
  • Crea un progetto di base AEM SPA utilizzando il tipo di archivio AEM progetti.
    • Questo costituirà la base del progetto AEM che verrà aggiornato per includere il SPA esterno.
    • Per gli esempi in questo documento, stiamo utilizzando il punto di partenza di il progetto di SPA WKND.
  • Avere a portata di mano la React SPA operativa ed esterna che si desidera integrare.

Carica SPA in AEM progetto

Innanzitutto, è necessario caricare la SPA esterna nel progetto AEM.

  1. Sostituire src nella cartella del progetto /ui.frontend con la cartella src dell'applicazione React.
  2. Includi eventuali dipendenze aggiuntive nel file package.json dell'app nel file /ui.frontend/package.json.
  3. Includi eventuali personalizzazioni nella cartella /public.
  4. Includere eventuali script o stili in linea aggiunti nel file /public/index.html.

Configurare il SPA remoto

Ora che il SPA esterno fa parte del progetto AEM, deve essere configurato all’interno di AEM.

Includere Adobe SPA pacchetti SDK

Per sfruttare AEM funzionalità SPA, esistono dipendenze dai tre pacchetti seguenti.

@adobe/aem-spa-page-model-manager fornisce l'API per l'inizializzazione di Model Manager e il recupero del modello dall'istanza AEM. Questo modello può quindi essere utilizzato per eseguire il rendering AEM componenti utilizzando le API di @adobe/aem-react-editable-components e @adobe/aem-spa-component-mapping.

Installazione

Eseguite il seguente comando npm per installare i pacchetti richiesti.

npm install --save @adobe/aem-spa-component-mapping @adobe/aem-spa-page-model-manager @adobe/aem-react-editable-components

Inizializzazione ModelManager

Prima del rendering dell'app, è necessario inizializzare ModelManager per gestire la creazione del AEM ModelStore.

Questa operazione deve essere eseguita all'interno del file src/index.js dell'applicazione o ovunque venga eseguito il rendering della radice dell'applicazione.

A tal fine, è possibile utilizzare l'API initializationAsync fornita da ModelManager.

La schermata seguente mostra come abilitare l'inizializzazione di ModelManager in una semplice applicazione React. L'unico vincolo è che initializationAsync deve essere chiamato prima di ReactDOM.render().

Inizializza ModelManager

In questo esempio, ModelManager viene inizializzato e viene creato un ModelStore vuoto.

initializationAsync Facoltativamente, è possibile accettare un options oggetto come parametro:

  • path - Al momento dell'inizializzazione, il modello nel percorso definito viene recuperato e memorizzato nel ModelStore. Questo può essere utilizzato per recuperare il rootModel all'inizializzazione, se necessario.
  • modelClient - Consente di fornire un client personalizzato responsabile per il recupero del modello.
  • model - Un model oggetto passato come parametro generalmente popolato quando si utilizza SSR.

AEM Componenti Leaf Autorizzati

  1. Creare/identificare un componente AEM per il quale verrà creato un componente React autorizzabile. In questo esempio, stiamo utilizzando il componente di testo del progetto WKND.

    Componente Testo WKND

  2. Create un semplice componente di testo React (Reazione) nella SPA. In questo esempio, è stato creato un nuovo file Text.js con il seguente contenuto.

    Text.js

  3. Create un oggetto di configurazione per specificare gli attributi necessari per abilitare AEM modifica.

    Crea oggetto config

    • resourceType è obbligatorio mappare il componente React sul componente AEM e attivarlo all’apertura nell’editor AEM.
  4. Utilizzare la funzione wrapper withMappable.

    Usa conMappable

    Questa funzione wrapper mappa il componente React sul AEM resourceType specificato nella configurazione e abilita le funzionalità di modifica quando aperto nell'editor AEM. Per i componenti standalone, recupererà anche il contenuto del modello per il nodo specifico.

    NOTA

    In questo esempio sono disponibili diverse versioni del componente: AEM componenti React con wrapper e senza wrapper. La versione a capo deve essere utilizzata quando si utilizza esplicitamente il componente. Quando il componente fa parte di una pagina, potete continuare a usare il componente predefinito come avviene attualmente nell’editor SPA.

  5. Eseguire il rendering del contenuto nel componente.

    Le proprietà JCR del componente di testo vengono visualizzate come segue in AEM.

    Proprietà dei componenti di testo

    Questi valori vengono passati come proprietà al componente AEMText React appena creato e possono essere utilizzati per il rendering del contenuto.

    import React from 'react';
    import { withMappable } from '@adobe/aem-react-editable-components';
    
    export const TextEditConfig = {
        // Empty component placeholder label
        emptyLabel:'Text', 
        isEmpty:function(props) {
           return !props || !props.text || props.text.trim().length < 1;
        },
        // resourcetype of the AEM counterpart component
        resourceType:'wknd-spa-react/components/text'
    };
    
    const Text = ({ text }) => (<div>{text}</div>);
    
    export default Text;
    
    export const AEMText = withMappable(Text, TextEditConfig);
    

    Questo è il modo in cui il componente viene visualizzato al termine delle configurazioni AEM.

    const Text = ({ cqPath, richText, text }) => {
       const richTextContent = () => (
          <div className="aem_text" id={cqPath.substr(cqPath.lastIndexOf('/') + 1)} data-rte-editelement dangerouslySetInnerHTML={{__html: text}}/>
       );
       return richText ? richTextContent() : (<div className="aem_text">{text}</div>);
    };
    
    NOTA

    In questo esempio, sono state apportate ulteriori personalizzazioni al componente di cui è stato effettuato il rendering in modo che corrisponda al componente di testo esistente. Questo tuttavia non è correlato all’authoring in AEM.

Aggiungere componenti modificabili alla pagina

Una volta creati i componenti React che possono essere utilizzati in tutta l’applicazione.

Prendiamo una pagina di esempio in cui è necessario aggiungere un testo dal progetto WKND SPA. Per questo esempio, vogliamo visualizzare il testo "Hello World!" su /content/wknd-spa-react/us/en/home.html.

  1. Determinare il percorso del nodo da visualizzare.

    • pagePath: La pagina che contiene il nodo, nel nostro esempio /content/wknd-spa-react/us/en/home
    • itemPath: Percorso del nodo all'interno della pagina, nel nostro esempio root/responsivegrid/text
      • È costituito dai nomi degli elementi che li contengono sulla pagina.

    Percorso del nodo

  2. Aggiungere un componente alla posizione desiderata nella pagina.

    Aggiungere un componente alla pagina

    Il componente AEMText può essere aggiunto alla posizione desiderata all'interno della pagina con i valori pagePath e itemPath impostati come proprietà. pagePath è una proprietà obbligatoria.

Verifica della modifica del contenuto del testo su AEM

Ora è possibile testare il componente nell’istanza di AEM in esecuzione.

  1. Eseguite il seguente comando Maven dalla directory aem-guides-wknd-spa per creare e distribuire il progetto in AEM.
mvn clean install -PautoInstallSinglePackage
  1. Nell'istanza AEM, passare a http://<host>:<port>/editor.html/content/wknd-spa-react/us/en/home.html.

Modifica del SPA in AEM

Il componente AEMText è ora compatibile con AEM.

AEM Pagine Autorizzate

  1. Identificare una pagina da aggiungere per l’authoring nel SPA. In questo esempio viene utilizzato /content/wknd-spa-react/us/en/home.html.

  2. Creare un nuovo file (ad es. Page.js) per il componente Pagina modificabile. Qui è possibile riutilizzare il componente Pagina fornito in @adobe/cq-react-editable-components.

  3. Ripetere il passaggio 4 nella sezione AEM componenti foglia autorizzabili. Utilizzare la funzione wrapper withMappable sul componente.

  4. Come già fatto in precedenza, applicare MapTo ai tipi di risorse AEM per tutti i componenti secondari all'interno della pagina.

    import { Page, MapTo, withMappable } from '@adobe/aem-react-editable-components';
    import Text, { TextEditConfig } from './Text';
    
    export default withMappable(Page);
    
    MapTo('wknd-spa-react/components/text')(Text, TextEditConfig);
    
    NOTA

    In questo esempio stiamo utilizzando il componente di testo React non racchiuso invece del AEMText racchiuso creato in precedenza. Questo perché quando il componente fa parte di una pagina/contenitore e non è il solo contenitore, il contenitore si occuperà di mappare in modo ricorsivo il componente e di abilitare le funzionalità di authoring, e il wrapper aggiuntivo non è necessario per ogni elemento secondario.

  5. Per aggiungere una pagina modificabile nella SPA, procedere come segue nella sezione Aggiungi componenti modificabili alla pagina. Qui è possibile saltare la itemPath proprietà.

Verifica contenuto pagina su AEM

Per verificare che la pagina possa essere modificata, procedere come segue nella sezione Verifica della modifica del contenuto di testo in AEM.

Modifica di una pagina in AEM

La pagina è ora modificabile su AEM con un Contenitore di layout e un Componente testo secondario.

Componenti foglia virtuale

Negli esempi precedenti, abbiamo aggiunto componenti al SPA con contenuti AEM esistenti. Tuttavia, in alcuni casi il contenuto non è ancora stato creato in AEM, ma deve essere aggiunto successivamente dall’autore del contenuto. A tal fine, lo sviluppatore front-end può aggiungere componenti nelle posizioni appropriate all’interno del SPA. Questi componenti visualizzeranno dei segnaposto quando vengono aperti nell'editor in AEM. Una volta che il contenuto viene aggiunto all’interno di questi segnaposto dall’autore del contenuto, i nodi vengono creati nella struttura JCR e il contenuto viene mantenuto. Il componente creato consentirà lo stesso set di operazioni dei componenti a foglia autonoma.

In questo esempio, stiamo riutilizzando il componente AEMText creato in precedenza. Il nuovo testo deve essere aggiunto sotto il componente di testo esistente nella home page WKND. L’aggiunta di componenti è la stessa dei normali componenti foglia. Tuttavia, è possibile aggiornare itemPath al percorso in cui è necessario aggiungere il nuovo componente.

Poiché il nuovo componente deve essere aggiunto sotto il testo esistente in root/responsivegrid/text, il nuovo percorso sarà root/responsivegrid/{itemName}.

<AEMText
 pagePath='/content/wknd-spa-react/us/en/home'
 itemPath='root/responsivegrid/text_20' />

Dopo l'aggiunta del componente virtuale, il componente TestPage si presenta come segue.

Verifica del componente virtuale

NOTA

Verificare che il componente AEMText sia resourceType impostato nella configurazione per abilitare questa funzione.

È ora possibile distribuire le modifiche AEM seguendo la procedura indicata nella sezione Verifica della modifica del contenuto di testo in AEM. Verrà visualizzato un segnaposto per il text_20 nodo attualmente non esistente.

Il nodo text_20 in Aem

Quando l'autore del contenuto aggiorna questo componente, viene creato un nuovo nodo text_20 in root/responsivegrid/text_20 in /content/wknd-spa-react/us/en/home.

Il nodo text20

Requisiti e limitazioni

Esistono diversi requisiti per aggiungere componenti foglia virtuale e alcuni limiti.

  • La proprietà pagePath è obbligatoria per la creazione di un componente virtuale.
  • Il nodo di pagina fornito nel percorso in pagePath deve esistere nel progetto AEM.
  • Il nome del nodo da creare deve essere specificato in itemPath.
  • Il componente può essere creato a qualsiasi livello.
    • Se forniamo un itemPath='text_20' nell’esempio precedente, il nuovo nodo verrà creato direttamente sotto la pagina, ovvero /content/wknd-spa-react/us/en/home/jcr:content/text_20
  • Il percorso del nodo in cui viene creato un nuovo nodo deve essere valido se fornito tramite itemPath.
    • In questo esempio, root/responsivegrid deve esistere in modo che sia possibile creare il nuovo nodo text_20.
  • È supportata solo la creazione di componenti foglia. Il contenitore virtuale e la pagina saranno supportati nelle versioni future.

Personalizzazioni aggiuntive

Se avete seguito gli esempi precedenti, la vostra SPA esterna ora è modificabile in AEM. Tuttavia, potete personalizzare ulteriormente alcuni aspetti della vostra SPA esterna.

ID nodo radice

Per impostazione predefinita, il rendering dell'applicazione React viene eseguito all'interno di un div ID elemento spa-root. Se necessario, può essere personalizzato.

Ad esempio, supponiamo che sia presente un SPA in cui l'applicazione viene rappresentata all'interno di un div ID elemento root. Questo deve essere riflesso in tre file.

  1. In index.js dell'applicazione React (o dove viene chiamato ReactDOM.render())

    ReactDOM.rendering() nel file index.js

  2. Nell' index.html dell'applicazione React

    index.html dell’applicazione

  3. Nel corpo del componente della pagina dell'app AEM tramite due passaggi:

    1. Create un nuovo elemento body.html per il componente pagina.

    Creare un nuovo file body.html

    1. Aggiungete il nuovo elemento principale nel nuovo file body.html.

    Aggiungere l'elemento principale a body.html

Modifica di un SPA React con Routing

Se l'applicazione React SPA esterna ha più pagine, può utilizzare il routing per determinare la pagina/il componente da eseguire. L’esempio di base prevede la corrispondenza dell’URL attualmente attivo rispetto al percorso fornito per una route. Per abilitare la modifica su tali applicazioni abilitate per il routing, il percorso a cui confrontarsi deve essere trasformato per contenere informazioni specifiche per AEM.

Nell'esempio seguente è disponibile una semplice applicazione React con due pagine. La pagina di cui eseguire il rendering è determinata dalla corrispondenza del percorso fornito al router rispetto all'URL attivo. Ad esempio, se il numero è impostato su mydomain.com/test, verrà eseguito il rendering di TestPage.

Routing in un SPA esterno

Per abilitare la modifica entro AEM per questo SPA di esempio, sono necessari i seguenti passaggi.

  1. Identificare il livello che fungerebbe da radice su AEM.

    • Per il nostro campione, stiamo considerando wknd-spa-response/us/en come la radice del SPA. Ciò significa che tutto ciò che precede tale percorso è AEM solo pagine/contenuti.
  2. Create una nuova pagina al livello desiderato.

    • In questo esempio, la pagina da modificare è mydomain.com/test. test si trova nel percorso principale dell'app. Questo deve essere mantenuto anche durante la creazione della pagina in AEM. È quindi possibile creare una nuova pagina al livello principale definito nel passaggio precedente.
    • La nuova pagina creata deve avere lo stesso nome della pagina da modificare. In questo esempio per mydomain.com/test, la nuova pagina creata deve essere /path/to/aem/root/test.
  3. Aggiungere gli assistenti all'interno SPA routing.

    • La pagina appena creata non esegue ancora il rendering del contenuto previsto in AEM. Questo perché il router prevede un percorso di /test mentre il percorso attivo AEM è /wknd-spa-react/us/en/test. Per contenere la porzione AEM specifica dell’URL, è necessario aggiungere alcuni assistenti sul lato SPA.

    Helper di routing

    • A questo scopo è possibile utilizzare il supporto toAEMPath fornito da @adobe/cq-spa-page-model-manager. Trasforma il percorso fornito per il routing in modo da includere porzioni specifiche AEM quando l'applicazione è aperta in un'istanza AEM. Accetta tre parametri:
      • Percorso richiesto per il routing
      • L'URL di origine dell'istanza AEM in cui viene modificato il SPA
      • Radice del progetto su AEM come determinato nel primo passaggio
    • Questi valori possono essere impostati come variabili di ambiente per una maggiore flessibilità.
  4. Verificare la modifica della pagina in AEM.

    • Distribuisci il progetto per AEM e passare alla nuova pagina test creata. È ora possibile eseguire il rendering del contenuto della pagina e AEM componenti sono modificabili.

Risorse aggiuntive

Il seguente materiale di riferimento può essere utile per comprendere SPA nel contesto di AEM.

In questa pagina