Choosing between FreeMarker and headless templating

While there are many benefits to a headless approach, switching from FreeMarker-based templating to headless templating can be tricky.

This page provides a list of key differences between the two approaches and information about the most common challenges you may encounter when changing or choosing a rendering method for your project.

Overview of the process

FreeMarker	Headless
The web user types a page URL in their browser. The request comes to Magnolia directly. The Magnolia server renders the HTML website. Magnolia returns the HTML page to the web user. Magnolia has full access and control over the generated HTML.	The web user types a page URL in their browser. The request comes to the server where the front-end is hosted (NOT Magnolia). The front-end server or browser renders the HTML website. The front-end app fetches the content data from Magnolia using the Delivery API. Magnolia doesn’t have access to nor control over the generated HTML.

FreeMarker

Headless

The web user types a page URL in their browser.
The request comes to Magnolia directly.
The Magnolia server renders the HTML website.
Magnolia returns the HTML page to the web user.

Magnolia has full access and control over the generated HTML.

The web user types a page URL in their browser.
The request comes to the server where the front-end is hosted (NOT Magnolia).
The front-end server or browser renders the HTML website.
The front-end app fetches the content data from Magnolia using the Delivery API.

Magnolia doesn’t have access to nor control over the generated HTML.

YAML definitions

FreeMarker Headless

	FreeMarker	Headless
Component autogeneration	Supported. See Component autogeneration.	Supported since 6.2.35.
Component inheritance	Supported. See Component inheritance.	Supported since 6.2.35.
Component YAML definition	Magnolia renders the component templates. You specify which FreeMarker template is used to render the page: `templateScript: /hello/templates/components/hello.ftl renderType: freemarker`	The front-end server or browser renders the component templates. Component YAML definitions can be as simple as just the title property. The mapping between template names and JS components is in JS code. For more information, see the React, Angular, and Vue properties.
Dialog definition	Dialog definitions are fully decoupled from template rendering. There are no differences between the FreeMarker and headless templating approaches.
Page YAML definition	Page templates are rendered by Magnolia. You specify which FreeMarker template is used to render the page: `templateScript: /hello/templates/pages/hello.ftl renderType: freemarker`	Page templates are rendered by the front-end server or browser. You only specify the URL to load in the Pages app. `$type: spa baseUrl: http://localhost:3000 routeTemplate: '/\{language}\{\{@path}}'` The mapping between template names and JavaScript components is in the JS code. For more information, see React, Angular, and Vue.
Site Template Prototypes	Supported. See Template prototype.	Supported. See Template prototype. A headless template page must have: `$type: siteSpa` See Common template properties.

Component autogeneration

Supported.

See Component autogeneration.

Supported since 6.2.35.

Component inheritance

Supported.

See Component inheritance.

Supported since 6.2.35.

Component YAML definition

Magnolia renders the component templates. You specify which FreeMarker template is used to render the page:

templateScript: /hello/templates/components/hello.ftl
renderType: freemarker

The front-end server or browser renders the component templates.

Component YAML definitions can be as simple as just the title property.

The mapping between template names and JS components is in JS code. For more information, see the React, Angular, and Vue properties.

Dialog definition

Dialog definitions are fully decoupled from template rendering. There are no differences between the FreeMarker and headless templating approaches.

Page YAML definition

Page templates are rendered by Magnolia. You specify which FreeMarker template is used to render the page:

templateScript: /hello/templates/pages/hello.ftl
renderType: freemarker

Page templates are rendered by the front-end server or browser.

You only specify the URL to load in the Pages app.

$type: spa
baseUrl: http://localhost:3000
routeTemplate: '/\{language}\{\{@path}}'

The mapping between template names and JavaScript components is in the JS code. For more information, see React, Angular, and Vue.

Site Template Prototypes

Supported.

See Template prototype.

Supported.

See Template prototype.

A headless template page must have:

$type: siteSpa

See Common template properties.

End user impact (editor, visitor)

	FreeMarker	Headless
i18n (internationalization of template labels)	Done via i18n message bundles.	See the Magnolia blog post Internationalizing Template Labels in SPAs.
p13n (personalization)	Supported. See Personalization.	Supported. See Personalization. For headless templates, an extra step is required. See Personalization of headless SPA projects.
SEO/Social media sharing	FreeMarker templates are all server-side generated. All SEO/Social media sharing tags work correctly.	For all scenarios that render the site on the server (such as Next.js), all SEO/Social media sharing tags work correctly. For scenarios where JS fetches the page data on the client side in the user browsers, the SEO/Social media sharing tags might not work as expected.
Sitemap	The recommended approach is described in Generating custom sitemap with Solr.	In the headless approach, Magnolia doesn’t render sites and lacks a comprehensive knowledge of the entire scope of the project structure. The SPA has this knowledge and should be tasked with rendering the sitemap by means of the Delivery API to retrieve Magnolia-managed pages or content app items for URL builds.
Versioning	Supported. See Versioning.	Restore works as expected. Show version works but, when fetching data from Magnolia, you must include a version number in the query parameters read from the iframe URL. Compare is not supported.

FreeMarker

Headless

i18n (internationalization of template labels)

Done via i18n message bundles.

See the Magnolia blog post Internationalizing Template Labels in SPAs.

p13n (personalization)

Supported.

See Personalization.

Supported.

See Personalization.

For headless templates, an extra step is required. See Personalization of headless SPA projects.

SEO/Social media sharing

FreeMarker templates are all server-side generated. All SEO/Social media sharing tags work correctly.

For all scenarios that render the site on the server (such as Next.js), all SEO/Social media sharing tags work correctly.

For scenarios where JS fetches the page data on the client side in the user browsers, the SEO/Social media sharing tags might not work as expected.

Sitemap

The recommended approach is described in Generating custom sitemap with Solr.

In the headless approach, Magnolia doesn’t render sites and lacks a comprehensive knowledge of the entire scope of the project structure. The SPA has this knowledge and should be tasked with rendering the sitemap by means of the Delivery API to retrieve Magnolia-managed pages or content app items for URL builds.

Versioning

Supported.

See Versioning.

Restore works as expected.

Show version works but, when fetching data from Magnolia, you must include a version number in the query parameters read from the iframe URL.

Compare is not supported.

Infrastructure

FreeMarker Headless

Caching

Because Magnolia is responsible for serving the HTML to end users, Magnolia controls caching policies and browser caching policies (we can set response headers to make browser cache content).

Magnolia is responsible for Magnolia caching policies. Regarding browser caching, Magnolia can ONLY influence the requests coming to the Delivery API and assets stored in Magnolia. So only those requests reaching Magnolia via:

/.rest/*
/dam/*
/.imaging/*

You must set browser caching policies on the front-end server.

CDN

In a typical case where the CDN inherits the caching headers from the original source, Magnolia can influence all cache headers.

See the Caching row above.

In a typical case where the CDN inherits the caching headers from the original source, Magnolia can only influence the following cache headers:

/.rest/*
/dam/*
/.imaging/*

HTML document headers are set on the front-end servers.

See the Caching row above.

Redirects

Because all requests come to Magnolia, Magnolia controls various redirects using Virtual URI Mappings.

Magnolia can only serve redirects for:

/.rest/*
/dam/*
/.imaging/*

This is because only those requests go directly to Magnolia.

Other redirects must be handled by front-end servers as the initial requests arrive there.

One way of adding the ability to set redirects in Magnolia would involve creating a new Content App to create redirect mappings. The front-end server would then fetch the mappings from Magnolia and apply them.

Magnolia modules and features

FreeMarker

Headless

A/B/n Testing

A/B/n Testing module.

Not supported on headless.

Campaign manager

Supported.

See Campaign manager module.

Supported.

See Campaign manager module.

For headless templates, an extra step is required. For information, see the comments in ticket SUPPORT-12091.

Commerce Connector

E-commerce module.

Supported.

Diff

Diff module.

Not supported on headless.

Form

Magnolia controls the HTML rendering. It can not only allow the creation of forms but also render them inside FreeMarker templates.

FreeMarker-based module allows adding the form processors and custom Java logic to consume and process the data after form submission.

You can use the Form module (incubator version) to create forms. This module exposes the REST APIs to:

Fetch the JSON structure of the form, meaning the JS code needs to fetch the form and render it on its own.
Submit the form to store data entered by the user.

JavaScript Models

JavaScript Models module.

Not supported on headless.

Live Copy

Supported.

See Live Copy.

Supported.

See Live Copy.

Marketing Automation (Web-to-lead)

Marketing Automation Connector pack.

Supported.

Marketing Tags

Magnolia has complete control over rendering the HTML Editors can use the Marketing Tags app to define various tags and Magnolia can add them when rendering the page HTML.

You must add the Delivery API endpoint to the existing Marketing Tags app.

The front-end server fetches the tags from Magnolia and applies them to the generated HTML.

MTK (Magnolia Templating Kit)

MTK module.

Not supported on headless.

Multisite

Multisite module.

Supported.

Pages

Pages module.

Supported.

Personalization