Developing and rendering custom content blocks - 5 UI
|
This page has been created for the Magnolia 5 UI framework. For the 6 UI framework page, see Developing and rendering custom content blocks instead. |
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.
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
|
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
blocksfolder of your module and add:-
The
info.magnolia.editor.block.stock.FieldSetBlockDefinitionclass. -
The
templateIdof your block. -
The list of fields the content block consists of.
A general block definition based on the FieldSetBlockDefinition class
-
class: info.magnolia.editor.block.stock.FieldSetBlockDefinition templateId: <module-name>:<the-path-to-the-block-relative-to-the-module> fields: <field-1> <field-2> <field-3> etc.
-
Provide a template definition file and a template script for your block in the
templates/blockssubfolder of your module. -
Optionally, in the
i18nfolder 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 :
Block definition (/block-examples/blocks/quote.yaml)
Template definition file (/block-examples/templates/blocks/quote.yaml)
Template script (/block-examples/templates/blocks/quote.ftl)
i18n file (/block-examples/i18n/example-blocks_en.properties)
Resulting block:
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.ftlpage 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.blockensures 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.blockcalls the template script associated to the passed block content.