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

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

Property

Description

Default value

Acceptable values

label

Title of the dialog displayed to the user.

Dialog.editTitle

No limitations. Conventional alphanumeric characters are recommended.

width

Dialog box width in pixels. This property can be edited after the dialog is created.

800

Limited by user's screen resolution.

height

Dialog box height in pixels. This property can be edited after the dialog is created.

650

Limited by user's screen resolution.

saveLabel

Text displayed on the Save button.

buttons.save

Short and descriptive since it will be displayed on a button.

saveOnclick

JavaScript to be executed when user clicks the Save button

mgnlDialogFormSubmit()

Reference to a JavaScript with appropriate functionality.

cancelLabel

Text displayed on the Cancel button.

buttons.cancel

Short and descriptive since it will be displayed on a button.

cancelOnclick

JavaScript to be executed when user clicks the Save button

Window.close()

Reference to a JavaScript with appropriate functionality.

i18nBasename

Message bundle used for the dialog. See Language.

info.magnolia.module.
admininterface.messages

Any message bundle.

name

Optional name for the dialog. Not necessary. By default the content node name is used.

Name of the dialog content node.

No limitations. Conventional alphanumeric characters are recommended.

class

This is the dialog handler class and is generally a sub-class of the configured dialog class or of  ConfiguredDialog . This class facilitates the creation, validation and saving of the dialog.

ConfiguredDialog

This property needs to be in appropriate Magnolia class syntax and specifically refer to the class for the dialog.

saveHandler

Class to be used as the save handler for the dialog. saveHandler interface. 

UUIDSaveHandler

This property must specify a defined class that will be used as the SaveHandler class for the dialog.

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 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:

Create a dialog definition.

Reference the dialog definition from the page, area or component template definition.

Referencing a dialog definition

A page, area or 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!}" />
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels

To comment, create an account and log in.

© Copyright 2023 Magnolia