Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
This page describes how to define and render custom content blocks that can be grouped to form content compositions in implementations of the Content editor.
The Magnolia Stories app, which is an implementation of the content editor, uses four predefined block types: text
, image
, externalLink
and video
.
Block types
The Content editor provides predefined block types that you can use in your custom content editor app:
text
image
externalLink
video
You can also define your own blocks.
Compared to
TextFieldDefinition
, the text
block implements a special RichTextBlock
class, which features basic text formatting functions:
All the other predefined block types implement the FieldSetBlockDefinition
class.
Note that RichTextFieldDefinition
, based on the CKEditor, is supported in the Content editor since Magnolia 5.7.3.
Demo block types
The Magnolia demo decorates the default Stories app and provides two additional block types you can use:
tour
date
Both block types implement the FieldSetBlockDefinition
class.
To see these blocks you must have the Magnolia demo modules installed.
Defining a custom block
You can quickly create your own custom block using Magnolia CLI. The Magnolia CLI
create-block
command creates a block based on FieldSetBlockDefinition
and includes many commonly used fields as a starting point.
To define a custom block, use a YAML definition file and apply the FieldSetBlockDefinition
class of the Content editor submodule.
- Create a YAML file in the
blocks
folder of your module and add:- The
info.magnolia.editor.block.stock.FieldSetBlockDefinition
class. - The
templateId
of your block. The list of fields the content block consists of.
- The
Provide a template definition file and a template script for your block in the
templates/blocks
subfolder of your module.Optionally, in the
i18n
folder of your module, provide a file with i18n keys for labels and descriptions of the block's fields.
Example: a quotation block
The following code samples are used to create a quotation block in a light module called block-examples
:
class: info.magnolia.editor.block.stock.FieldSetBlockDefinition templateId: block-examples:blocks/quote fields: quotation: class: info.magnolia.ui.form.field.definition.TextFieldDefinition rows: 3 citedPerson: class: info.magnolia.ui.form.field.definition.TextFieldDefinition
templateScript: /block-examples/templates/blocks/quote.ftl renderType: freemarker
[#if content.quotation?has_content] <blockquote> <p>${cmsfn.decode(content).quotation}</p> [#if content.citedPerson?has_content]<cite>${content.citedPerson}</cite>[/#if] </blockquote> [/#if]
blocks.quote.label=Quote quote.quotation.label=Quote quote.citedPerson.label=Cited person
Rendering blocks in a FreeMarker script
This section explains how to render block content in a page or a component template.
The cms:block
directive
The Content editor module provides cms:block
, a Magnolia FreeMarker directive for fetching and rendering block elements.
The directive expects a node of the type mgnl:block
as argument, identifies the template definition of the block and calls the associated template script.
[#assign blocks = cmsfn.children(articleContent, "mgnl:block") /] [#list blocks as block] [@cms.block content=block /] [/#list]
Block-rendering scripts in the article-editor
submodule
In /templates/pages/areas
, the article-editor
submodule already contains the following predefined block-rendering scripts used by the Stories app:
articleDisplayArea.ftl
– Displays a single story.articleListArea.ftl
– Displays a list of all story.articleReferenceArea.ftl
– Displays a referenced story through the/templates/pages/article.inc.ftl
page template script.
Examples of block rendering
The examples show how to render blocks within a template script of a page or component template. Using the Magnolia directive cms.block
, the template script of the block is executed during the rendering of the page or component.
- Get story content:
[#assign articleContent = cmsfn.contentById(content.article, "") /]
- Get the blocks for that story:
[#assign blocks = cmsfn.children(articleContent, "mgnl:block") /]
Retrieve all blocks for a piece of content:
[#if articleContent?hasContent] [#assign blocks = cmsfn.children(articleContent, "mgnl:block") /] [#list blocks as block] [@cms.block content=block /] [/#list] [/#if]
Line 4: The Magnolia directive
cms.block
ensures that the template script associated to the passed block is called to render the block content.Retrieve two blocks, for instance to display an excerpt of a story in a list:
[#if articleContent?hasContent] [#assign blocks = cmsfn.children(articleContent, "mgnl:block") /] [#list blocks as block] [#if block?index == 2] [#break] [/#if] [@cms.block content=block /] [/#list] [/#if]
Line 7: The Magnolia directive
cms.block
calls the template script associated to the passed block content.