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

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 is info.magnolia.ui.dialog.DialogDefinition.

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

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

      label: Text
      $type: textField
      light: true
  $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

While base dialog definition does not enforce any type of content, the most common is FormDialogDefinition (which uses FormDefinition for content configuration).

Dialog properties



Unique identifier for the dialog in the registry. Set automatically according to the definition location.


optional, default is commit and cancel

Defines actions in the dialog. Specified actions are rendered as components via 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 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 a label at all, define the property and set its value to a blank space 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.

Location of dialog definition

YAML file pathJCR node path in config workspace
Dialog definition$magnolia.resources.dir/<module-name>/dialogs/modules/<module-name>/dialogs

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.

Example template definition referencing textImage dialog

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

Template property



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.

  • No labels