The Magnolia authoring system uses dialogs for content contribution and control. A dialog is an HTML form with input fields. Authors type content into the input fields and the dialog stores it in the repository. Dialogs can be used to edit area and component content. In addition to content entry, the system provides standard dialogs for page properties, data nodes, users, roles, workflow notifications and many other editable items. It is a flexible mechanism that allows you to create your own dialogs and customize the standard dialogs.

• Dialog definition
• Properties
• Tabs
• Configuring a dialog
• Referencing a dialog definition
• Adding dialog content on a page

Dialog definition

Below is an example dialog definition for the Text and Image component. You can access the definition in Templating Kit > Dialog Definitions /components/content/stkTextImage.

1. stkTextImage is the internal name used when referencing this dialog from the template definition. i18nBasename defines a message bundle. The bundle is a collection of properties files inside the module .jar that contain default labels for dialogs and fields. A key will retrieve the matching label from the bundle. For example, the key dialogs.paragraphs.content.stkTextImage.label retrieves the dialog title "Text and Image". Storing field labels in a property file has the advantage that you can hand the file to a translator when a new UI language is needed. Alternatively, you can type a label here.
2. tabText is the first tab in the dialog.
3. subtitle is the first control on the tab. It is an edit control, rendered as a text box (see screenshot above). A description is displayed below the text box. i18n is enabled which means a language suffix (en, de, fr...) is displayed next to the field label and the dialog stores language specific content.
4. text is a rich text edit control. It's a very common control with many configuration options. To ensure that all rich text edit controls are configured the same way, we define it once in the generic controls folder and extend when needed.

Properties

Tabs

Dialogs are assembled of tabs and controls. Text and Image is a typical component-editing dialog. It has two tabs: Text and Image.

The Text tab contains a simple edit control for a subheading and an fckEdit rich-text control for text. Note how internationalization support is enabled in this dialog: the field label "(en)" indicates that English language content should be entered.

The Image tab allows for the selection of an image to accompany the text. A radio button control chooses between uploading the image from the local computer and selecting it from the document management system.

Configuring a dialog

A typical Magnolia CMS installation includes a standard set of dialogs. In many cases it is not necessary to create a new dialog from scratch; you can copy or extend an existing dialog and adapt it to your needs. Sample dialogs are provided in the Standard Templating Kit, Templating and Templating Samples modules.

A dialog definition defines the dialog's tabs and fields. Typically configuring a dialog involves two steps:

1. Create a dialog definition.
2. Reference the dialog definition from the page, area or component template definition.

Referencing a dialog definition

A page, an area or a component template definition references its dialog definition. This means that when an editor edits the page, area or component the referenced dialog is displayed.

The stkTextImage component definition references its counterpart dialog by an internal name stkTextImage. You can find the component definition in Templating Kit > Template Definitions /components/content/stkTextImage.

The reference to a dialog is in the dialog node. The value has two parts. The first part before the colon (:) is the name of the module folder where the dialog definition resides. The second part is a relative path, for example <module name>:<relative path to dialog>. In this case the dialog is defined in the Standard Templating Kit module so the first part is standard-templating-kit. The relative path always starts from inside the dialogs folder. The stkTextImage dialog definition is in the components/content subfolder.

All STK templates reference a page properties dialog opened by clicking Properties in the top bar. This is how the stkArticleProperties dialog is assigned to the stkArticle template available in Templating Kit > Template Definitions /pages/stkArticle.

A dialog can also be referenced from an area template definition which is configured within the page template definition. This is not a very common use case. You can find a sample configuration in Configuring page reuse at item 3.

Adding dialog content on a page

Since the matching dialog is identified in the template definition, the script does not need to know this detail. The reference between the template definition and the dialog definition takes care of opening the correct dialog.

This is how the textImage.ftl script renders the content of the subtitle and text controls. Plain text dialog content is rendered using the content.<field name> notation and the cmsfn.decode method escapes the HTML of the text field. You can access the script in Templating Kit > Templates > /components/content/textImage.

[#if content.subtitle?has_content]
   <h2 ${id}>${content.subtitle}</h2>
[/#if]
[@image image=model.image! imageClass=model.imageClass/]
[#if content.text?has_content]
   ${cmsfn.decode(content).text}
[/#if]

This is how the htmlHeader.ftl script renders the content of the controls in tabMetaData of any properties dialog. Note how the abstract content is used if no description exists. You can access the script in Templates /templates/pages/global.

<meta name="keywords" content="${content.keywords!content.title!content.@name}" />
<meta name="description" content="${content.description!content.abstract!}" />