Dialog definition

A dialog is a pop-up featuring some content and actions to conduct some operations on that content. It contains a head (title), content (typically forms) and a footer (mainly action controls).

This dialog definition is part of the Magnolia 6 UI framework. The fully qualified class name for the base definition is info.magnolia.ui.dialog.DialogDefinition.

If you work with the Magnolia 5 UI framework, see Dialog definition for Magnolia 5 UI instead.

The base dialog definition does not enforce any type of content. The most common dialog definition is info.magnolia.ui.dialog.FormDialogDefinition, which uses info.magnolia.ui.editor.FormDefinition for content configuration.

Dialog definitions for Magnolia 5 UI still reside in the same registry and can be used in the apps that are not ported to Vaadin 8 UI; they extend the dialog definition for Magnolia 6 UI (with legacy properties).

Example definition

There are many layout possibilities when using Magnolia 6 UI dialogs (see Layout types). The most common is the tabbed layout with its single-tab and multi-tab use cases.

  • Single tab

  • Multi tab

      label: Text
      $type: textField
  $type: defaultEditorActionLayout
    commit: commit
      $type: textField
      label: Title
      $type: textField
      label: Description
    $type: tabbedLayout
        label: First
          - name: title
        label: Second
          - name: description
  $type: defaultEditorActionLayout
    commit: commit

Dialog properties

Property Description



Node containing fields and similar components as well as their layout.

See Form definition for more information.


optional, default is commit and cancel

Defines actions in the dialog. Specified actions are rendered as components via info.magnolia.ui.api.action.ActionDefinition.

Only the actions that are defined will be provided. If no action is specified, the dialog will have commit and cancel actions by default.


optional, default is info.magnolia.ui.dialog.layout.DefaultEditorActionLayoutDefinition

Contains the action area configuration. Specifies the action component layout via info.magnolia.ui.framework.layout.LayoutDefinition.


optional, default is commit and cancel

Adds subnodes to match the primary actions defined in the actions node. The order of the subnodes defines the sequence in which they are rendered. Actions configured under primaryActions are rendered on the right side.


optional, default is localeSelector

Adds subnodes to match the secondary actions defined in the actions node. The order of the subnodes defines the sequence in which they are rendered. Actions configured under secondaryActions are rendered on the left side.



Dialog 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.


optional, default is true

When false, the dialog blacks out the background—you can only interact with the dialog until it is closed.


optional, default is false

When true, the dialog appears in wide mode using the maximum width of the viewport with a 20-pixel padding on the left and right. See also the width property.


optional, default is medium

Defines the dialog width. Possible values are small (700 pixels), medium (1000 pixels) and wide. For small and medium to work, the wide property has to be false.

Definition location

YAML file path JCR node path in config workspace

Dialog definition



Referencing dialogs

Templates reference dialog definitions in their template definition. This is how the system knows which dialog to associate with the template. Page, area and component templates reference dialogs in the same way by using the dialog property.

dialog: my-module:components/textImage
renderType: freemarker
templateScript: /components/textImage.ftl
title: Text & Image Component
Property Description



Dialog definition ID in <module-name>:<path to dialog definition> format.

The ID has two parts separated by a colon:

  1. <module-name>: the name of the module that contains the dialog definition.

  2. <path>: relative path to the dialog definition inside the dialogs root item. For example, the dialog ID my-module:components/textImage points either to the YAML file $magnolia.resources.dir/my-module/dialogs/components/textImage.yaml or to the JCR node /modules/my-module/dialogs/components/textImage in the configuration workspace.

Using dialogs in templates

Dialogs are most commonly used for content entry in components. However, dialogs are also useful for page and area templates. Here are a few suggestions:

  • Page dialogs:

    • Content entry: use the dialog to enter content that is not necessarily rendered on the page (for example, to enter a meta title and description that are injected into the <head> element or a page excerpt for use in teaser components on other pages).

    • Navigation: set up a field to mark the page for inclusion in or exclusion from navigation. You could also define browser header and tab titles.

    • Information: page dialogs can provide editors with useful information. For example, the Content Dependencies module includes a generic tab that collects page dependencies such as other pages and assets. This information is useful when deleting a page.

  • Area dialogs: while most areas contain components, dialog content can be rendered by the script in noComponent areas.

Reusing configuration

Magnolia provides mechanisms to reuse dialogs and other configuration items. For more information, see Reusing configuration.


DX Core



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
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.