SPA templating API

SPA template annotations endpoint

Magnolia SPA template annotations make content from a front-end project editable in Magnolia. This is achieved by injecting annotations (HTML comments) around components which the Magnolia Page editor transforms into controls for web content editors.

Annotations are created on the server and can be retrieved through a dedicated Template annotation endpoint. The advantage is the server renders everything from the attributes. Before, the annotations were created in Magnolia frontend helpers.

Version 6.2.17 of the Pages module also introduced the site-aware template annotations endpoint (info.magnolia.rendering.spa.rest.v1.SiteAwareTemplateAnnotationEndpoint), which is aware of site-defined prototype templates.

Retrieving annotations

The example below shows how you can retrieve template annotations for the Two columns page in the angular-lm light module. The light module is part of our angular-sample demonstration Angular application.

The endpoint path as well as the other environment parameters are configured in the .env configuration file:

NG_APP_MGNL_HOST=http://localhost:8080

NG_APP_MGNL_CONTEXT_PATH=/magnoliaAuthor

NG_APP_MGNL_API_TEMPLATES=/.rest/template-annotations/v1
NG_APP_MGNL_API_PAGES=/.rest/delivery/pages/v1
NG_APP_MGNL_STATIC=/.resources/angular-lm/webresources/dist

Template annotations for the page can be retrieved through the following URL:

http://localhost:8080/magnoliaAuthor/.rest/template-annotations/v1/angular-sample/two-columns

Page content for single-page applications is delivered through the Delivery API.

bypassWorkspaceAcls property

To enhance security, the bypassWorkspaceAcls property was removed from the template annotations endpoint in version 6.3.5 of the Pages module. To maintain the ability to edit your SPA project, you can implement one of the following solutions:

Recommended:
1. First, create a user in Magnolia specifically for the purpose of making requests from your frontend.
2. Then, assign it a role with write access to the website repository.
3. Finally, update the frontend project to include the username and password via basic authentication when it makes requests to the Magnolia endpoints.
Alternatively, reintroduce the bypassWorkspaceAcls property to the endpoint via a definition decoration:
my-light-module/decorations/spa-rendering/restEndpoints/templateAnnotations/templateAnnotationEndpoint.yaml
```
bypassWorkspaceAcls: true
```
As a third approach, you can use an SSO token. You must get the token from the IDP and use it for the template annotations endpoint. However, be aware that for this to work you must configure an http.bearer client on your Magnolia author instance. For more details, see SSO module: Configuring via yaml.

We also suggest enhancing the security of the author instance through additional measures, such as restricting access to specific IP addresses (through /server/IPConfig) or placing it behind a firewall.

SPA template definitions endpoint

For Single-page applications, we provide a dedicated template definitions endpoint which is used to deliver page, area and component template definitions.

Its implementation class is info.magnolia.rendering.spa.rest.v1.TemplateDefinitionEndpoint. You don’t need to configure anything in the endpoint.

Example request URL and response for template id mtk:components/textImage:

http://localhost:8080/magnoliaAuthor/.rest/template-definitions/v1/mtk:components/textImage

{
    "mtk:components/textImage": {
        "dialog": "mtk:components/textImage",
        "templateScript": "/mtk/templates/components/textImage.ftl",
        "name": "textImage",
        "id": "mtk:components/textImage",
        "type": "content",
        "renderType": "freemarker"
    }
}