Block definition

This page describes definition properties and template definition properties of a block, a component-like content element provided by the Content editor module.

Compatibility note

Magnolia 6 UI framework is implemented in version 2 of the Content Editor module. Custom content editor and block definitions created in the Magnolia 5 UI framework are not compatible with this version of the module and must be migrated.

If you wish to keep using the existing 5 UI block and custom content editor definitions, you must install version 1.3.10 of the Content Editor module and use them with this version.

For block definition properties in the Magnolia 5 UI framework, see Block definition 5 UI instead.

Overview

A block is the smallest piece of content in an implementation of the Content editor, such as the Stories app. A block definition gives a block a name and specifies the content allowed to form a single block. A block template definition specifies which template should be used to render a block in an area or a page.

The mgnl:block nodetype

Block content is stored using the mgnl:block node type in the JCR. mgnl:block is similar to the custom node type mgnl:content, but it cannot be versioned on its own. Block content is usually grouped into block compositions (mgnl:composition), which are versionable.

Files required

You define blocks to add or modify content in the Stories app or in an implementation of the Content editor. To render the block content, you must then define a template definition and a script for the block. You can define them both using YAML configuration files or JCR nodes.

If you want to define field labels and other i18n descriptors for the elements of your block, you can create the i18n file for the block(s) included in your module.

Definition Location

Block definition

/<module-name>/blocks/<block-name>.yaml *

Template definition

/<module-name>/templates/<path>/<block-name>.yaml **

Template script

/<module-name>/templates/<path>/<block-name>.ftl **

i18n file (optional)

/<module-name>/i18n/

* <block-name> gives the block its name in the JCR.

** The <path> is arbitrary but would typically be blocks for block template files.

Example

my-module
├── blocks
│ └── quotation.yaml
├── i18n
│ └── my-module_en.properties
└── templates
    └── blocks
        ├── quotation.ftl
        └── quotation.yaml

Properties

Block definition

Property Description

templateId

required

The ID of the template definition in <module name>:<path to block definition> format, for example my-module:blocks/quotation.

icon

optional, default is icon-text-block

The icon used by the block picker box.

name

optional

A custom i18n base name to generate a key for the block, for example the name singleTextRow in the i18n key blocks.singleTextRow.label.

By default the block’s name in the JCR is used.

block

required

A node containing a specification of the block.

     implementationClass

optional, default is info.magnolia.ui.editor.FormView

Specifies the implementation used to create the block fields.

For a block with a light rich text field, the implementationClass must be info.magnolia.editor.field.LightRichTextFormView.

     label

optional

An i18n label for the block, for example the value Text in the key-value pair blocks.text.label=Text.

     properties

required

A list of arbitrarily named nodes for the fields creating the block.

Example:

  properties:
    image:
      $type: damLinkField
      label: Image
      placeholder: Add image...
      buttonSelectNewLabel: Select new...
    imageAltText:
      label: Alt text
      $type: textField
      placeholder: Add alt text...

Example

/module-name/blocks/richText.yaml

templateId: module-name:blocks/richText
icon: text-block
block:
  implementationClass: info.magnolia.editor.field.LightRichTextFormView
  label: Rich text
  properties:
    lightRichTextBox:
      class: info.magnolia.editor.field.LightRichTextFieldDefinition
      linkableApps:
        - pages-app
        - dam-chooser

Additional Content Editor field types

Besides the fields usable in the Composite field, you can use also the following fields:

  • LightRichTextFieldDefinition - Creates a text field with simple text formatting capabilities.

  • MultiBlockDefinition - Creates a multi block.

  • SlugFieldDefinition - Creates a URL slug field, which the story editor can use to create a human-readable story title such as lost-and-found-in-swiss-alps.

Block template definition

You can use the following properties in a block template definition:

Property Description

renderType

required

The renderer to be used.

templateScript

required

Path to the template script in the following format:

/<module-name>/templates/<path>/<filename>.<ext>

See Resources for more information about script storage locations.

No dialog definition is required in the block template definition. Everything that is related to the content and the form of a block is defined in the block definition.
Feedback