Modifica di un SPA esterno in Adobe Experience Manager editing-external-spa-within-aem
Quando si decide quale livello di integrazione si desidera avere tra l’SPA esterno e il Adobe Experience Manager (AEM), spesso è necessario essere in grado di modificare e visualizzare l’SPA all’interno dell’AEM.
Panoramica overview
Questo documento descrive i passaggi consigliati per caricare un SPA autonomo in un’istanza AEM, aggiungere sezioni di contenuto modificabili e abilitare l’authoring.
Prerequisiti prerequisites
I prerequisiti sono semplici.
-
Verificare che un'istanza dell'AEM sia in esecuzione localmente.
-
Creare un progetto SPA AEM di base utilizzando l'archetipo del progetto AEM.
- Su questa base si basa il progetto AEM, che sarà aggiornato per includere l'SPA esterno.
- Gli esempi in questo documento utilizzano il punto di partenza del progetto WKND SPA.
-
Avere l'SPA React funzionante esterno che si desidera integrare a portata di mano.
Carica SPA in progetto AEM upload-spa-to-aem-project
Innanzitutto, devi caricare l’SPA esterno nel tuo progetto AEM.
- Sostituisci
src
nella cartella dei progetti/ui.frontend
con la cartellasrc
dell'applicazione React. - Includere eventuali dipendenze aggiuntive nel file
/ui.frontend/package.json
dell'apppackage.json
.- Assicurati che le dipendenze dell'SDK SPA siano di versioni consigliate.
- Includere eventuali personalizzazioni nella cartella
/public
. - Includere eventuali script o stili in linea aggiunti nel file
/public/index.html
.
Configurare l’SPA remoto configure-remote-spa
Ora che l’SPA esterno fa parte del progetto AEM, deve essere configurato all’interno dell’AEM.
Includi pacchetti SDK SPA di Adobe include-spa-sdk-packages
Per sfruttare le caratteristiche dell'SPA dell'AEM, ci sono 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 dei componenti AEM utilizzando le API di @adobe/aem-react-editable-components
e @adobe/aem-spa-component-mapping
.
Installazione installation
Esegui 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 di ModelManager model-manager-initialization
Prima del rendering dell'app, è necessario inizializzare ModelManager
per gestire la creazione dell'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.
Per questo, utilizza l'API initializationAsync
fornita da ModelManager
.
Nella schermata seguente viene illustrato come abilitare l'inizializzazione di ModelManager
in una semplice applicazione React. L'unico vincolo è che initializationAsync
deve essere chiamato prima di ReactDOM.render()
.
In questo esempio, ModelManager
è inizializzato e viene creato un ModelStore
vuoto.
initializationAsync
può accettare un oggetto options
come parametro:
path
- All'inizializzazione, il modello nel percorso definito viene recuperato e memorizzato inModelStore
. Può essere utilizzato per recuperarerootModel
all'inizializzazione, se necessario.modelClient
- Consente di fornire un client personalizzato responsabile del recupero del modello.model
- Un oggettomodel
passato come parametro viene generalmente popolato quando si utilizza SSR
Componenti foglia compatibili con AEM authorable-leaf-components
-
Creare/identificare un componente AEM per il quale verrà creato un componente React modificabile. In questo esempio, il progetto WKND utilizza il componente testo.
-
Creare un componente testo React semplice nell’SPA. In questo esempio è stato creato un nuovo file
Text.js
con il contenuto seguente. -
Crea un oggetto di configurazione per specificare gli attributi necessari per abilitare la modifica AEM.
resourceType
è obbligatorio per mappare il componente React al componente AEM e abilitare la modifica all'apertura nell'editor AEM.
-
Utilizzare la funzione wrapper
withMappable
.Questa funzione wrapper mappa il componente React all'AEM
resourceType
specificato nella configurazione e abilita le funzionalità di modifica quando viene aperto nell'editor AEM. Per i componenti autonomi, recupera anche il contenuto del modello per il nodo specifico.note note NOTE In questo esempio, esistono versioni separate del componente: componenti AEM wrapped e React unwrapped. La versione racchiusa deve essere utilizzata quando si utilizza esplicitamente il componente. Quando il componente fa parte di una pagina, puoi continuare a utilizzare il componente predefinito come già fatto nell’editor SPA. -
Esegui il rendering del contenuto nel componente.
Le proprietà JCR del componente testo vengono visualizzate come segue in AEM.
Questi valori vengono passati come proprietà al componente React
AEMText
appena creato e possono essere utilizzati per il rendering del contenuto.code language-javascript 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 appare quando le configurazioni dell’AEM sono completate.
code language-javascript 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>); };
note note NOTE In questo esempio, sono state apportate ulteriori personalizzazioni al componente di cui è stato eseguito il rendering, in modo che corrisponda al componente testo esistente. Questo tuttavia non è correlato all’authoring in AEM.
Aggiungere componenti autorizzabili alla pagina add-authorable-component-to-page
Una volta creati, i componenti React possono essere utilizzati in tutta l’applicazione.
Prendiamo una pagina di esempio in cui è necessario aggiungere testo dal progetto WKND SPA. In questo esempio, si desidera visualizzare il testo "Hello World!" il /content/wknd-spa-react/us/en/home.html
.
-
Determina il percorso del nodo da visualizzare.
pagePath
: la pagina che contiene il nodo, nell'esempio/content/wknd-spa-react/us/en/home
itemPath
: percorso del nodo all'interno della pagina, nell'esempioroot/responsivegrid/text
- È costituito dai nomi degli elementi che la contengono nella pagina.
-
Aggiungi il componente nella posizione richiesta nella pagina.
Il componente
AEMText
può essere aggiunto nella posizione richiesta all'interno della pagina con valoripagePath
eitemPath
impostati come proprietà.pagePath
è una proprietà obbligatoria.
Verificare la modifica del contenuto di testo su AEM verify-text-edit
Ora testa il componente sull’istanza AEM in esecuzione.
- Eseguire il seguente comando Maven dalla directory
aem-guides-wknd-spa
per generare e distribuire il progetto a AEM.
mvn clean install -PautoInstallSinglePackage
- Nell'istanza AEM, passa a
http://<host>:<port>/editor.html/content/wknd-spa-react/us/en/home.html
.
Il componente AEMText
è ora modificabile in AEM.
Pagine AEM modificabili aem-authorable-pages
-
Identifica una pagina da aggiungere per l’authoring nell’SPA. Questo esempio utilizza
/content/wknd-spa-react/us/en/home.html
. -
Creare un file (ad esempio,
Page.js
) per il componente Pagina modificabile. In questo caso, è possibile riutilizzare il componente Pagina fornito in@adobe/cq-react-editable-components
. -
Ripetere il passaggio 4 nella sezione Componenti foglia modificabili dall'AEM. Utilizzare la funzione wrapper
withMappable
sul componente. -
Come già fatto in precedenza, applica
MapTo
ai tipi di risorse AEM per tutti i componenti secondari all'interno della pagina.code language-javascript 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);
note note NOTE In questo esempio, viene utilizzato il componente testo React decompresso al posto di AEMText
creato in precedenza. Questo perché quando il componente fa parte di una pagina o di un contenitore e non è autonomo, il contenitore si occupa della mappatura ricorsiva del componente e dell’abilitazione delle funzionalità di authoring e il wrapper aggiuntivo non è necessario per ogni elemento secondario. -
Per aggiungere una pagina modificabile nell'SPA, seguire gli stessi passaggi della sezione Aggiungere componenti modificabili alla pagina. In questo caso, tuttavia, è possibile ignorare la proprietà
itemPath
.
Verifica contenuto pagina in AEM verify-page-content
Per verificare che la pagina possa essere modificata, seguire gli stessi passaggi della sezione Verifica modifica del contenuto di testo su AEM.
La pagina è ora modificabile su AEM con un contenitore di layout e un componente testo figlio.
Componenti foglia virtuale virtual-leaf-components
Negli esempi precedenti, abbiamo aggiunto componenti all’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. In questo modo, lo sviluppatore front-end può aggiungere componenti nelle posizioni appropriate all’interno dell’SPA. Questi componenti visualizzano i 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 consente di eseguire le stesse operazioni dei componenti foglia autonomi.
In questo esempio viene riutilizzato il componente AEMText
creato in precedenza. Desideriamo che venga aggiunto nuovo testo sotto il componente testo esistente nella home page di WKND. L’aggiunta dei componenti è la stessa dei normali componenti foglia. Tuttavia, itemPath
può essere aggiornato al percorso in cui è necessario aggiungere il nuovo componente.
Poiché è necessario aggiungere il nuovo componente 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.
AEMText
abbia impostato resourceType
nella configurazione per abilitare questa funzione.È ora possibile distribuire le modifiche all'AEM seguendo i passaggi descritti nella sezione Verifica della modifica del contenuto di testo nell'AEM. Viene visualizzato un segnaposto per il nodo text_20
attualmente non esistente.
Quando l'autore di contenuto aggiorna questo componente, viene creato un nuovo nodo text_20
in root/responsivegrid/text_20
in /content/wknd-spa-react/us/en/home
.
Requisiti e limitazioni limitations
Esistono diversi requisiti per aggiungere componenti foglia virtuali e alcune limitazioni.
- La proprietà
pagePath
è obbligatoria per creare 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 si specifica
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
- Se si specifica
- Il percorso del nodo in cui viene creato un nuovo nodo deve essere valido quando fornito tramite
itemPath
.- In questo esempio,
root/responsivegrid
deve esistere in modo che il nuovo nodotext_20
possa essere creato lì.
- In questo esempio,
- È supportata solo la creazione di componenti foglia. Contenitore virtuale e pagina saranno supportati nelle versioni future.
Contenitori virtuali virtual-containers
È supportata la possibilità di aggiungere contenitori, anche se il contenitore corrispondente non è ancora stato creato in AEM. Il concetto e l'approccio sono simili a componenti foglia virtuali.
Lo sviluppatore front-end può aggiungere i componenti contenitore nelle posizioni appropriate all’interno dell’SPA e tali componenti visualizzeranno dei segnaposto quando vengono aperti nell’editor nell’AEM. L’autore può quindi aggiungere componenti e il relativo contenuto al contenitore, che creerà i nodi richiesti nella struttura JCR.
Ad esempio, se in /root/responsivegrid
esiste già un contenitore e lo sviluppatore desidera aggiungere un nuovo contenitore secondario:
newContainer
non esiste ancora nel AEM.
Durante la modifica della pagina che contiene questo componente in AEM, viene visualizzato un segnaposto vuoto per un contenitore in cui l’autore può aggiungere contenuti.
Una volta che l’autore aggiunge un componente secondario al contenitore, il nuovo nodo del contenitore viene creato con il nome corrispondente nella struttura JCR.
È ora possibile aggiungere al contenitore altri componenti e contenuti necessari all’autore e le modifiche verranno mantenute.
Requisiti e limitazioni container-limitations
Esistono diversi requisiti per aggiungere contenitori virtuali e alcune limitazioni.
-
Il criterio per determinare quali componenti possono essere aggiunti verrà ereditato dal contenitore principale.
-
L’elemento padre diretto del contenitore da creare deve già esistere in AEM.
- Se il contenitore
root/responsivegrid
esiste già nel contenitore AEM, è possibile creare un nuovo contenitore fornendo il percorsoroot/responsivegrid/newContainer
. - Tuttavia
root/responsivegrid/newContainer/secondNewContainer
non è possibile.
- Se il contenitore
-
È possibile creare un solo nuovo livello di componente alla volta.
Personalizzazioni aggiuntive additional-customizations
Se hai seguito gli esempi precedenti, il tuo SPA esterno è ora modificabile all’interno dell’AEM. Tuttavia, vi sono altri aspetti del vostro SPA esterno che potete personalizzare ulteriormente.
ID nodo principale root-node-id
Per impostazione predefinita, si presuppone che l'applicazione React sia rappresentata all'interno di un div
di ID elemento spa-root
. Se necessario, questo può essere personalizzato.
Ad esempio, si supponga di disporre di un SPA in cui l'applicazione viene rappresentata all'interno di un div
di ID elemento root
. Questo deve essere riflesso in tre file.
-
In
index.js
dell'applicazione React (o dove viene chiamatoReactDOM.render()
) -
In
index.html
dell'applicazione React -
Nel corpo del componente Pagina dell’app AEM, segui questi due passaggi:
- Crea un
body.html
per il componente pagina.
- Aggiungere il nuovo elemento radice nel nuovo file
body.html
.
- Crea un
Modifica di un SPA React con routing editing-react-spa-with-routing
Se l'applicazione esterna React SPA ha più pagine, può usare il routing per determinare la pagina/componente da riprodurre. Il caso d’uso di base prevede che l’URL attualmente attivo corrisponda al percorso fornito per una route. Per consentire la modifica di tali applicazioni abilitate per l’instradamento, il percorso da confrontare deve essere trasformato per adattarsi alle informazioni specifiche dell’AEM.
Nell’esempio seguente abbiamo una semplice applicazione React con due pagine. La pagina di cui eseguire il rendering viene determinata confrontando il percorso fornito al router con l’URL attivo. Ad esempio, se ci troviamo su mydomain.com/test
, verrà eseguito il rendering di TestPage
.
Per abilitare la modifica all’interno dell’AEM per questo esempio di SPA, sono necessari i seguenti passaggi.
-
Identificare il livello che fungerebbe da base per l’AEM.
- Per il nostro esempio, consideriamo
wknd-spa-react/us/en
come la radice dell'SPA. Ciò significa che tutto ciò che precede quel percorso sono solo pagine/contenuti AEM.
- Per il nostro esempio, consideriamo
-
Crea una pagina al livello richiesto.
- In questo esempio, la pagina da modificare è
mydomain.com/test
.test
è nel percorso principale dell'app. Questo deve essere mantenuto anche durante la creazione della pagina in AEM. Pertanto, puoi creare una 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
.
- In questo esempio, la pagina da modificare è
-
Aggiungere helper all’interno del routing SPA.
- La pagina appena creata non eseguirà ancora il rendering del contenuto previsto in AEM. Il router prevede un percorso di
/test
, mentre il percorso attivo AEM è/wknd-spa-react/us/en/test
. Per adattarsi alla porzione dell’URL specifica per l’AEM, è necessario aggiungere degli helper sul lato SPA.
-
È possibile utilizzare l'helper
toAEMPath
fornito da@adobe/cq-spa-page-model-manager
. Trasforma il percorso fornito per il routing in modo da includere parti specifiche dell'AEM quando l'applicazione è aperta su un'istanza dell'AEM. Accetta tre parametri:- Percorso necessario per il routing
- URL di origine dell’istanza AEM in cui viene modificato l’SPA
- Elemento di base del progetto sull’AEM come determinato nella prima fase
-
Questi valori possono essere impostati come variabili di ambiente per maggiore flessibilità.
- La pagina appena creata non eseguirà ancora il rendering del contenuto previsto in AEM. Il router prevede un percorso di
-
Verifica la modifica della pagina in AEM.
- Distribuire il progetto in AEM e passare alla pagina
test
appena creata. Ora viene eseguito il rendering del contenuto della pagina e i componenti AEM sono modificabili.
- Distribuire il progetto in AEM e passare alla pagina
Limitazioni del framework framework-limitations
Il componente RemotePage prevede che l'implementazione fornisca un manifesto delle risorse come webpack-manifest-plugin su GitHub. Il componente RemotePage, tuttavia, è stato testato per funzionare solo con il framework React (e Next.js tramite il componente remote-page-next ) e pertanto non supporta il caricamento remoto di applicazioni da altri framework, come ad Angular.
Risorse aggiuntive additional-resources
I seguenti materiali di riferimento possono essere utili per comprendere l'SPA nel contesto dell'AEM.