This documentation is still in progress. We are working hard to update all our screenshots to the new Magnolia 6 style. Please bear with us.

Page tree
Skip to end of metadata
Go to start of metadata

This page describes how to develop a custom content editor app 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: blockcomposition

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 the stories-app module,  
  • the articles workspace provided by the article-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 the mgnl: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 the ActionDefinition  of the Content Editor module. 

ContentEditorSubAppDescriptor and ActionDefinition(s)
actions:
  close:
    class: info.magnolia.editor.action.CloseContentEditorActionDefinition
  save:
    class: info.magnolia.editor.action.SaveContentActionDefinition
  saveAndPublish:
    class: info.magnolia.editor.action.SaveContentActionDefinition
    onSuccessAction:
      class: info.magnolia.ui.framework.action.ActivationActionDefinition
      command: activate

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 of the browser subapp
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 of the editor subapp
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 storiesarticles 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: titleleadimagecreatedauthor and jcrName .

      outlineFields:
        title:
          class: info.magnolia.editor.app.field.ExpandingTextFieldDefinition
          required: true
          styleName: title
        lead:
          class: info.magnolia.editor.app.field.ExpandingTextFieldDefinition
          rows: 3
          required: true
          styleName: lead-text
        image:
          class: info.magnolia.ui.form.field.definition.LinkFieldDefinition
          targetWorkspace: dam
          appName: assets
          identifierToPathConverter:
            class: info.magnolia.dam.app.assets.field.translator.AssetCompositeIdKeyTranslator
          contentPreviewDefinition:
            contentPreviewClass: info.magnolia.dam.app.ui.field.DamFilePreviewComponent
        entryMetaData:
          class: info.magnolia.editor.app.field.CollapsibleCompositeFieldDefinition
          collapsed: true
          fields:
            created:
              class: info.magnolia.ui.form.field.definition.DateFieldDefinition
              time: true
              required: true
            author:
              class: info.magnolia.editor.app.field.PlaceholderTextFieldDefinition
            jcrName:
              class: info.magnolia.editor.app.field.PlaceholderTextFieldDefinition
              required: true
# eof: outlineFields

blocks

This property defines the block types that are allowed.

Example definition of allowed blocks
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).

Example definition of the initialBlock
initialBlock: text

Example definition of the initialBlock
initialBlock: image

defaultBlock

Defines the block type which will be pre-selected by BlockPickerField.

Example definition of the defaultBlock
defaultBlock: image

Example definition of the defaultBlock
defaultBlock: text

linkableApp

Defines the app(s) whose resources you can link to from the text block.

Example definition of the linkableApps
linkableApps:
  - pages
  - assets
  - contacts