Defining a Content Block

Directory structure of a Content Block

A Content Block definition has the following files and directory structure:

Directory / File Mandatory? Created via make:content-block
EditorInterface.yaml x x
Source/Language/Labels.xlf x x
Source/EditorPreview.html   x
Source/Frontend.html   x
Assets/EditorPreview.css   x
Assets/Frontend.css   x
Assets/Frontend.js   x
Assets/Icon.(svg/png/gif)   x

Content Block definition files explained


refers to: YAML RFC

You must

  • provide this file
  • define the editor interface of exactly one Content Block
  • define the unique name of the Content Block, all the fields and their position in the editing interface

See Editing interface (YAML reference).

A field is localize-able by default. Setting the localization explicitly is only necessary, if a special localization method is required.


This is the icon for the Content Block. There is no fallback by intention, but it is easy to generate an SVG with the Content Block name as a graphical representation.

You must

  • provide this file
  • provide that file in the format svg or png or gif
  • provide a file with 1:1 dimensions


You may

  • provide that file
  • define your labels with the XLF links in the configuration file

Labels for the editing interface, as well as frontend labels, are stored in the Source/Language/Labels.xlf (translated files will be e.g. de.Labels.xlf).

It is recommended to apply the coding guidelines for labels to your Content Blocks as well. E.g. for backend labels that would be: <code-block-identifier>.<field-identifier>.title

Or the description in the backend, e.g. the description in newContentElementWizard: <code-block-identifier>.<field-identifier>.description

Example for a label of a field: <field-identifier>.label

Example for a description of a field: <field-identifier>.description

This goes analogously for collection fields, in this case the field identifier of the collection field is used as a prefix: <collection-field-identifier>.<field-identifier>.label