The 5.7 branch of Magnolia reached End-of-Life on December 31, 2023, as specified in our End-of-life policy. This means the 5.7 branch is no longer maintained or supported. Please upgrade to the latest Magnolia release. By upgrading, you will get the latest release of Magnolia featuring significant improvements to the author and developer experience. For a successful upgrade, please consult our Magnolia 6.2 documentation. If you need help, please contact info@magnolia-cms.com.
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.
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
See Module configuration - Location of configuration items for a broader explanation of the location of definition files.
Properties
Block definition
class | required The fully-qualified class name for the Java bean representing the definition of the block. Needs to be a subtype of The default implementation of For blocks wrapping one or multiple form fields, there is a built-in |
| optional ( 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 |
templateId | required The ID of the template definition in |
fields | required only for the 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 By default the block's name in the JCR is used. |
label | optional An i18n label for the block, for example the value |
Example
class: info.magnolia.editor.block.stock.FieldSetBlockDefinition templateId: my-module:blocks/quotation.ftl fields: textRow: class: info.magnolia.ui.form.field.definition.TextFieldDefinition
Node name | Value |
---|---|
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. |
| required Path to the template script in the |
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.
Do not use the field type info.magnolia.ui.form.field.definition.RichTextFieldDefinition
on a FieldSetBlockDefinition, instead use the RichTextBlock (see below).
RichTextBlock
This is a block definition with a single field. Use this block when you need a rich text editor.
Example block definition:
blockClass: info.magnolia.editor.block.stock.RichTextBlock templateId: content-editor:blocks/text icon: edit