Modifica di un’applicazione a pagina singola esterna all’interno di Adobe Experience Manager editing-external-spa-within-aem

Last update: Tue Jun 17 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Si applica a:
Experience Manager 6.5 LTS

Argomenti:

Creato per:

Sviluppatore

Quando decidi quale livello di integrazione desideri avere tra l’applicazione a pagina singola esterna e Adobe Experience Manager (AEM), spesso devi essere in grado di modificare e visualizzare l’applicazione a pagina singola in AEM.

Panoramica overview

Questo documento descrive i passaggi consigliati per caricare un’applicazione a pagina singola indipendente in un’istanza di AEM, aggiungere sezioni di contenuto modificabili e abilitare l’authoring.

IMPORTANT

L’editor SPA è obsoleto per i nuovi progetti. Continua a essere supportato da Adobe per i progetti esistenti, ma non dovrebbe essere utilizzato per i nuovi progetti. Gli editor preferiti per la gestione dei contenuti headless in AEM sono ora i seguenti:

Editor universale per la modifica visiva di contenuti headless.
Editor frammenti di contenuto per la modifica di contenuti headless basata su modulo.

Prerequisiti prerequisites

I prerequisiti sono semplici.

Assicurati che un’istanza di AEM sia in esecuzione localmente.
Creare un progetto SPA di base di AEM utilizzando l'archetipo del progetto AEM.
- Questo costituisce la base del progetto AEM che verrà aggiornato per includere l’applicazione a pagina singola esterna.
- Gli esempi in questo documento utilizzano il punto di partenza del progetto SPA WKND.
Avrai a portata di mano l’applicazione a pagina singola React funzionante ed esterna che desideri integrare.

Carica applicazione a pagina singola in un progetto AEM upload-spa-to-aem-project

Innanzitutto, devi caricare l’applicazione a pagina singola esterna nel progetto AEM.

Sostituisci src nella cartella dei progetti /ui.frontend con la cartella src dell'applicazione React.
Includere eventuali dipendenze aggiuntive nel file /ui.frontend/package.json dell'app package.json.
- Verificare che le dipendenze di SPA SDK 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’applicazione a pagina singola remota configure-remote-spa

Ora che l’applicazione a pagina singola esterna fa parte del progetto AEM, deve essere configurata all’interno di AEM.

Includi pacchetti SDK SPA di Adobe include-spa-sdk-packages

Per sfruttare le funzioni di AEM SPA, esistono dipendenze dai tre pacchetti seguenti.

@adobe/aem-spa-page-model-manager fornisce l'API per inizializzare Model Manager e recuperare il modello dall'istanza di 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().

Inizializza ModelManager

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 in ModelStore. Può essere utilizzato per recuperare rootModel all'inizializzazione, se necessario.
modelClient - Consente di fornire un client personalizzato responsabile del recupero del modello.
model - Un oggetto model passato come parametro viene generalmente popolato quando si utilizza SSR.

Componenti foglia compatibili con AEM authorable-leaf-components

Crea/identifica un componente AEM per il quale verrà creato un componente React personalizzabile. In questo esempio, il progetto WKND utilizza il componente testo.
Crea un componente di testo React semplice nell’applicazione a pagina singola. 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 quando si apre nell'editor di AEM.

Utilizzare la funzione wrapper withMappable.

Usa conMappable

Questa funzione wrapper mappa il componente React all'AEM resourceType specificato nella configurazione e abilita le funzionalità di modifica quando viene aperto nell'editor di 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 racchiusi e non racchiusi (unwrapped) in React. 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 di applicazioni a pagina singola.

Esegui il rendering del contenuto nel componente.

In AEM, le proprietà JCR del componente testo vengono visualizzate come segue.

Proprietà componente testo

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

code language-javascript

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

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 quando le configurazioni di AEM sono completate.

code language-javascript

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

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. Tuttavia, questo 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 il testo del progetto SPA WKND. 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'esempio root/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 valori pagePath e itemPath 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 di AEM in esecuzione.

Eseguire il seguente comando Maven dalla directory aem-guides-wknd-spa per generare e distribuire il progetto in AEM.

mvn clean install -PautoInstallSinglePackage

Nell'istanza di AEM, passa a http://<host>:<port>/editor.html/content/wknd-spa-react/us/en/home.html.

Modifica dellapplicazione a pagina singola in AEM

Il componente AEMText è ora modificabile in AEM.

Pagine AEM Authorable aem-authorable-pages

Identifica una pagina da aggiungere per l’authoring nell’applicazione a pagina singola. 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.
Ripeti il passaggio quattro nella sezione Componenti foglia 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.

code language-javascript

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

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'applicazione a pagina singola, seguire gli stessi passaggi della sezione Aggiungere componenti modificabili alla pagina. In questo caso, tuttavia, è possibile ignorare la proprietà itemPath.

Verificare il contenuto della 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 in AEM.

Modifica di una pagina in AEM

La pagina è ora modificabile in AEM con un contenitore di layout e un componente testo figlio.

Componenti foglia virtuale virtual-leaf-components

Negli esempi precedenti, abbiamo aggiunto componenti all’applicazione a pagina singola con contenuto AEM esistente. Tuttavia, in alcuni casi il contenuto non è ancora stato creato in AEM, ma deve essere aggiunto successivamente dall’autore del contenuto. Per soddisfare questa esigenza, lo sviluppatore front-end può aggiungere componenti nelle posizioni appropriate all’interno dell’applicazione a pagina singola. 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.

Verifica del componente virtuale

NOTE

Assicurarsi che il componente AEMText abbia impostato resourceType nella configurazione per abilitare questa funzione.

È ora possibile distribuire le modifiche ad AEM seguendo i passaggi descritti nella sezione Verifica modifica del contenuto di testo in AEM. Viene visualizzato un segnaposto per il nodo text_20 attualmente non esistente.

Nodo text_20 in aem

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.

Nodo text20

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
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 nodo text_20 possa essere creato lì.
È 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’applicazione a pagina singola e tali componenti visualizzeranno dei segnaposto quando vengono aperti nell’editor in 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:

Percorso contenitore

newContainer non esiste ancora in 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.

Segnaposto contenitore

Percorso contenitore in JCR

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.

Contenitore con contenuto

Contenitore con contenuto in 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 principale immediato 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 percorso root/responsivegrid/newContainer.
- Tuttavia root/responsivegrid/newContainer/secondNewContainer non è possibile.
È possibile creare un solo nuovo livello di componente alla volta.

Personalizzazioni aggiuntive additional-customizations

Se hai seguito gli esempi precedenti, l’applicazione a pagina singola esterna ora è modificabile in AEM. Tuttavia, puoi personalizzare ulteriormente alcuni aspetti aggiuntivi dell’applicazione a pagina singola esterna.

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'applicazione a pagina singola 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 chiamato ReactDOM.render())
In index.html dell'applicazione React
Nel corpo del componente Pagina dell’app AEM, segui questi due passaggi:
1. Crea un body.html per il componente pagina.
1. Aggiungere il nuovo elemento radice nel nuovo file body.html.

Modifica di un’applicazione a pagina singola React con routing editing-react-spa-with-routing

Se l'applicazione SPA React esterna 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 abilitare la modifica nelle applicazioni abilitate per l’instradamento, il percorso da confrontare deve essere trasformato per adattarsi alle informazioni specifiche di 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.

Indirizzamento in unapplicazione a pagina singola esterna

Per abilitare la modifica in AEM per questa applicazione a pagina singola di esempio, sono necessari i seguenti passaggi.

Identifica il livello che fungerebbe da root su AEM.
- Per il nostro esempio, consideriamo wknd-spa-react/us/en come radice dell'applicazione a pagina singola. Ciò significa che tutto ciò che precede quel percorso è costituito solo da pagine/contenuti AEM.
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.
Aggiungi 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 di AEM è /wknd-spa-react/us/en/test. Per includere la porzione dell’URL specifica per AEM, è necessario aggiungere alcuni 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 di AEM quando l’applicazione è aperta su un’istanza di AEM. Accetta tre parametri:
  - Percorso necessario per il routing
  - URL di origine dell’istanza di AEM in cui viene modificata l’applicazione a pagina singola
  - Directory principale del progetto su AEM come determinato nel primo passaggio
- Questi valori possono essere impostati come variabili di ambiente per maggiore flessibilità.
Verifica la modifica della pagina in AEM.
- Distribuire il progetto in AEM e passare alla pagina test appena creata. Ora è stato eseguito il rendering del contenuto della pagina e i componenti AEM sono modificabili.

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 Angular.

Risorse aggiuntive additional-resources

Il seguente materiale di riferimento può essere utile per comprendere le applicazioni a pagina singola nel contesto di AEM.

recommendation-more-help

51c6a92d-a39d-46d7-8e3e-2db9a31c06a2