Related topics:

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

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 .

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.

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.

DefinitionLocation
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

See Module configuration - Location of configuration items for a broader explanation of the location of definition files.

Properties

Block definition

As of Magnolia 5.6.7, references to non-existing and deprecated block definitions are reported in the Definitions app.

class

required

The fully-qualified class name for the Java bean representing the definition of the block. Needs to be a subtype of info.magnolia.block.BlockDefinition.

The default implementation of info.magnolia.block.BlockDefinition can be extended for convenience.

For blocks wrapping one or multiple form fields, there is a built-in info.magnolia.editor.block.stock.FieldSetBlockDefinition which expects an additional fields property listing the form fields.

blockClass

optional ((warning) A default value is already a part of the definition, so there's in fact no need to specify it in the definition YAML file.)

The fully-qualified class name for the Java bean representing the block. Needs to be a subtype of info.magnolia.block.Block.

templateId

required

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

fields

required only for the  FieldSetBlockDefinition class, unavailable for the default and other definitions

Defines what field types are available in the block.

icon

optional, default is icon-help-mark

Defines the icon used by the Block chooser toolbar.

name

optional

A custom i18n base name used by the BlockDefinitionKeyGenerator 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.

label

optional

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

Example

/my-module/blocks/quotation.yaml
class: info.magnolia.editor.block.stock.FieldSetBlockDefinition
templateId: my-module:blocks/quotation.ftl
fields:
  textRow:
    class: info.magnolia.ui.form.field.definition.TextFieldDefinition
Node nameValue

 
modules


 
<my-module>


 
blocks


 
quotation


 
fields


 
textRow


 
class

info.magnolia.ui.form.field.definition.TextFieldDefinition

 
class

info.magnolia.editor.block.stock.FieldSetBlockDefinition

 
templateId

my-module:blocks/quotation.ftl

Block template definition

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

renderType

required

The renderer to be used.

templateScript

required

Path to the template script in the /<module-name>/templates/<path>/<filename>.<ext> format. See Resources for more information about script storage locations.

(warning) 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.

Block definitions provided

Magnolia provides the following definitions out-of-the-box.

FieldSetBlockDefinition

Use this definition to configure the list of fields depending on your needs as explained in the properties table above. 

RichTextBlock

This is a block definition with a single text field and simple text formatting capabilities.

Example block definition:

content-editor/blocks/text.yaml
blockClass: info.magnolia.editor.block.stock.RichTextBlock
templateId: content-editor:blocks/text
icon: edit

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))

2 Comments

  1. Vyacheslav Maksimov

    Hello.

    I want to use a RichText field and plus other fields in one block, how to do this?

    1. Christoph Meier

      Hi Vyacheslav

      You have to create some custom blocks. I see two possibilities:

      1)
      Create a custom block by extending info.magnolia.editor.block.stock.RichTextBlock according to your needs.

      2)
      Extend info.magnolia.editor.block.stock.FieldSetBlockDefinition for a custom version which allows to take RichTextBlock.

      The 1st option seems easier at 1st sight. Note that I have not tried out (neither #1 nor #2).
      Also note that you should not use (default) RichTextBlock within (default) FieldSetBlockDefinition - and I guess there was a good reason to prohibit this.

      I hope this helps,
      ¯\_(ツ)_/¯
      cheers,
      Christoph