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

form:
  properties:
    text:
      label: Text
      $type: textField
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

Dialog properties

Property Description

form

required

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

See Form definition for more information.

actions

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.

footerLayout

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.

     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 to have any label, set the property to an empty string such as label: "" in YAML.

light

optional, default is true

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

wide

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.

width

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

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

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

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.

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