Reusing configuration

When developing a website or an application using Magnolia, it’s recommended to reuse existing components or entire pages from other projects. This is particularly useful for accelerating development and maintaining consistency across different parts of your digital presence. For instance, if you’re building a new section of your site and find that a page from the travel-demo project, for example, its home page, already contains the layout, components, and content structure you need, you can leverage it.

This page gives an overview of how you can reuse configurations and override properties to customize them to suit your needs. Instead of copying specific instances of pages, you reuse the underlying YAML definitions or extend JCR-based items. You can only include or inherit the same type of configurations, such as dialog actions or form fields, into a dialog.

Reusing definitions

Within both JCR configuration and YAML files, you can use mechanisms to reuse existing configuration.

YAML include

Use !include in a YAML file to reuse a snippet or a complete YAML-based configuration. Reference the includable as Magnolia Resource (which can be from any origin).

!include:/mtk/dialogs/pages/basic.yaml (1)
form:
  properties:
    - name: title (2)
      description: Some new description for the title (2)
1 Includes the basic.yaml resource with the !include directive.
2 Modified properties in the included definition.
Avoid adding YAML snippets, which are not proper definitions, to definition-specific folders like templates, dialogs, or apps. Instead, place them in a folder that is not scanned, such as /<your-module>/includes/.

For more details, see YAML include.

YAML inherit

Use !inherit in a YAML file to inherit a registered definition item. You can inherit on the root level only.

  • Inherit from a-component

  • a-component definition

!inherit:module-a:components/a-component (1)
title: b-component (2)
description: This is a b-bombastic component to test cool YAML features! (3)
parameters:
  color: red (4)
  size: 100 (4)
1 Inherit the a-component definition.
2 Override the title property.
3 Add a new description property.
4 Override the color and size properties. 
title: a-component
renderType: freemarker
templateScript: /module-a/templates/components/a-component.ftl
dialog: module-a:components/a-component
modelClass: info.magnolia.module.jsmodels.rendering.JavascriptRenderingModel

parameters:
  color: blue
  size: 50

For more details, see YAML inherit.

YAML override

The !override directive prevents a node from inheriting properties from its original definition. Therefore, you must explicitly define all necessary properties for the overridden node.

  • Inherit and override

  • /module-a/templates/pages/l-page.yaml definition

!inherit:module-a:pages/l-page
title: XS page

areas:
  main:
    availableComponents: !override (1)
      linkList: (2)
        id: my-module:components/myLinkList (2)
1 The resulting definition ignores all the properties of availableComponents in the inherited l-page definition (textImage, teaser, image, and link).
2 Only the myLinkList component is available in the main area. 
title: L page
templateScript: /mtk/templates/pages/basic.ftl
renderType: freemarker
dialog: module-a:pages/l-page
visible: true

areas:
  main:
    availableComponents:
      textImage:
        id: mtk:components/textImage
      teaser:
        id: mtk:components/teaser
      image:
        id: mtk:components/image
      link:
        id: mtk:components/link

JCR extends

The JCR extends mechanism is based on JCR nodes and properties. JCR configuration data can be extended on any node level, and thus on any level of configuration. JCR extends allow to extend sub-items of a JCR-defined item definition.

For more details, see JCR extends.

Summary

The following table outlines the reuse commands, detailing their application and usage.

Reuse command Context Inheritance type Override granularity Typical use

!include

YAML only

Snippet/config fragment

Node-level (inserted block)

Share reusable chunks in a folder that is not scanned, such as /<your-module>/includes/.

!inherit

YAML registry (root only)

Whole definition

Root-level, you can override keys

Inherit whole definitions from the YAML registry. Registered items can originate from YAML files, JCR configurations, or even Blossom Java code.

extends

JCR (config workspace)

Whole node/subtree

Any node/property

Runtime config & reuse, for example, extend a site definition and override locales.

!content-type

Creates a content app based on a content type.

Whole definition

Root-level, you can override any configuration with the same name

App descriptors for content-type apps.

What can’t be overridden?

Overriding is not possible in the following situations:

  • You can’t override list items due to their syntax. To bypass this constraint, use a YAML map instead of a list to apply an !override to an item. Even if the definition class expects a list, the YAML file can define the item with a map.

  • You can override Magnolia defaults within your module descriptors, but not observed components.

  • If automatic generation of references is turned off in the Headless Accelerator, reference resolvers can’t be overridden for specific properties.

In addition, the following properties can’t be overridden.

  • Unique and system IDs

    • Dialog, component, renderer, site, and page definitions require a globally unique and unchangeable id property.

    • JCR node names must be unique within their scope and can’t be altered by inheritance or override.

  • Type/Class properties

    • The $type property in field and column definitions specifies a component’s unchangeable class.

    • App and subapp descriptors also need fixed class properties for correct implementation binding.

  • Domain, mapping, group, row names

    • Domain mapping: Node and domain names in site definitions must be unique and constant for stable routing.

    • App Launcher: Critical structure names (group, row) can’t be overridden without breaking the layout.

  • Field and area names must be unique within their container and can’t be redefined by inheritance.

What can be overridden?

The table below lists standard properties across the most used configuration definitions. All items that can be configured via YAML are registered in a specific registry. Registered items can be viewed in the Definitions app.

Definitions Example properties Standard properties

App Launcher layout

Follow this link for a full example definition.

layout:
  ...
  groups:
    - name: content
      label: <MY CONTENT GROUP>
      apps:
        - name: pages-app
        - name: dam
        - name: stories
        - name: tours
        - name: contacts
  ...
  rows:
    - name: one
      cssClass: editor
      groups:
        content: content
        marketing: marketing
  ...

Organizes apps into rows and groups so users see apps grouped by purpose (for example, editors, developers) with a customized layout.

  • layout

  • groups

  • label

  • apps

  • hiddenApps

  • cssClass (a group’s background color)

App descriptor

Follow this link for full details on content type-based configuration and a fully manual app configuration.

!content-type:tour
label: tours.app.label
icon: icon-language-app
permissions:
  roles:
    - travel-demo-editor
    - travel-demo-publisher
subApps:
  browser:
    actions:
     addItem:
       appName: tours
     editItem:
       appName: tours
  detail:
    form:
      properties:
        name:
          i18n: true

Defines the core properties and behavior of an application, including its appearance, permissions, and available sub-applications.

  • name

  • label

  • icon

  • permissions

  • subApps

Subapp descriptor

Go to Subapp descriptor properties for more details. Exmaple descriptor definition below.

subApps:
  browser:
    subAppClass: info.magnolia.ui.contentapp.browser.Browser
    class: info.magnolia.ui.contentapp.configuration.BrowserDescriptor
    label: Browser
    icon: icon-app
    datasource:
      workspace: myWorkspace
      rootPath: /items
    actions:
      # define subapp-specific actions here
      # e.g. refresh, preview, custom actions
    closable: true

Defines a subapp tab within an app. Controls its data source, tab label/icon, available actions, and whether the tab can be closed.

  • name (the subapp node name, for example, browser)

  • subAppClass ( can’t be overridden)

  • class ( can’t be overridden)

  • label

  • icon

  • datasource (inherits from the app if omitted)

  • actions

  • closable (default: true)

Workbench

Go to Workbench properties for more details.

workbench:
  contentViews:
    - name: tree
      view:
        $type: treeView
    - name: list
      view:
        $type: listView
  extensionViews:
    - view:
        $type: thumbnailView
      icon: icon-view-thumbnails
      expandRatio: 1f

Defines the main browsing area of a content app: which content views are available and any optional extension panels, plus sizing and naming.

  • contentViews (at least one view)

  • extensionViews

    • view (extension view definition)

    • icon (extension panel icon)

    • expandRatio (extension panel size share)

    • expandHorizontally (layout orientation)

    • splitRatio

  • name (default is workbench)

Content view

Go to Content view properties for more details.

contentViews:
  - name: tree
    $type: treeView
    columns:
      - name: jcrName
        $type: jcrTitleColumn
        editable: true
      - name: jcrPath
        $type: jcrPathColumn
    dropConstraint:
      $type: jcrDropConstraint
      primaryNodeType: mgnl:content
    icon: icon-view-tree
    readOnly: false
    scrollToSelectedItem: true
  - name: list
    $type: listView
    columns:
      - name: jcrName
        $type: jcrTitleColumn
    multiSelect: true
    multiSelectByRowClick: false
  - $type: thumbnailView
    icon: icon-view-thumbnails

Defines a view inside the workbench (tree, list, or thumbnail), including its columns, drag-and-drop behavior, selection, and display options.

  • $type or class (view type)

  • columns (tree/list only)

  • dropConstraint (tree/list only)

  • name

  • icon

  • readOnly

  • multiSelect (checkboxes or radio buttons)

  • multiSelectByRowClick (rows instead of checkboxes)

  • scrollToSelectedItem

Column

Go to Column properties for more detais.

columns:
  jcrName:
    $type: jcrTitleColumn
    label: name
    editable: true
  jcrPath:
    $type: jcrPathColumn
    label: path
  lastModified:
    $type: dateColumn
    label: Last changed
    sortable: true

Configure column display, editing, filtering, width, and sorting options.

  • $type or class

  • name, label

  • type

  • editable (default is false)

  • editor (with field and availability properties)

  • filterComponent

  • sortable (default is true)

  • expandRatio, width, minimumWidth, maximumWidth, minimumWidthFromContent

Data source

Go to Datasource types for more general details or JCR example definition for a full JCR datasource example.

datasource:
  $type: jcrDatasource
  workspace: website
  rootPath: /
  allowedNodeTypes:
    page: mgnl:page
    folder: mgnl:folder

Connect apps, subapps, and fields to a persistence layer such as JCR.

  • $type or class

  • workspace

  • rootPath

  • allowedNodeTypes

Action bar

Follow this link for a full example definition.

actionbar:
  defaultAction: edit
  sections:
    - name: root
      groups:
        - name: create
          items:
            - name: addFolder
            - name: addPage
    - name: page
      groups:
        - name: edit
          items:
            - name: edit
            - name: move
      availability:
        nodeTypes:
          - mgnl:page

Organizes actions into sections and groups and defines when each section is displayed.

  • sections

  • groups → items

  • availability

    • nodeTypes

    • rules

    • root

    • properties

  • label

  • defaultAction

Action

Go to General action properties for more details.

actions:
  addFolder:
    $type: addNodeAction
    label: Add folder
    icon: icon-add-folder
    nodeType: mgnl:folder
    availability:
      root: true
      nodeTypes:
        - mgnl:folder

Configures an executable UI action (for example, add, edit, publish).

  • $type or class

  • label

  • icon

  • availability

Site

Follow this link for a full example definition.

templates:
  availability:
    templates:
      home:
        id: travel-demo:pages/home
theme:
  name: travel-demo-theme
i18n:
  enabled: true
  fallbackLocale: en
domains:
  main:
    name: www.example.com
enabled: true

Controls site-wide settings, including available page templates, theme, locale, and routing (URL mapping).

  • enabled

  • templates

    • availability

  • theme

  • i18n

  • mappings

  • domains

  • trustedProxyConfig

  • variations (adapting a site to different devices or geographical locations)

Content mapping and domain configuration

Go to Mappings configuration for more details.

mappings:
  website:
    repository: website
    handlePrefix: /travel
    URIPrefix:
domains:
  travel-demo:
    name: travel-demo.magnolia-cms.com
    protocol: https

Specifies the content mapping, for example, the /travel website in the Pages app, in the mappings property, and the domain mapping for the site in the domains property.

  • mappings

    • repository

    • handlePrefix

    • URIPrefix

  • domains

    • name

    • port

    • protocol

    • context

Renderer

See Configuring a renderer for more details.

class: info.magnolia.rendering.renderer.FreemarkerRenderer
contextAttributes:
  cmsfn:
    componentClass: info.magnolia.templating.functions.TemplatingFunctions
    name: cmsfn

Register a rendering engine and optional context attributes.

  • class

  • contextAttributes

    • componentClass

    • name

Theme

Go to CSS Files, JavaScript files, or Image variations for more details.

cssFiles:
  bootstrap:
    link: /.resources/my-theme/libs/bootstrap.css
    media: all
jsFiles:
  jquery:
    link: /.resources/my-theme/js/jquery.min.js
imaging:
  class: info.magnolia.templating.imaging.VariationAwareImagingSupport
  variations:
    1366:
      class: info.magnolia.templating.imaging.variation.SimpleResizeVariation
      width: 1366

Defines site-wide CSS, JS resources, and imaging variations.

  • cssFiles

  • jsFiles

  • imaging

    • variations

Page

Go to Page template properties for more details.

renderType: freemarker
templateScript: /my-module/templates/pages/home.ftl
dialog: my-module:pages/home
visible: true
class: com.example.templates.HomeTemplateDefinition
modelClass: com.example.templates.HomePageModel
areas:
  main:
    availableComponents:
      text:
        id: my-module:components/text

Defines a page template, its script, areas, and availability.

  • renderType

  • templateScript

  • dialog

  • visible

  • class

  • modelClass

  • areas

Area

Go to Area properties for more details.

areas:
  content:
    type: list
    availableComponents:
      text:
        id: my-module:components/text
    optional: false
    editable: true

Defines editable regions of a page/component and which components are allowed.

Component

Go to Component properties for more details.

renderType: freemarker
templateScript: /my-module/templates/components/text.ftl
dialog: my-module:components/text
modelClass: com.example.templates.TextComponentModel
deletable: false
moveable: false
personalizable: false
class: com.example.templates.TextComponentDefinition

Defines a component with its own script and dialog.

  • renderType

  • templateScript

  • dialog

  • modelClass

  • deletable

  • moveable

  • personalizable

  • class

  • areas (for nested components)

Dialog

Follow this link for a full example definition.

form:
  properties:
    text:
      label: Text
      $type: textField
footerLayout:
  $type: defaultEditorActionLayout
  primaryActions:
    commit: commit

It defines the fields, tabs, actions, and layout for dialogs that editors use to input and manage content.

  • id ( can’t be overridden)

  • label

  • description

  • width

  • form

  • tabs

  • fields

  • actions

  • primaryActions

  • secondaryActions

  • footerLayout

Field

Refer to specific field pages, for example Text field, Link field, Multi field, or Checkbox field.

title:
  label: Title
  $type: textField
  required: true
  description: Display title
  validators:
    notEmpty:
      $type: notEmpty

Defines form input, which is used in dialogs, where authors can enter content.

  • $type or class

  • label

  • description

  • required

  • readOnly

  • defaultValue

  • i18n

  • validators
Related topics
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