Lorsque vous décidez du niveau d’intégration à appliquer entre votre SPA externe et AEM, pensez que vous aurez souvent à modifier et à afficher la SPA dans AEM.
Ce document décrit les étapes recommandées pour charger une SPA autonome vers une instance AEM, ajouter des sections de contenu modifiables et permettre la création.
Les conditions préalables sont simples.
Vous devez tout d’abord charger la SPA externe vers votre projet AEM.
src
dans le dossier de projet /ui.frontend
par le dossier src
de votre application React.package.json
de l’application dans le fichier /ui.frontend/package.json
.
/public
./public/index.html
.Maintenant que la SPA externe fait partie de votre projet AEM, vous devez la configurer dans AEM.
Pour tirer parti des fonctionnalités de SPA AEM, vous pouvez utiliser les dépendances des trois packages suivants.
@adobe/aem-react-editable-components
@adobe/aem-spa-component-mapping
@adobe/aem-spa-page-model-manager
Le package @adobe/aem-spa-page-model-manager
fournit l’API permettant d’initialiser un gestionnaire de modèle et de récupérer le modèle à partir de l’instance AEM. Ce modèle peut ensuite être utilisé pour effectuer le rendu des composants AEM à l’aide d’API provenant de @adobe/aem-react-editable-components
et @adobe/aem-spa-component-mapping
.
Exécutez la commande npm
suivante pour pouvoir installer les packages requis.
npm install --save @adobe/aem-spa-component-mapping @adobe/aem-spa-page-model-manager @adobe/aem-react-editable-components
Avant le rendu de l’application, ModelManager
doit être initialisé pour gérer la création du ModelStore
AEM.
Cette initialisation doit être effectuée dans le fichier src/index.js
de votre application ou à l’endroit où la racine de l’application est générée.
Pour effectuer cette initialisation, vous pouvez utiliser l’API initializationAsync
fournie par le ModelManager
.
La capture d’écran suivante montre comment activer l’initialisation de ModelManager
dans une application React simple. La seule contrainte est que initializationAsync
doit être appelée avant ReactDOM.render()
.
Dans cet exemple, ModelManager
est initialisé et un ModelStore
vide est créé.
initializationAsync
peut éventuellement accepter un objet options
comme paramètre :
path
– Lors de l’initialisation, le modèle au niveau du chemin d’accès défini est récupéré et stocké dans le ModelStore
. Ce chemin peut être utilisé pour récupérer le rootModel
à l’initialisation, le cas échéant.modelClient
– Permet de fournir un client personnalisé chargé de récupérer le modèle.model
– Un objet model
transmis en tant que paramètre généralement renseigné lors de l’utilisation de SSR.Créez/identifiez un composant AEM pour lequel un composant React modifiable est créé. Dans cet exemple il utilise le composant texte du projet WKND.
Créez un simple composant texte React dans la SPA. Dans cet exemple, un nouveau fichier Text.js
a été créé avec le contenu suivant.
Créez un objet de configuration pour spécifier les attributs requis pour activer la modification AEM.
resourceType
est nécessaire pour pouvoir mapper le composant React au composant AEM et activer la modification lors de l’ouverture dans l’éditeur AEM.Utilisez la fonction Wrapper withMappable
.
Cette fonction Wrapper mappe le composant React au resourceType
AEM spécifié dans la configuration et active les capacités de modification en l’ouvrant dans l’éditeur AEM. Pour les composants autonomes, cette fonction récupère également le contenu du modèle pour le nœud spécifique.
Dans cet exemple, il existe des versions distinctes du composant : les composants AEM encapsulés et les composants React non encapsulés. La version encapsulée doit être utilisée lors de l’utilisation explicite du composant. Lorsque le composant fait partie d’une page, vous pouvez continuer à utiliser le composant par défaut comme dans l’éditeur de SPA.
Générez le contenu dans le composant.
Les propriétés JCR du composant texte apparaissent comme suit dans AEM.
Ces valeurs sont transmises en tant que propriétés à la propriété créée. AEMText
React et peut être utilisé pour effectuer le rendu du contenu.
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);
C’est ainsi que le composant apparaît une fois que les configurations AEM sont terminées.
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>);
};
Dans cet exemple, d’autres personnalisations ont été apportées au composant rendu pour correspondre au composant de texte existant. Cette personnalisation n’est toutefois pas liée à la création dans AEM.
Une fois les composants React modifiables créés, vous pouvez les utiliser dans toute l’application.
Prenons un exemple de page dans lequel vous devez ajouter un texte du projet SPA WKND. Pour cet exemple, vous voulez afficher le texte « Hello World! » à /content/wknd-spa-react/us/en/home.html
.
Déterminez le chemin d’accès du nœud à afficher.
pagePath
: page qui contient le nœud, dans cet exemple, /content/wknd-spa-react/us/en/home
itemPath
: chemin d’accès au nœud dans la page, dans cet exemple, root/responsivegrid/text
Ajoutez le composant à la position requise sur la page.
Le composant AEMText
peut être ajouté à la position requise sur la page avec les valeurs pagePath
et itemPath
définies en tant que propriétés. pagePath
est une propriété obligatoire.
Testez maintenant le composant sur l’instance AEM en cours d’exécution.
aem-guides-wknd-spa
pour générer et déployer le projet sur AEM.mvn clean install -PautoInstallSinglePackage
http://<host>:<port>/editor.html/content/wknd-spa-react/us/en/home.html
.Le composant AEMText
est désormais modifiable sur AEM.
Identifiez une page à ajouter pour la création dans la SPA. Cet exemple utilise /content/wknd-spa-react/us/en/home.html
.
Créez un fichier (par exemple, Page.js
) pour le composant de page modifiable. Utilisez le composant de page fourni dans @adobe/cq-react-editable-components
.
Répétez l’étape 4 de la section Composants feuille AEM modifiables. Utilisez la fonction Wrapper withMappable
sur le composant.
Comme précédemment, appliquez MapTo
aux types de ressources AEM pour tous les composants enfants de la page.
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);
Dans cet exemple, le composant de texte React non encapsulé est utilisé à la place de l’élément encapsulé AEMText
créé précédemment. En effet, lorsque le composant fait partie d’une page/d’un conteneur et qu’il n’est pas autonome, le conteneur s’occupe de mapper récursivement le composant. De plus, l’activation des fonctionnalités de création et du wrapper supplémentaire n’est pas nécessaire pour chaque enfant.
Pour ajouter une page autorisée dans la SPA, suivez les mêmes étapes de la section Ajout de composants modifiables à la page. Ici, vous pouvez ignorer la propriété itemPath
.
Pour vérifier que la page peut être modifiée, suivez les mêmes étapes que dans la section Vérification de la modification du contenu texte dans AEM.
La page est désormais modifiable dans AEM avec un conteneur de disposition et un composant texte enfant.
Dans les exemples précédents, vous avez ajouté des composants à la SPA avec le contenu AEM existant. Toutefois, il arrive que le contenu n’ait pas encore été créé dans AEM, mais qu’il doive être ajouté ultérieurement par l’auteur ou l’autrice du contenu. Pour ce faire, dans ce scénario, l’équipe de développement front-end peut ajouter des composants aux emplacements appropriés dans la SPA. Ces composants affichent des espaces réservés lorsqu’ils sont ouverts dans l’éditeur dans AEM. Une fois que le contenu est ajouté par l’auteur ou l’autrice du contenu dans ces espaces réservés, les nœuds sont créés dans la structure JCR et le contenu est conservé. Le composant créé permet le même ensemble d’opérations que les composants feuille autonomes.
Dans cet exemple, vous réutilisez le composant AEMText
créé précédemment. Vous devez ajouter un nouveau texte sous le composant texte existant sur la page d’accueil WKND. L’ajout de composants est le même que pour les composants feuille normaux. Cependant, itemPath
peut être mis à jour avec le chemin d’accès pour le nouveau composant.
Étant donné que le nouveau composant doit être ajouté sous le texte existant à l’adresse root/responsivegrid/text
, le nouveau chemin est root/responsivegrid/{itemName}
.
<AEMText
pagePath='/content/wknd-spa-react/us/en/home'
itemPath='root/responsivegrid/text_20' />
Le composant TestPage
ressemble à ce qui suit après l’ajout du composant virtuel.
Assurez-vous que le composant AEMText
a son resourceType
défini dans la configuration pour activer cette fonctionnalité.
Vous pouvez maintenant déployer les modifications sur AEM en suivant les étapes de la section Vérification de la modification du contenu texte dans AEM. Un espace réservé s’affiche pour le nœud text_20
encore non existant.
Lorsque l’auteur du contenu met à jour ce composant, un nœud text_20
est créé sur root/responsivegrid/text_20
dans /content/wknd-spa-react/us/en/home
.
Il existe plusieurs exigences pour ajouter des composants feuille virtuels et certaines limites.
pagePath
est obligatoire pour créer un composant virtuel.pagePath
doit exister dans le projet AEM.itemPath
.itemPath='text_20'
dans l’exemple précédent, le nœud est créé directement sous la page, à savoir /content/wknd-spa-react/us/en/home/jcr:content/text_20
itemPath
.
root/responsivegrid
doit exister pour que le nœud text_20
puisse y être créé.La possibilité d’ajouter des conteneurs, même si le conteneur correspondant n’est pas encore créé dans AEM, est prise en charge. Le concept et l’approche sont semblables à celles des composants feuille virtuels.
L’équipe de développement front-end peut ajouter les composants de conteneur aux emplacements appropriés dans la SPA. Ces composants affichent des espaces réservés lorsqu’ils sont ouverts dans l’éditeur dans AEM. L’auteur ou l’autrice peut ensuite ajouter des composants et leur contenu au conteneur, ce qui crée les nœuds requis dans la structure JCR.
Par exemple, si un conteneur existe déjà à l’adresse /root/responsivegrid
et que l’équipe de développement souhaite ajouter un nouveau conteneur enfant :
newContainer
n’existe pas encore dans AEM.
Lors de la modification de la page contenant ce composant dans AEM, un espace réservé vide pour un conteneur s’affiche dans lequel l’auteur peut ajouter du contenu.
Une fois que l’auteur ajoute un composant enfant au conteneur, le nouveau nœud de conteneur est créé avec le nom correspondant dans la structure JCR.
Vous pouvez désormais ajouter plus de composants et de contenu au conteneur en fonction des besoins de l’auteur pu l’autrice, et les modifications sont conservées.
Il existe plusieurs exigences pour ajouter des conteneurs virtuels et certaines limites.
root/responsivegrid
existe dans le conteneur AEM, un nouveau conteneur peut être créé en indiquant le chemin d’accès root/responsivegrid/newContainer
.root/responsivegrid/newContainer/secondNewContainer
n’est pas possible.Si vous avez suivi les exemples précédents, votre SPA externe est désormais modifiable dans AEM. Cependant, vous pouvez personnaliser encore davantage d’autres aspects de votre SPA externe.
Par défaut, vous pouvez supposer que l’application React est rendue dans un div
de l’ID d’élément spa-root
. Au besoin, cette syntaxe peut être personnalisée.
Par exemple, supposons que vous ayez une SPA dans laquelle l’application est rendue dans un div
de l’ID d’élément root
. Cette syntaxe doit se refléter dans trois fichiers.
Dans le fichier index.js
de l’application React (ou à l’endroit où ReactDOM.render()
est appelé)
Dans le fichier index.html
de l’application React
Dans le corps du composant de page de l’application AEM, opération possible en deux étapes :
body.html
pour le composant de page.body.html
.Si l’application SPA React externe comporte plusieurs pages, elle peut utiliser le routage pour déterminer la page ou le composant à rendre. Le cas d’utilisation typique consiste à faire correspondre l’URL actuellement principale au chemin d’accès fourni pour un itinéraire. Pour permettre la modification sur de telles applications activées pour le routage, le chemin d’accès à comparer doit être modifié pour pouvoir s’adapter aux informations spécifiques à AEM.
Dans l’exemple suivant, vous avez une application React simple de deux pages. La page à rendre est déterminée en comparant le chemin d’accès fourni au routeur avec l’URL active. Par exemple, si vous utilisez mydomain.com/test
, TestPage
est rendue.
Pour activer la modification dans AEM pour cet exemple de SPA, vous devez suivre les étapes suivantes.
Identifiez le niveau racine pour AEM.
Créez une page au niveau requis.
mydomain.com/test
. test
se trouve dans le chemin racine de l’application. Ce chemin racine doit également être conservé lors de la création de la page dans AEM. Par conséquent, vous pouvez créer une page au niveau racine défini à l’étape précédente.mydomain.com/test
, la page créée doit être /path/to/aem/root/test
.Ajoutez des assistants pour le routage de la SPA.
/test
alors que le chemin d’accès actif d’AEM est /wknd-spa-react/us/en/test
. Pour prendre en compte la partie spécifique à AEM de l’URL, vous devez ajouter des fonctions d’aide côté SPA.L’assistant toAEMPath
fourni par @adobe/cq-spa-page-model-manager
peut être utilisé. Elle adapte le chemin d’accès fourni pour que le routage intègre les portions spécifiques à AEM lorsque l’application est ouverte sur une instance AEM. Elle accepte trois paramètres :
Ces valeurs peuvent être définies en tant que variables d’environnement pour plus de flexibilité.
Vérifiez la modification de la page dans AEM.
test
page. Le contenu de la page est désormais rendu et les composants AEM sont modifiables.Le composant RemotePage s’attend à ce que l’implémentation fournisse un manifeste de ressource comme celui-ci. Le composant RemotePage, en revanche, a été testé uniquement pour fonctionner avec le framework React (et Next.js via le composant remote-page-next) et il ne prend donc pas en charge le chargement à distance d’applications à partir d’autres frameworks tels qu’Angular.
Les documents de référence suivants peuvent être utiles pour comprendre le fonctionnement des SPA dans le contexte d’AEM.