Developing and rendering custom content blocks

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.

Defining a custom block

To define a custom block, use a YAML definition file and apply the FieldSetBlockDefinition class of the Content editor submodule.

1. Create a YAML file in the blocks folder of your module and add:
   1. The info.magnolia.editor.block.stock.FieldSetBlockDefinition class.
   2. The templateId of your block.

   3. The list of fields the content block consists of.

      A general block definition based on the FieldSetBlockDefinition class Expand source

      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.

2. Provide a template definition file and a template script for your block in the templates/blocks subfolder of your module.

3. 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.

1. Get story content:
   [#assign articleContent = cmsfn.contentById(content.article, "") /]
2. Get the blocks for that story:
   [#assign blocks = cmsfn.children(articleContent, "mgnl:block") /]

3. 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.

4. 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.