Dialog definition - 5 UI

Deprecated

This dialog definition has been deprecated since Magnolia 6.0. It is part of the Magnolia 5 UI framework.

For the updated implementation, see Dialog definition for Magnolia 6 UI instead.

Dialogs are used for content entry. A dialog defines the editable content properties of a template. Pages, area and component templates can all use dialogs.

The create-page and create-component commands in the Magnolia CLI create basic dialog definitions automatically.

A dialog is basically an HTML form with input fields for each content property. Editors type content into the fields and the dialog saves it in the repository.

The functionality of each field in a dialog is provided by a field definition class that allows the editor to perform a task such as enter text, upload an image, select a date etc. Fields are assembled into tabs and tabs into dialogs.

All dialogs used throughout the system are configured in the same way. For example, the configuration of dialogs used in apps and components is the same.

Dialog properties

At minimum a dialog definition must have a name and has to contain a form and actions.

Here’s what the configurations do:

Form definition: Defines the tabs and fields in the dialog. It determines what content users can enter into the dialog.
Action definition: Defines how the form is submitted. Each action definition displays as a button in the dialog. Action definitions control what happens when a user clicks a dialog button. Typical dialogs have save and cancel actions.

Example: Simple dialog definition

YAML file JCR node

<module name>/dialogs/<dialog name>.yaml

form:
  tabs:
    - name: tabText
      fields:
        - name: title
          fieldType: text
          label: Title
actions:
  commit:
    class: info.magnolia.ui.dialog.action.SaveDialogActionDefinition
    label: Save
  cancel:
    class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition
    label: Cancel

Simple dialog definition

Title field

Node Description

Node	Description
`<dialog-name>`	required Arbitrary node name. Typically matches the template it edits. For example the component definition node and dialog definition node for a link component could both be named `link`. This is not required and one dialog can be used for more than one template.
`form`	required Contains a form definition, which defines the fields where content is entered.
`actions`	required Contains action definitions which define how the data is submitted. The actions are rendered to users as buttons. Typically you need at least save and cancel actions.
`modalityLevel`	optional Modality level defines how intrusive the dialog is. Valid values are `strong` (default), `light` and `non-modal`.
`actionArea`	optional Allows you to configure secondary actions.
`wide`	optional, default is `false` `true` opens the dialog in wide mode using all available horizontal space. Click the expand/collapse button in the top right corner to toggle between the wide and normal (720px) modes.
`label`	optional A property that sets the dialog’s caption. The value is ignored if the `dialogLabelItemProperty` property is set (see below). The value can be literal such as `Group` or retrieved from the message bundle with a key such as `security-app.group.label`.
`dialogLabelItemProperty`	optional Allows you to set the dialog’s caption dynamically through a property holding the preferred value for the caption, for example through the `jcrName` property. If no `dialogLabelItemProperty` is configured for the dialog, Magnolia tries to retrieve the caption from the `label` property (see above) or from the respective `i18n` key in the language bundle associated with the dialog. The `jcrName` property is implemented as the value of `dialogLabelItemProperty`, for instance, in the Security app’s `user`, `role` and `group` dialogs (`group` dialog shown below):

<dialog-name>

required

Arbitrary node name. Typically matches the template it edits. For example the component definition node and dialog definition node for a link component could both be named link. This is not required and one dialog can be used for more than one template.

form

required

Contains a form definition, which defines the fields where content is entered.

actions

required

Contains action definitions which define how the data is submitted. The actions are rendered to users as buttons. Typically you need at least save and cancel actions.

modalityLevel

optional

Modality level defines how intrusive the dialog is. Valid values are strong (default), light and non-modal.

actionArea

optional

Allows you to configure secondary actions.

wide

optional, default is false

true opens the dialog in wide mode using all available horizontal space.

Click the expand/collapse button in the top right corner to toggle between the wide and normal (720px) modes.

label

optional

A property that sets the dialog’s caption.

The value is ignored if the dialogLabelItemProperty property is set (see below).

The value can be literal such as Group or retrieved from the message bundle with a key such as security-app.group.label.

dialogLabelItemProperty

optional

Allows you to set the dialog’s caption dynamically through a property holding the preferred value for the caption, for example through the jcrName property.

If no dialogLabelItemProperty is configured for the dialog, Magnolia tries to retrieve the caption from the label property (see above) or from the respective i18n key in the language bundle associated with the dialog.

The jcrName property is implemented as the value of dialogLabelItemProperty, for instance, in the Security app’s user, role and group dialogs (group dialog shown below):

Editors

Location of dialog definitions

YAML file path JCR node path in config workspace

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

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: A component definition that references a textImage dialog.

YAML file JCR node

<module name>/templates/components/textImage.yaml

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

Node name	Value
my-module
templates#
components#
textImage#
dialog#	my-module:components/textImage
renderType#	freemarker
templateScript#	/components/textImage.ftl
title#	Text & Image Component

Node name

Value

my-module

templates#

components#

textImage#

dialog#

my-module:components/textImage

renderType#

freemarker

templateScript#

/components/textImage.ftl

title#

Text & Image Component

Property Description

Property	Description
`dialog`	optional Dialog definition ID in `<module-name>:<path to dialog definition>` format. The ID has two parts, separated by a colon: `<module-name>` : The name of the module which contains the dialog definition. `<path>`: Relative path to the dialog definition inside `dialogs` root item. For example the dialog ID `my-module:components/textImage` either points 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.

dialog

optional

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

The ID has two parts, separated by a colon:

<module-name> : The name of the module which contains the dialog definition.
<path>: Relative path to the dialog definition inside dialogs root item. For example the dialog ID my-module:components/textImage either points 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. This is where the bulk on content is entered. But dialogs are also useful for page and area templates. Here are a few suggestions:

Page dialogs:
- Content entry: Use the dialog for content entry that is not necessarily rendered on the page. For example, to enter a meta title and description that is 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.

Configuring secondary actions

The actionArea node lets you provide additional actions and specify a renderer, if required. You need a renderer when the action requires more than just a button (for instance for an upload action).

The choose dialog in the Assets app - 5 UI is an example. The dialog allows editors to upload assets to the DAM while working in other apps.

The configuration is in /modules/dam-app/apps/assets/chooseDialog:

Configuring secondary actions

Property Description

Property	Description
`actionArea`	optional A secondary action area in the bottom left corner of the editor. Contains the action area configuration.
`secondaryActions`	required Add 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 and other actions are on the right side.
`<actionName>`	required Secondary action name.
`actionRenderers`	optional Define a subnode for each action which requires its own renderer.
`<actionName>`	required Name of the secondary action.
`rendererClass`	required A renderer class if the secondary action requires one. Must implement `ActionRenderer`.

actionArea

optional

A secondary action area in the bottom left corner of the editor. Contains the action area configuration.

secondaryActions

required

Add 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 and other actions are on the right side.

<actionName>

required

Secondary action name.

actionRenderers

optional

Define a subnode for each action which requires its own renderer.

<actionName>

required

Name of the secondary action.

rendererClass

required

A renderer class if the secondary action requires one. Must implement ActionRenderer.

Assets chooser

Reusing configuration

Magnolia provides mechanisms to reuse dialogs or more general said to reuse configuration items. See Reusing configuration.

Feedback

DX Core

Dialog definition - 5 UI

Dialog properties

Location of dialog definitions

Referencing dialogs

Using dialogs in templates

Configuring secondary actions

Reusing configuration

Location

Main doc sections