Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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.
A dialog definition contains a form
and actions
.
Here's what the configurations do:
Example: Simple dialog definition:
form: tabs: - name: tabText label: Text fields: - name: title class: info.magnolia.ui.form.field.definition.TextFieldDefinition label: Title actions: commit: class: info.magnolia.ui.dialog.action.SaveDialogActionDefinition label: Save cancel: class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition label: Cancel
Node name | Value |
---|---|
modules | |
<module name> | |
dialogs | |
<dialog name> | |
form | |
tabs | |
tabText | |
fields | |
title | |
class | info.magnolia.ui.form.field.definition.TextFieldDefinition |
label | Title |
label | Text |
actions | |
commit | |
class | info.magnolia.ui.dialog.action.SaveDialogActionDefinition |
label | save |
cancel | |
class | info.magnolia.ui.dialog.action.CancelDialogActionDefinition |
label | close |
Nodes:
<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 |
| required Contains a form definition which defines the fields where content is entered. |
| 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. |
| optional Modality level defines how intrusive the dialog is. Valid values are |
| optional Allows you to configure secondary actions. |
| optional , default is
Click the expand/collapse button in the top right corner to toggle between the wide and normal (720px) modes. |
| optional ( |
YAML file path | JCR node path in config workspace | |
---|---|---|
Dialog definition | $magnolia.resources.dir/<module-name>/dialogs | /modules/<module-name>/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.
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:
dialog | optional Dialog definition ID in The ID has two parts, separated by a colon:
|
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:
<head>
element, or a page excerpt for use in teaser components on other pages.noComponent
areas.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 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
:
Node name | |
---|---|
chooseDialog | |
actions | |
commit | |
cancel | |
upload | |
uploadAndEdit | |
actionArea | |
secondaryActions | |
upload | |
uploadAndEdit | |
actionRenderers | |
upload | |
rendererClass | info.magnolia.dam.app.assets.field.UploadAssetActionRenderer |
uploadAndEdit | |
rendererClass | info.magnolia.dam.app.assets.field.UploadAndEditActionRenderer |
actionArea | optional A secondary action area in the bottom left corner of the editor. Contains the action area configuration. |
| required Add subnodes to match the secondary actions defined in the |
| required Secondary action name. |
| optional Define a subnode for each action which requires its own renderer. |
| required Name of the secondary action. |
| required A renderer class if the secondary action requires one. Must implement |
Magnolia provides mechanisms to reuse dialogs or more general said to reuse configuration items. See Reusing configuration and Generic tab for a dialog.
optional
Sets the dialog's caption via a property holding the preferred value, for example via the jcrName
property.