SPA Model Routing spa-model-routing

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

Project Routing 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 architecture

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

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

Routing Contract 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 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)(.*)"/>