Multi JCR block

info.magnolia.editor.block.jcr.MultiJcrBlockDefinition is a special type of multi field installed by the Content Editor module. It enables different block types in a content editor, for example the Stories app, and allows you to change their appearance.

Keep in mind that multiJcrBlock is a content-editor field and therefore can’t be used in a content-type app.

By specifying the $type as multiJcrBlock, or alternatively the class as info.magnolia.editor.block.jcr.MultiJcrBlockDefinition, several configuration properties are set automatically:

  • implementationClass is set to info.magnolia.editor.block.MultiBlockView

  • entryResolution is set to MultiJcrBlockEntryResolution

  • orderHandler is set to MultiJcrBlockOrderHandler

Example definition

blocks:
  label: Blocks
  $type: multiJcrBlock
  initialBlock: text
  defaultBlock: image
  blocks:
    - text
    - image
    - video
    - externalLink
  itemProvider:
    $type: currentItemProvider

Properties

Block-specific properties

Property Description

blocks

required

Node containing a list of block definitions.

defaultBlock

required

The name of the block which will be pre-selected in the block picker subdialog.

initialBlock

required

The name of the block that will be created as the initial block when creating a new content item (new story).

Common multi field properties

  • When configuring the common multi field properties listed in the table below, make sure that you use the JcrMultiFieldDefinition-related variables if more options are present.

  • The field property only applies to field definitions. The corresponding property in a multi block definition is blocks (see in the table above).
Property Description

field

required

Node containing an editor property definition item (typically, a field).

All field types are supported. See List of fields for more information.

JcrMultiLinkFieldDefinition supports only link and combobox fields.

chooserId

optional (used only in JcrMultiLinkFieldDefinition), default is ui-framework-core:multiChooser

Unique identifier for the multi-chooser dialog. If none is specified, the JCR multiChooser will be used by default.

entryResolution

optional, default is

  • MultiFieldEntryResolution for JcrMultiFieldDefinition

  • MultiJcrBlockEntryResolution for MultiJcrBlockDefinition

  • JsonMultiFieldEntryResolver for JsonMultiFieldDefinition

Implementation class that defines how the child entries of a multi field should be resolved.

MultiFieldEntryResolution of JcrMultiFieldDefinition extends ByIndexedChildNodes, which resolves entry nodes regardless of node names. To enable this non-strict resolution behavior, there is a strict property that is set to false by default.

Setting strict to true ensures backward compatibility (for example, when porting configurations that use Magnolia 5 UI multi field transformers). In configurations such as the two below, strict falls back to the required value and that change appears in the Definitions app.

  • itemProvider specifies the type of data binding for subnodes in complex fields. When you configure a multi field with CurrentItemProvider and set entryResolution to MultiFieldEntryResolution, the strict node resolution is set to false. This ensures that nodes, which aren’t multi fields, don’t get resolved as multi fields.

  • When you configure a multi field with isSupportI18N set to false, the strict property of entryResolution is set to false. The isSupportI18N configuration flattens localized multi parent nodes into a single parent. However, you need to resolve child nodes in a way that considers their locale suffix and doesn’t take everything beneath the parent, so strict is set to true.

You can’t configure this property through YAML but it can be used in your Java code.

orderHandler

optional, default is

  • DefaultJcrNodeOrderHandler for JcrMultiFieldDefinition

  • MultiJcrBlockOrderHandler for JcrMultiFieldDefinition

Implementation class that sorts nodes and ensures that the suffixes in index names correspond to the order in which they are stored.

When MultiFormDefinition$OrderHandlerDefinition$Noop is used, the order of the items of a multi field cannot be changed retroactively.

You can’t configure this property through YAML but it can be used in your Java code.

canRemoveItems

optional, default is true for MultiValueFieldDefinition and JcrMultiFieldDefinition

When false, the items of a multi field cannot be removed from a dialog.

buttonSelectAddLabel

optional, default is translated buttons.add key (translated dialogs.buttons.select.multiple key for JcrMultiLinkFieldDefinition)

Button label for adding an item. The value is i18n-able.

buttonSelectRemoveLabel

optional, default is translated buttons.delete key

Button label for removing an item. The value is i18n-able.

minItems

optional, default is 0

Specifies the minimum number of items to be added.

maxItems

optional, default is Integer.MAX_VALUE

Specifies the maximum number of items to be added.

If minItems is greater than maxItems, item count validation will be disabled.

itemCountErrorMessage

optional, default is translated validators.multi.itemCount.errorMessage key

Error message shown when the number of items is less than minItems or greater than maxItems. The value can be literal or a key of a message bundle.

required

optional, default is false

Makes the field required. An asterisk is displayed next to the field label.

requiredErrorMessage

optional, default is translated validation.message.required key

Error message shown when required is set to true and the user saves an empty field. The value can be literal or a key of a message bundle.

Common complex field properties

Property Description

name

required

Name of the field definition item. Derived from the configured node name. Use alphanumeric characters without spaces.

class

required (unless $type is used)

Type of the field definition item. The value must be a fully qualified class name and a subtype of info.magnolia.ui.field.FieldDefinition. See Field types for possible values.

$type

You can use this as a shortcut for class if the definition class is annotated with info.magnolia.ui.field.FieldType. The proper value is defined by the annotation.

Example class annotation
@FieldType("textField")
public class TextFieldDefinition extends ConfiguredFieldDefinition<String> {
...
}

See Field types for possible values.

itemProvider

optional, default is

  • JcrChildNodeProviderDefinition for JcrMultiFieldDefinition

  • CurrentItemProviderDefinition for StaticFieldViewDefinition

Node with a $type property that specifies the type of data binding for the subnodes in complex fields.

See Item providers for more information.

You can’t configure this property through YAML but it can be used in your Java code.

description

optional

Help text displayed when the user clicks the help icon. The value can be literal or a key of a message bundle.

i18n

optional, default is false

Enables i18n authoring support, which allows editors to write foreign-language or regionally targeted content. A two-letter language identifier (en, de, fr, etc.) is displayed on controls where i18n is set to true.

label

optional

Field label displayed to editors. The value can be literal or a key of a message bundle.

If you do not provide the property, Magnolia will fall back to a generated i18n key.

If you do not want to have any label, set the property to an empty string such as label: "" in YAML.

styleName

optional

Additional style information for an editor property definition item applied to the element when the form is rendered. The value can be a CSS class or a list of CSS classes separated by white spaces.

The style name will be rendered as an HTML class name, which can be used in a CSS definition. The class name is added to the field by calling the Vaadin method addStyleName.

The referenced class can be defined in:

Content i18n and migration to version 2.1 (and higher)

Internationalization (i18n) of content is supported since version 2.1 of the Content Editor module.

If you are upgrading from Magnolia 6.2 or from a 1.x version of the Content Editor, please mind the migration procedures below to enable i18n in the Stories app, as well as in other Content Editor based apps you may have.

Compatibility of content and block definitions

Block definitions and data structures created in the older versions of the module must be migrated.

Flat vs nested content structure

The data model has changed for internationalized stories. Whereas in versions 1.3.x and 2.0.x of the module, the mgnl:block elements are stored in a flat node structure,

stories
└── story1
    ├── 0
    └── 1

in the i18n-supported version (2.1 and higher), the nodes are locale-nested under intermediate nodes of type mgnl:contentNode, named blocks_de and blocks in this example:

stories
└── story1
    └── blocks_de
    │   ├── 0_de
    │   └── 1_de
    └── blocks
        ├── 0
        └── 1

This must be reflected in your MultiJcrBlockDefinition, where you need to add and enable the i18n property.

Instead of the CurrentItemProvider, the CompatibleBlockProvider is set as the default provider, which can resolve both flat and nested block nodes. You do not need to declare it in your block definition.

Example definition
blocks:
  label: Blocks
  $type: multiJcrBlock
  i18n: true
  blocks:
    - text
This applies only to the 2.0.x block definitions. Block definitions created for version 1.3.x (5 UI) of the module are not compatible with the 2.1 version and must be fully migrated.

Migrating content

There are two ways you can migrate the non-i18n blocks to the i18n-compatible hierarchy: using a version handler or a Groovy script.

We strongly recommend you have the latest version of the Content Editor before migrating your content.

In versions prior to 2.1.3, the MigrateBlockToIntermediateParentTask doesn’t preserve the order of nodes when migrating to the latest version. Running this task can actually reorder the nodes to an incorrect state.
Version handler

When upgrading the Stories app submodule to version 2.1 or higher, all block nodes in the stories workspace will be moved to intermediate nodes, see the MigrateBlockToIntermediateParentTask task.

Groovy script

You can run the migration task in the Groovy app, especially in case a block node is stored in another workspace.

Example Groovy script
import info.magnolia.editor.setup.MigrateBlockToIntermediateParentTask
import info.magnolia.module.InstallContextImpl
import info.magnolia.module.ModuleRegistryImpl
import info.magnolia.objectfactory.Components
import javax.jcr.Session


Session session =  MgnlContext.getJCRSession("stories");
task = new MigrateBlockToIntermediateParentTask("stories", "/", "blocks");
task.execute(Components.newInstance(InstallContextImpl.class));
session.save();

The parameters in the MigrateBlockToIntermediateParentTask:

  • stories - workspace name

  • / - path

  • blocks - name of the intermediate node, the name of the multiJcrBlock field.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules