Bearbeiten einer externen SPA in Adobe Experience Manager
Erstellt für:
- Entwickler
Wenn Sie entscheiden, welchen Grad der Integration Sie zwischen Ihrer externen SPA und Adobe Experience Manager (AEM) haben möchten, müssen Sie oft die SPA in AEM anzeigen und bearbeiten können.
Übersicht
In diesem Dokument werden die empfohlenen Schritte zum Hochladen einer eigenständigen SPA in eine AEM-Instanz, zum Hinzufügen bearbeitbarer Inhaltsabschnitte und zum Aktivieren des Authoring beschrieben.
Voraussetzungen
Die Voraussetzungen sind einfach.
-
Stellen Sie sicher, dass eine Instanz von AEM lokal ausgeführt wird.
-
Erstellen Sie ein AEM-SPA-Projekt mithilfe des AEM-Projektarchetyps.
- Dies bildet die Grundlage des AEM-Projekts, das aktualisiert wird, um die externe SPA einzubeziehen.
- Die Beispiele in diesem Dokument verwenden als Ausgangspunkt das WKND-SPA-Projekt.
-
Halten Sie die funktionierende, externe React SPA bereit, die Sie integrieren möchten.
Hochladen der SPA in das AEM-Projekt
Zunächst müssen Sie die externe SPA in Ihr AEM-Projekt hochladen.
- Ersetzen Sie
src
im Projektordner/ui.frontend
durch den Ordnersrc
des React-Programms. - Schließen Sie alle weiteren Abhängigkeiten in der Datei
package.json
der App in die Datei/ui.frontend/package.json
ein.- Stellen Sie sicher, dass die SDK-Abhängigkeiten der SPA den empfohlenen Versionen entsprechen.
- Fügen Sie alle Anpassungen in den Ordner
/public
ein. - Fügen Sie alle hinzugefügten Inline-Skripte oder Stile ein die Datei
/public/index.html
ein.
Konfigurieren der Remote-SPA
Da die externe SPA nun Teil Ihres AEM-Projekts ist, muss sie in AEM konfiguriert werden.
Einschließen der Adobe SPA-SDK-Pakete
Um die AEM-SPA-Funktionen nutzen zu können, gibt es Abhängigkeiten von den folgenden drei Paketen.
@adobe/aem-spa-page-model-manager
stellt die API zum Initialisieren eines Modell-Managers und zum Abrufen des Modells aus der AEM-Instanz bereit. Dieses Modell kann dann zum Rendern von AEM-Komponenten mithilfe der APIs von @adobe/aem-react-editable-components
und @adobe/aem-spa-component-mapping
verwendet werden.
Installation
Führen Sie den folgenden npm-Befehl aus, um die erforderlichen Pakete zu installieren.
npm install --save @adobe/aem-spa-component-mapping @adobe/aem-spa-page-model-manager @adobe/aem-react-editable-components
ModelManager-Initialisierung
Bevor die App gerendert wird, muss der ModelManager
initialisiert werden, um die Erstellung des AEM ModelStore
zu verarbeiten.
Dies muss innerhalb der Datei src/index.js
Ihres Programms oder überall dort erfolgen, wo der Stamm des Programms gerendert wird.
Verwenden Sie dazu die initializationAsync
-API, die von ModelManager
bereitgestellt wird.
Der folgende Screenshot zeigt, wie die Initialisierung von ModelManager
in einem einfachen React-Programm aktiviert wird. Die einzige Einschränkung ist, dass initializationAsync
vor ReactDOM.render()
aufgerufen werden muss.
In diesem Beispiel wird ModelManager
initialisiert und ein leerer ModelStore
erstellt.
initializationAsync
kann optional ein options
-Objekt als Parameter akzeptieren:
path
– Bei der Initialisierung wird das Modell vom definierten Pfad abgerufen und imModelStore
gespeichert. Auf diese Weise können Sie bei Bedarf dasrootModel
bei der Initialisierung abrufen.modelClient
- Ermöglicht die Bereitstellung eines benutzerdefinierten Clients, der für das Abrufen des Modells verantwortlich ist.model
- Einmodel
-Objekt, das als Parameter übergeben wird und typischerweise bei der Verwendung von SSR gefüllt wird.
Bearbeitbare AEM-Blattkomponenten
-
Erstellen/identifizieren Sie eine AEM-Komponente, für die eine bearbeitbare React-Komponente erstellt werden soll. In diesem Beispiel verwendet das WKND-Projekt die Textkomponente.
-
Erstellen Sie eine einfache React-Textkomponente in der SPA. In diesem Beispiel wurde eine neue Datei
Text.js
mit folgendem Inhalt erstellt. -
Erstellen Sie ein Konfigurationsobjekt, um die für die Aktivierung der AEM-Bearbeitung erforderlichen Attribute anzugeben.
resourceType
ist zwingend erforderlich, um die React-Komponente der AEM Komponente zuzuordnen und die Bearbeitung beim Öffnen im AEM-Editor zu ermöglichen.
-
Verwenden Sie die Wrapper-Funktion
withMappable
.Diese Wrapper-Funktion ordnet die React-Komponente dem in der Konfiguration angegebenen AEM-
resourceType
zu und aktiviert beim Öffnen im AEM-Editor die Bearbeitungsfunktionen. Bei eigenständigen Komponenten wird auch der Modellinhalt für den jeweiligen Knoten abgerufen.NOTEIn diesem Beispiel gibt es unterschiedliche Versionen der Komponente: in AEM eingeschlossene und nicht eingeschlossene React-Komponenten. Die eingeschlossene Version muss verwendet werden, wenn die Komponente explizit verwendet wird. Wenn die Komponente Teil einer Seite ist, können Sie weiterhin die Standardkomponente verwenden (wie derzeit im SPA-Editor). -
Rendern des Inhalts in der Komponente
Die JCR-Eigenschaften der Textkomponente werden wie folgt in AEM angezeigt.
Diese Werte werden als Eigenschaften an die neu erstellte React-Komponente
AEMText
übergeben und können zum Rendern des Inhalts verwendet werden.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);
So wird die Komponente angezeigt, wenn die AEM-Konfigurationen abgeschlossen sind.
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>); };
NOTEIn diesem Beispiel wurden weitere Anpassungen an der gerenderten Komponente vorgenommen, um sie an die vorhandene Textkomponente anzupassen. Dies hat jedoch nichts mit dem Authoring in AEM zu tun.
Hinzufügen von bearbeitbaren Komponenten zur Seite
Nachdem die bearbeitbaren React-Komponenten erstellt wurden, können sie im gesamten Programm verwendet werden.
Nehmen wir eine Beispielseite, auf der Text aus der WKND-SPA hinzugefügt werden muss. In diesem Beispiel möchten wir den Text „Hello World!“ auf /content/wknd-spa-react/us/en/home.html
anzeigen.
-
Legen Sie den Pfad der anzuzeigenden Knoten fest.
pagePath
: Die Seite, die den Knoten enthält, in dem Beispiel/content/wknd-spa-react/us/en/home
itemPath
: Pfad zum Knoten innerhalb der Seite, in dem Beispielroot/responsivegrid/text
- Dieser besteht aus den Namen der enthaltenen Elemente auf der Seite.
-
Fügen Sie die Komponente an gewünschter Position in die Seite ein.
Die
AEMText
-Komponente kann an der gewünschten Position in die Seite eingefügt werden, wobei die WertepagePath
unditemPath
als Eigenschaften festgelegt sind.pagePath
ist eine obligatorische Eigenschaft.
Überprüfen der Bearbeitung von Textinhalten in AEM
Testen Sie nun die Komponente in der aktuell ausgeführten AEM-Instanz.
- Führen Sie den folgenden Maven-Befehl aus dem Verzeichnis
aem-guides-wknd-spa
aus, um das Projekt zu erstellen und in AEM bereitzustellen.
mvn clean install -PautoInstallSinglePackage
- Navigieren Sie in Ihrer AEM-Instanz zu
http://<host>:<port>/editor.html/content/wknd-spa-react/us/en/home.html
.
Die AEMText
-Komponente kann jetzt in AEM bearbeitet werden.
In AEM bearbeitbare Seiten
-
Identifizieren Sie eine Seite, die zur Bearbeitung in der SPA hinzugefügt werden soll. In diesem Beispiel wird
/content/wknd-spa-react/us/en/home.html
verwendet. -
Erstellen Sie eine neue Datei (z. B.
Page.js
) für die bearbeitbare Seitenkomponente. Hier kann die Seitenkomponente wiederverwendet werden, die in@adobe/cq-react-editable-components
bereitgestellt wird. -
Wiederholen Sie Schritt 4 im Abschnitt Bearbeitbare AEM-Blattkomponenten. Verwenden Sie die Wrapper-Funktion
withMappable
für die Komponente. -
Wenden Sie wie zuvor
MapTo
auf die AEM-Ressourcentypen für alle untergeordneten Komponenten in der Seite an.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);
NOTEIn diesem Beispiel wird die nicht umhüllte React-Textkomponente anstelle des zuvor erstellten umhülltenAEMText
verwendet. Das liegt daran, dass, wenn die Komponente Teil einer Seite/eines Containers und nicht eigenständig ist, der Container sich um die rekursive Zuordnung der Komponente und die Aktivierung der Authoring-Funktionen kümmert und der zusätzliche Wrapper nicht für jedes untergeordnete Element benötigt wird. -
Um eine bearbeitbare Seite in der SPA hinzuzufügen, folgen Sie denselben Schritten wie im Abschnitt Hinzufügen von bearbeitbaren Komponenten zur Seite. Hier können wir die
itemPath
-Eigenschaft jedoch überspringen.
Überprüfen des Seiteninhalts in AEM
Um zu überprüfen, ob die Seite bearbeitet werden kann, folgen Sie denselben Schritten im Abschnitt Überprüfen der Bearbeitung von Textinhalten in AEM.
Die Seite ist nun in AEM mit einem Layout-Container und einer untergeordneten Textkomponente bearbeitbar.
Virtuelle Blattkomponenten
In den vorherigen Beispielen haben wir der SPA Komponenten mit vorhandenen AEM-Inhalten hinzugefügt. Es gibt jedoch Fälle, in denen der Inhalt noch nicht in AEM erstellt wurde, der jedoch später vom Inhaltsautor hinzugefügt werden muss. Um dies zu ermöglichen, kann der Frontend-Entwickler Komponenten an den entsprechenden Stellen in der SPA hinzufügen. Diese Komponenten zeigen Platzhalter an, wenn sie im Editor in AEM geöffnet werden. Sobald der Inhalt innerhalb dieser Platzhalter vom Inhaltsautor hinzugefügt wurde, werden Knoten in der JCR-Struktur erstellt und der Inhalt bleibt erhalten. Die erstellte Komponente ermöglicht dieselben Vorgänge wie die eigenständigen Blattkomponenten.
In diesem Beispiel verwenden wir die zuvor erstellte AEMText
-Komponente erneut. Wir möchten auf der WKND-Startseite einen neuen Text unterhalb der bestehenden Textkomponente hinzufügen. Das Hinzufügen von Komponenten ist dasselbe wie bei normalen Blattkomponenten. itemPath
kann jedoch auf den Pfad aktualisiert werden, in dem die neue Komponente hinzugefügt werden muss.
Da die neue Komponente unter dem vorhandenen Text unter root/responsivegrid/text
hinzugefügt werden muss, lautet der neue Pfad root/responsivegrid/{itemName}
.
<AEMText
pagePath='/content/wknd-spa-react/us/en/home'
itemPath='root/responsivegrid/text_20' />
Die Komponente TestPage
sieht nach dem Hinzufügen der virtuellen Komponente wie folgt aus.
AEMText
in der Konfiguration ihre resourceType
-Eigenschaft eingestellt hat, um diese Funktion zu aktivieren.Sie können jetzt die Änderungen an AEM entsprechend den Schritten im Abschnitt Überprüfen der Bearbeitung von Textinhalten in AEM bereitstellen. Für den derzeit nicht vorhandenen text_20
-Knoten wird ein Platzhalter angezeigt.
Wenn der Inhaltsautor diese Komponente aktualisiert, wird unter root/responsivegrid/text_20
in /content/wknd-spa-react/us/en/home
ein neuer text_20
-Knoten erstellt.
Anforderungen und Einschränkungen
Es gibt mehrere Anforderungen, um virtuelle Blattkomponenten hinzuzufügen, und einige Einschränkungen.
- Die
pagePath
-Eigenschaft ist zum Erstellen einer virtuellen Komponente obligatorisch. - Der im Pfad in
pagePath
angegebene Seitenknoten muss im AEM-Projekt vorhanden sein. - Der Name des zu erstellenden Knotens muss im
itemPath
angegeben werden. - Die Komponente kann auf jeder Ebene erstellt werden.
- Wenn wir im vorherigen Beispiel
itemPath='text_20'
angeben, wird der neue Knoten direkt unter der Seite/content/wknd-spa-react/us/en/home/jcr:content/text_20
erstellt.
- Wenn wir im vorherigen Beispiel
- Der Pfad zum Knoten, in dem ein neuer Knoten erstellt wird, muss gültig sein, wenn er über
itemPath
bereitgestellt wird.- In diesem Beispiel muss
root/responsivegrid
vorhanden sein, damit der neue Knotentext_20
dort erstellt werden kann.
- In diesem Beispiel muss
- Es wird nur die Erstellung von Blattkomponenten unterstützt. Virtuelle Container und Seiten werden in zukünftigen Versionen unterstützt.
Virtuelle Container
Die Möglichkeit, Container hinzuzufügen, auch wenn der entsprechende Container noch nicht in AEM erstellt wurde, wird unterstützt. Konzept und Ansatz ähneln den virtuellen Blattkomponenten.
Frontend-Entwicklerinnen und -Entwickler können die Container-Komponenten an geeigneten Stellen innerhalb des SPA hinzufügen. Diese Komponenten zeigen Platzhalter an, wenn sie im Editor in AEM geöffnet werden. Autorinnen und Autoren können dann Komponenten und deren Inhalt zum Container hinzufügen, wodurch die erforderlichen Knoten in der JCR-Struktur erstellt werden.
Wenn beispielsweise ein Container bereits unter /root/responsivegrid
vorhanden ist und die Entwicklerinnen und Entwickler einen neuen untergeordneten Container hinzufügen möchten:
newContainer
existiert noch nicht in AEM.
Wenn Sie in AEM die Seite bearbeiten, die diese Komponente enthält, wird ein leerer Platzhalter für einen Container angezeigt, dem Autorinnen und Autoren Inhalte hinzufügen können.
Sobald der Autor dem Container eine untergeordnete Komponente hinzufügt, wird der neue Container-Knoten mit dem entsprechenden Namen in der JCR-Struktur angelegt.
Je nach Bedarf der Autorin bzw. des Autors können nun weitere Komponenten und Inhalte in den Container eingefügt werden, und die Änderungen werden beibehalten.
Anforderungen und Einschränkungen
Es gibt verschiedene Anforderungen, um virtuelle Container hinzuzufügen, und einige Einschränkungen.
-
Die Richtlinie, die bestimmt, welche Komponenten hinzugefügt werden können, wird vom übergeordneten Container übernommen.
-
Das unmittelbar übergeordnete Element des zu erstellenden Containers muss bereits in AEM vorhanden sein.
- Wenn der Container
root/responsivegrid
bereits im AEM-Container vorhanden ist, kann ein neuer Container durch Angabe des Pfadsroot/responsivegrid/newContainer
erstellt werden. root/responsivegrid/newContainer/secondNewContainer
ist jedoch nicht möglich.
- Wenn der Container
-
Es kann jeweils nur eine neue Komponentenebene virtuell erstellt werden.
Zusätzliche Anpassungen
Wenn Sie den vorherigen Beispielen gefolgt sind, kann Ihre externe SPA jetzt in AEM bearbeitet werden. Es gibt jedoch zusätzliche Aspekte Ihrer externen SPA, die Sie weiter anpassen können.
Stammknoten-ID
Standardmäßig wird davon ausgegangen, dass das React-Programm innerhalb einer div
der Element-ID spa-root
gerendert wird. Falls erforderlich, kann dies angepasst werden.
Nehmen wir beispielsweise an, wir haben eine SPA, in der das Programm innerhalb einer div
der Element-ID root
gerendert wird. Dies muss in drei Dateien widergespiegelt werden.
-
Im
index.js
der React-Programm (oder woReactDOM.render()
aufgerufen wird) -
In der
index.html
des React-Programms -
Führen Sie im Hauptteil der Seitenkomponente der AEM-App zwei Schritte aus:
- Erstellen Sie eine
body.html
für die Seitenkomponente.
- Fügen Sie das neue Stammelement in der neuen
body.html
-Datei hinzu.
- Erstellen Sie eine
Bearbeiten einer React-SPA mit Routing
Wenn das externe React-SPA-Programm über mehrere Seiten verfügt, kann sie mithilfe von Routing die zu rendernde Seite/Komponente bestimmen. Der grundlegende Anwendungsfall ist der Abgleich der aktuell aktiven URL mit dem für eine Route bereitgestellten Pfad. Um die Bearbeitung in solchen Routing-fähigen Programmen zu ermöglichen, muss der Pfad, gegen den abgeglichen werden soll, transformiert werden, damit AEM-spezifische Informationen aufgenommen werden können.
Im folgenden Beispiel haben wir ein einfaches React-Programm mit zwei Seiten. Die Seite, die gerendert werden soll, wird durch den Abgleich des an den Router übergebenen Pfads mit der aktiven URL bestimmt. Wenn wir uns zum Beispiel auf mydomain.com/test
befinden, wird TestPage
gerendert.
Um die Bearbeitung in AEM für diese Beispiel-SPA zu aktivieren, sind die folgenden Schritte erforderlich.
-
Identifizieren Sie die Ebene, die als Stamm in AEM fungieren würde.
- In unserem Beispiel ist
wknd-spa-react/us/en
der Stamm der SPA. Das bedeutet, dass alles vor diesem Pfad nur AEM-Seiten/-Inhalte sind.
- In unserem Beispiel ist
-
Erstellen Sie eine neue Seite auf der erforderlichen Ebene.
- In diesem Beispiel lautet die zu bearbeitende Seite
mydomain.com/test
.test
befindet sich im Stammpfad der App. Dies muss auch beim Erstellen der Seite in AEM beibehalten werden. Daher können Sie eine neue Seite auf der im vorherigen Schritt definierten Stammebene erstellen. - Die neu erstellte Seite muss denselben Namen haben wie die zu bearbeitende Seite. In diesem Beispiel für
mydomain.com/test
muss die neue Seite/path/to/aem/root/test
heißen.
- In diesem Beispiel lautet die zu bearbeitende Seite
-
Fügen Sie Helfer innerhalb des SPA-Routings hinzu.
- Die neu erstellte Seite wird noch nicht den erwarteten Inhalt in AEM wiedergeben. Dies liegt daran, dass der Router den Pfad
/test
erwartet, während der aktive Pfad in AEM/wknd-spa-react/us/en/test
ist. Um den AEM-spezifischen Teil der URL aufzunehmen, müssen wir einige Helfer auf der SPA Seite hinzufügen.
-
Hierfür kann der
toAEMPath
-Helfer verwendet werden, der von@adobe/cq-spa-page-model-manager
bereitgestellt wird. Er wandelt den für das Routing bereitgestellten Pfad so um, dass er AEM-spezifische Teile enthält, wenn das Programm auf einer AEM-Instanz geöffnet ist. Es werden drei Parameter akzeptiert:- Der für das Routing erforderliche Pfad
- Die ursprüngliche URL der AEM-Instanz, in der die SPA bearbeitet wird
- Das Projektstammverzeichnis in AEM, wie im ersten Schritt festgelegt
-
Diese Werte können für mehr Flexibilität als Umgebungsvariablen festgelegt werden.
- Die neu erstellte Seite wird noch nicht den erwarteten Inhalt in AEM wiedergeben. Dies liegt daran, dass der Router den Pfad
-
Überprüfen Sie die Bearbeitung der Seite in AEM.
- Stellen Sie das Projekt in AEM bereit und navigieren Sie zur neu erstellten
test
-Seite. Der Seiteninhalt wird jetzt gerendert und die AEM-Komponenten können bearbeitet werden.
- Stellen Sie das Projekt in AEM bereit und navigieren Sie zur neu erstellten
Framework-Einschränkungen
Die RemotePage-Komponente erwartet, dass die Implementierung ein Asset-Manifest wie das webpack-manifest-plugin auf GitHub bereitstellt. Die RemotePage-Komponente wurde jedoch nur für die Zusammenarbeit mit dem React-Framework (und Next.js über die Komponente „remote-page-next“) getestet und unterstützt daher nicht das Fernladen von Anwendungen aus anderen Frameworks, wie z. B. Angular.
Zusätzliche Ressourcen
Das folgende Referenzmaterial kann hilfreich sein, um SPAs im Kontext der AEM zu verstehen.