Quando si decide quale livello di integrazione si desidera avere tra l'SPA esterno e l'AEM, spesso è necessario essere in grado di modificare e visualizzare l'SPA all'interno dell'AEM.
Questo documento descrive i passaggi consigliati per caricare un SPA autonomo in un’istanza AEM, aggiungere sezioni di contenuto modificabili e abilitare l’authoring.
I prerequisiti sono semplici.
Innanzitutto devi caricare l’SPA esterno nel tuo progetto AEM.
src
nel /ui.frontend
cartella di progetto con l'applicazione React src
cartella.package.json
nel /ui.frontend/package.json
file.
/public
cartella./public/index.html
file.Ora che l'SPA esterno fa parte del progetto AEM, deve essere configurato all'interno dell'AEM.
Per sfruttare le caratteristiche dell'SPA dell'AEM, ci sono dipendenze dai tre pacchetti seguenti.
@adobe/aem-react-editable-components
@adobe/aem-spa-component-mapping
@adobe/aem-spa-page-model-manager
@adobe/aem-spa-page-model-manager
fornisce l’API per inizializzare Model Manager e recuperare il 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
.
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
Prima del rendering dell’app, il ModelManager
deve essere inizializzato per gestire la creazione dell’AEM ModelStore
.
Questa operazione deve essere eseguita entro src/index.js
dell’applicazione o ovunque venga eseguito il rendering della directory principale dell’applicazione.
Per questo, possiamo utilizzare initializationAsync
API fornite da ModelManager
.
La schermata seguente mostra come abilitare l’inizializzazione del ModelManager
in una semplice applicazione React. L'unico vincolo è che initializationAsync
deve essere chiamato prima di ReactDOM.render()
.
In questo esempio, la proprietà ModelManager
è inizializzato e un valore vuoto ModelStore
viene creato.
initializationAsync
può facoltativamente accettare un options
object come parametro:
path
- Al momento dell'inizializzazione, il modello nel percorso definito viene recuperato e memorizzato nel ModelStore
. Può essere utilizzato per recuperare rootModel
all’inizializzazione, se necessario.modelClient
- Consente di fornire un client personalizzato responsabile del recupero del modello.model
- A model
l'oggetto passato come parametro viene generalmente popolato quando utilizzo di SSRCreare/identificare un componente AEM per il quale verrà creato un componente React modificabile. In questo esempio utilizziamo il componente testo del progetto WKND.
Creare un componente testo React semplice nell’SPA. In questo esempio, un nuovo file Text.js
è stato creato con il seguente contenuto.
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 quando si apre 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, recupererà anche il contenuto del modello per il nodo specifico.
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 nuovo AEMText
React e può essere utilizzato per riprodurre il 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 apparirà il componente una volta completate le configurazioni dell’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>);
};
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.
Una volta creati i componenti React personalizzabili, possiamo utilizzarli in tutta l’applicazione.
Prendiamo una pagina di esempio in cui dobbiamo aggiungere un testo dal progetto WKND SPA. Per 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, nel nostro esempio /content/wknd-spa-react/us/en/home
itemPath
: percorso del nodo all’interno della pagina, nel nostro esempio root/responsivegrid/text
Aggiungi il componente nella posizione richiesta nella pagina.
Il AEMText
Il componente può essere aggiunto nella posizione desiderata all’interno della pagina con pagePath
e itemPath
valori impostati come proprietà. pagePath
è una proprietà obbligatoria.
Ora possiamo testare il componente sull’istanza AEM in esecuzione.
aem-guides-wknd-spa
per generare e distribuire il progetto in AEM.mvn clean install -PautoInstallSinglePackage
http://<host>:<port>/editor.html/content/wknd-spa-react/us/en/home.html
.Il AEMText
Il componente è ora disponibile per l’authoring su AEM.
Identifica una pagina da aggiungere per l’authoring nell’SPA. Questo esempio utilizza /content/wknd-spa-react/us/en/home.html
.
Crea 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
.
Ripeti il passaggio quattro nella sezione Componenti fogliari modificabili da 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.
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);
In questo esempio viene utilizzato il componente testo React non racchiuso invece del testo racchiuso 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, segui gli stessi passaggi descritti nella sezione Aggiungere componenti autorizzabili alla pagina. Qui possiamo saltare il itemPath
proprietà.
Per verificare che la pagina possa essere modificata, segui gli stessi passaggi descritti nella sezione Verifica la modifica del contenuto di testo su AEM.
La pagina è ora modificabile su AEM con un contenitore di layout e un componente testo figlio.
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, stiamo riutilizzando AEMText
componente 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, il itemPath
può essere aggiornato 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' />
Il TestPage
dopo l’aggiunta del componente virtuale, il componente si presenta come segue.
Assicurati che AEMText
il componente ha il suo resourceType
nella configurazione per abilitare questa funzione.
Ora puoi implementare le modifiche all’AEM seguendo i passaggi descritti nella sezione Verifica la modifica del contenuto di testo su AEM. Verrà visualizzato un segnaposto per il file attualmente non esistente text_20
nodo.
Quando l’autore di contenuto aggiorna questo componente, viene aggiunto un nuovo text_20
il nodo viene creato alle root/responsivegrid/text_20
in /content/wknd-spa-react/us/en/home
.
Esistono diversi requisiti per aggiungere componenti foglia virtuali e alcune limitazioni.
pagePath
è obbligatoria per la creazione di un componente virtuale.pagePath
deve esistere nel progetto AEM.itemPath
.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
itemPath
.
root/responsivegrid
deve esistere affinché il nuovo nodo text_20
possono essere create lì.È 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 un contenitore esiste già in /root/responsivegrid
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.
Esistono diversi requisiti per aggiungere contenitori virtuali e alcune limitazioni.
root/responsivegrid
esiste già nel contenitore AEM, è possibile creare un nuovo contenitore fornendo il percorso root/responsivegrid/newContainer
.root/responsivegrid/newContainer/secondNewContainer
non è possibile.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.
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, supponiamo di avere un SPA in cui l’applicazione viene riprodotta all’interno di un div
di ID elemento root
. Questo deve essere riflesso in tre file.
In index.js
dell’applicazione React (o dove ReactDOM.render()
è chiamato)
In index.html
dell’applicazione React
Nel corpo del componente Pagina dell’app AEM, segui questi due passaggi:
body.html
per il componente Pagina.body.html
file.Se l’applicazione esterna React SPA ha più pagine, può utilizzare 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 siamo in mydomain.com/test
, TestPage
verrà eseguito il rendering.
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.
wknd-spa-react/us/en
come radice dell'SPA. Ciò significa che tutto ciò che precede quel percorso sono solo pagine/contenuti AEM.Crea una nuova pagina al livello richiesto.
mydomain.com/test
. test
si trova nel percorso principale dell’app. Questo deve essere mantenuto anche durante la creazione della pagina in AEM. Pertanto, è possibile creare una nuova pagina al livello principale definito nel passaggio precedente.mydomain.com/test
, la nuova pagina creata deve essere /path/to/aem/root/test
.Aggiungere helper all’interno del routing SPA.
/test
considerando che il percorso attivo dell'AEM è /wknd-spa-react/us/en/test
. Per adattarsi alla porzione dell’URL specifica per l’AEM, è necessario aggiungere degli helper sul lato SPA.toAEMPath
helper fornito da @adobe/cq-spa-page-model-manager
può essere utilizzato per questo. 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:
Verifica la modifica della pagina in AEM.
test
pagina. Ora viene eseguito il rendering del contenuto della pagina e i componenti AEM sono modificabili.Il componente RemotePage prevede che l’implementazione fornisca un manifesto delle risorse come quello trovato qui. 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.
I seguenti materiali di riferimento possono essere utili per comprendere l'SPA nel contesto dell'AEM.