Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
This page describes how to develop a custom content editor based on the Magnolia Content editor.
Before you start
This section mentions what you should be aware of before creating an implementation of the content editor.
Understanding the content model: block, composition
A block is a well-defined page section which, together with other blocks and additional meta information, can form a single content composition.
In the context of the content editor app, each item (e.g. a story in the stories-app
) is a composition of N blocks of editable content, such as <hx> headings and <p> paragraphs, complemented by meta information such as the required fields for a lead text and a title of the story:
Required node types
The content editor UI expects nodes of the type mgnl:composition
and mgnl:block
. These node types are defined in the file content-editor-nodetypes.xml
which resides in the magnolia-content-editor
submodule.
Hoewever, registration of these node types is handled by the stories-app
or the article-editor
via the XML-based module descriptor.
Dependencies on the content editor modules
In any case, your implementation of the content editor depends on the following modules:
magnolia-content-editor
magnolia-block-api
magnolia-block-templating
Besides the requirement for these "base modules", you must also ensure that the system registers the required node types.
If your custom content editor is created with a light module, your bundle must contain either the stories-app
or the article-editor
module. If created with a Magnolia Maven module, you can register the node types within your custom module.
If you are using a preconfigured Magnolia Enterprise Edition webapp or bundle (see the list of preconfigured Magnolia bundles), it already contains the stories-app
and all the required modules.
Read Content Editor module - Installing for a deeper understanding of the dependencies between the content editor submodules.
Workspace
To store new content items with your custom content editor, you can use
- the
stories
workspace provided by thestories-app
module, - the
articles
workspace provided by thearticle-editor
module, or a custom workspace defined by your custom module.
Multilingual content
The Content editor and the Stories app don't yet support multi-language content.
Defining a custom content editor app
Developing a custom content editor app is similar to creating a content app because it is also based on the info.magnolia.ui.contentapp.ContentApp
app class.
You can build your custom content editor app within a light module.
Here is an overview how to define a content editor app:
- Create a YAML app descriptor with its subapps.
- Make sure the
contentConnector
is using themgnl:composition
nodetype. - Specifiy the
contentDefinition
with the outline and the blocks section.
Creating the descriptor and subapps
Create a YAML app descriptor.
Typically, you need at least the following two sub apps:
- The browser subapp. Use a regular browser sub app class
info.magnolia.ui.contentapp.browser.BrowserSubApp
. The editor subapp, which is a variant of the detail subapp. It implements content editor's
info.magnolia.editor.app.ContentEditorSubAppDescriptor
class. (See also ContentEditorSubApp descriptor.)
The editor subapp must also implement theActionDefinition
of the Content Editor module.
Using the mgnl:composition
nodetype in the contentConnector
Set the mgnl:composition
nodetype for the contentConnector
property in the subapp descriptors of your content editor:
contentConnector: includeProperties: false workspace: <workspace-name> rootPath: / defaultOrder: jcrName nodeTypes: - icon: icon-node-content name: mgnl:composition strict: true - icon: icon-folder-l name: mgnl:folder strict: true
contentConnector: workspace: <workspace-name> nodeTypes: - icon: icon-node-content name: mgnl:composition strict: true - icon: icon-folder-l name: mgnl:folder strict: true
Instead of <workspace-name> use stories
, articles
or the name of your custom workspace.
Setting the contentDefinition
properties
Add the contentDefiniton
node to your editor subapp's descriptor and define in it what content is allowed (i.e. editable).
You must specify outlineFields
, initialBlock
, defaultBlock
and linkableApps
.
outlineFields
With outlineFields
you define the static, structured information which you want on every content item.
The example below has the following properties: title
, lead
, image
, created
, author
and jcrName
.
blocks
This property defines the block types that are allowed.
blocks: - text - image
The Content Editor module comes with four predefined types of block you can use in your editor: text
, image
, video
and externalLink
. You can also define your own content block(s).
initialBlock
Specifies what will be created as the initial, automatically added block when creating new content (or when no block is available).
initialBlock: text
initialBlock: image
defaultBlock
Defines the block type which will be pre-selected by BlockPickerField.
defaultBlock: image
defaultBlock: text
linkableApp
Defines the app(s) whose resources you can link to from the text
block.
linkableApps: - pages - assets - contacts