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.

form:
  properties:
    text:
      label: Text
      $type: textField
      light: true
footerLayout:
  $type: defaultEditorActionLayout
  primaryActions:
    commit: commit
form:
  properties:
    title:
      $type: textField
      label: Title
    description:
      $type: textField
      label: Description
  layout:
    $type: tabbedLayout
    tabs:
      firstTab:
        label: First
        fields:
          - name: title
      secondTab:
        label: Second
        fields:
          - name: description
footerLayout:
  $type: defaultEditorActionLayout
  primaryActions:
    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

id

required

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

actions

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.

footerLayout

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

Contains the action area configuration. Specifies the action component layout via LayoutDefinition.

primaryActions

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.

secondaryActions

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.

label

optional

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.

layout

optional, default is info.magnolia.ui.framework.layout.SingleTabLayoutProducer

Basic LayoutDefinition. Specifies the layout class for a form.

light

optional, default is false

When true, the dialog does not black out the background.

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

optional

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