SPA templating API

SPA template annotations endpoint

Magnolia SPA template annotations make content from a front-end (SPA) 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.

Since Magnolia 6.2.6, the 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.

Retrieving annotations

The example below shows how you can retrieve template annotations for the About page in the angular-magnolia-int light module. The light module is part of our spa-angular-minimal demonstration Angular application.

The endpoint path is configured on line 9 of the environment.ts configuration file:

const SERVER = 'http://localhost:8080';
const SERVER_PATH = '/magnoliaAuthor';

export const environment = {
server: SERVER,
serverPath: SERVER_PATH,
restUrlBase: SERVER + SERVER_PATH + '/.rest/delivery/pages/v1',
restPreviewUrlBase: SERVER + SERVER_PATH + '/.rest/preview/pages/v1',
templateAnnotationsBase: SERVER + SERVER_PATH + '/.rest/template-annotations/v1'
};

In the page edit mode, the About page looks like this when none of its components is selected:

About page in the Magnolia SPA angular demo

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

http://localhost:8080/magnoliaAuthor/.rest/template-annotations/v1/angular-minimal/about

The server returns the following JSON data:

{
"/angular-minimal/about/mainArea/0": "cms:component content=\"website:/angular-minimal/about/mainArea/0\" dialog=\"angular-magnolia-int:components/twoColumns\" label=\"Component with two columns\" activationStatus=\"0\"",
"/angular-minimal/about/header/0": "cms:component content=\"website:/angular-minimal/about/header/0\" label=\"Navigation\" activationStatus=\"0\"",
"/angular-minimal/about/mainArea/0/left/0": "cms:component content=\"website:/angular-minimal/about/mainArea/0/left/0\" dialog=\"angular-magnolia-int:components/textImage\" label=\"Text and image\" description=\"Adds headline, text and image.\" activationStatus=\"0\"",
"/angular-minimal/about": "cms:page content=\"website:/angular-minimal/about\" dialog=\"angular-magnolia-int:pages/home\"",
"/angular-minimal/about/header": "cms:area content=\"website:/angular-minimal/about/header\" name=\"header\" availableComponents=\"angular-magnolia-int:components/navigation\" type=\"single\" label=\"Single Area\" inherit=\"false\" optional=\"false\" createdAreaNode=\"true\" showAddButton=\"false\" showNewComponentArea=\"false\" activationStatus=\"0\"",
"/angular-minimal/about/mainArea": "cms:area content=\"website:/angular-minimal/about/mainArea\" name=\"mainArea\" availableComponents=\"angular-magnolia-int:components/alert,angular-magnolia-int:components/textImage,angular-magnolia-int:components/twoColumns\" type=\"list\" label=\"Main Area\" inherit=\"false\" optional=\"false\" createdAreaNode=\"true\" showAddButton=\"true\" showNewComponentArea=\"true\" activationStatus=\"0\"",
"/angular-minimal/about/mainArea/0/right/0": "cms:component content=\"website:/angular-minimal/about/mainArea/0/right/0\" dialog=\"angular-magnolia-int:components/textImage\" label=\"Text and image\" description=\"Adds headline, text and image.\" activationStatus=\"0\"",
"/angular-minimal/about/customArea": "cms:area content=\"website:/angular-minimal/about/customArea\" name=\"customArea\" availableComponents=\"angular-magnolia-int:components/card\" type=\"list\" label=\"Custom Area\" inherit=\"false\" optional=\"false\" createdAreaNode=\"true\" showAddButton=\"true\" showNewComponentArea=\"true\" activationStatus=\"0\"",
"/angular-minimal/about/staticArea": "cms:area content=\"website:/angular-minimal/about/staticArea\" name=\"staticArea\" availableComponents=\"\" type=\"noComponent\" dialog=\"angular-magnolia-int:areas/static\" label=\"Static Area\" inherit=\"false\" optional=\"false\" createdAreaNode=\"true\" showAddButton=\"false\" showNewComponentArea=\"false\" activationStatus=\"0\"",
"/angular-minimal/about/mainArea/0/left": "cms:area content=\"website:/angular-minimal/about/mainArea/0/left\" name=\"left\" availableComponents=\"angular-magnolia-int:components/textImage\" type=\"list\" label=\"Left Area\" inherit=\"false\" optional=\"false\" createdAreaNode=\"true\" showAddButton=\"true\" showNewComponentArea=\"true\" activationStatus=\"0\"",
"/angular-minimal/about/mainArea/0/right": "cms:area content=\"website:/angular-minimal/about/mainArea/0/right\" name=\"right\" availableComponents=\"angular-magnolia-int:components/textImage\" type=\"list\" label=\"Right Area\" inherit=\"false\" optional=\"false\" createdAreaNode=\"true\" showAddButton=\"true\" showNewComponentArea=\"true\" activationStatus=\"0\""
}
Page content for single-page applications is delivered through the Delivery API.

SPA template definitions endpoint

For Single-page applications, the magnolia-spa-rendering submodule of the Pages module provides 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"
    }
}
Page content for single-page applications is delivered through the Delivery API.
Related topics
Feedback