SPA Model Routing

May 3, 2023

Topics:
Developing

CREATED FOR:

Developer

CAUTION

AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.

For single page applications in AEM, the app is responsible for the routing. This document describes the routing mechanism, the contract, and options available.

NOTE

The Single-Page Application (SPA) Editor feature requires AEM 6.4 service pack 2 or newer.

The SPA Editor is the recommended solution for projects that require SPA framework based client-side rendering (e.g. React or Angular).

Project Routing

The App owns the routing and is then implemented by the project front end developers. This document describes the routing specific to the model returned by the AEM server. The page model data structure exposes the URL of the underlying resource. The front end project can use any custom or third-party library providing routing functionalities. Once a route expects a fragment of model, a call to the PageModelManager.getData() function can be made. When a model route has changed an event must be triggered to warn listening libraries such as the Page Editor.

Architecture

For a detailed description, please refer to the PageModelManager section of the SPA Blueprint document.

ModelRouter

The ModelRouter - when enabled - encapsulates the HTML5 History API functions pushState and replaceState to guarantee a given fragment of model is pre-fetched and accessible. It then notifies the registered front end component that the model has been modified.

Manual vs Automatic Model Routing

The ModelRouter automates the fetching of fragments of the model. But as any automated tooling it comes with limitations. When needed the ModelRouter can be disabled or configured to ignore paths using meta properties (See the Meta Properties section of the SPA Page Component document). Front end developers can then implement their own model routing layer by requesting the PageModelManager to load any given fragment of model using the getData() function.

NOTE

Currently the We.Retail Journal sample React project illustrates the automated approach while the Angular project illustrates the manual one. A semi-automated approach would also be valid use-case.

CAUTION

The current version of the ModelRouter only support the use of URLs that points to the actual resource path of Sling Model entry points. It doesn’t support the use of Vanity URLs or aliases.

Routing Contract

The current implementation is based on the assumption that the SPA project uses the HTML5 History API for routing to the different application pages.

Configuration

The ModelRouter supports the concept of model routing as it listens for pushState and replaceState calls to prefetch model fragments. Internally it triggers the PageModelManager to load the model that corresponds to a given URL and fires a cq-pagemodel-route-changed event that other modules can listen to.

By default, this behavior is automatically enabled. To disable it, the SPA should render the following meta property:

<meta property="cq:pagemodel_router" content="disable"\>

Note that every route of the SPA should correspond to an accessible resource in AEM (e.g., " /content/mysite/mypage") since the PageModelManager will automatically try to load the corresponding page model once the route is selected. Though, if needed, the SPA can also define a “block list” of routes that should be ignored by the PageModelManager:

<meta property="cq:pagemodel_route_filters" content="route/not/found,^(.*)(?:exclude/path)(.*)"/>

recommendation-more-help