A control is an HTML form element that allows the user to perform a task such as enter text, upload an image or select a date. Controls are assembled into tabs and tabs into dialogs. Magnolia is delivered with a number of controls which should fulfill most needs. It is also possible to create custom controls.

• Common properties
• Controls
• tab
• edit
• editCode
• fckEdit
• file
• dam
• link
• uuidLink
• date
• radio, checkbox and select
• checkboxSwitch
• multiselect
• button
• static
• hidden
• password
• passwordHash
• include
• freemarker
• Extending configuration
• Override
• Examples
• Creating a custom control

Common properties

These properties apply to all control types.

Controls

tab

Tab is a control that lets you organize a dialog into a tabs. All other controls are located inside a tab control.

You need at least one tab into your dialog. Controls cannot be added to a tabless dialog.

Control type: tab

Label displayed to the user. This is the text on the tab.

API: DialogTab

edit

The edit control renders an editable text field that allows for single or multiple rows of text.

Control type: edit

API: DialogEdit

editCode

Source code editing control that provides real-time syntax highlighting and line numbers. Under the hood, it uses the CodeMirror (since Magnolia 4.4.2 it replaces CodePress) JavaScript library.

Control type: editCode

KNOWN ISSUE: setting the control's width with the cols option currently does not work.

API: DialogEditCode

fckEdit

fckEditor is a configurable rich text editor which allows users to format text, insert links, tables and images. It has functions similar to word processing applications. See also How to configure fckEditor.

Control type: fckEdit

API: FckEditorDialog

file

The file control allows the user to browse to and upload a digital file. This control is not used very often as the dam control also offers the same functionality and more.

Control type: file

API: DialogFile

dam

The dam control allows a user to upload files or browse for a file stored in the DMS. It is commonly used as an image picker but can be used to locate Flash and videos.

The control is configured in the Standard Templating Kit module in /modules/standard-templating-kit/controls.

Control type: dam

The dam control relies on damHandlers which are configured in the Extended Templating Kit module at /modules/extended-templating-kit/config/sites/default/damSupport/handlers. Handlers for file upload and selecting from the DMS are provided by default.

link

The link control allows you to create a link to content stored in Magnolia. You can browse any specified repository and select a content node to link to such as a page (website), file (dms) or data item (data).

The link control differs from the uuidLink control in that the former stores a path and the latter the universal unique identifier (UUID) of the target content node.

Control type: link

API: DialogLink

uuidLink

The uuidLink control is identical in all respects to the link control except that the link value is stored as a UUID of the target content node as opposed to a path. Links stored as UUIDs remain valid even if the target is moved. All properties applicable to the link control are equally applicable here.

Control type: uuidLink

API: DialogUUIDLink

date

The date control allows a date and time to be selected. In order for the date control to work, the type must be set to Date so that the value will be saved as a Calendar object instead of a String.

Control type: date

Type: Date

Always set the properties as a pair: if you set jsTimeFormat set also jsDateFormat, not dateFormat.

API: DialogDate

radio, checkbox and select

radio, select and checkbox controls are configured very similarly. The difference between these three controls is the controlType.

The individual options are child content nodes of an options content node.

Control type: radio, checkbox or select

API: DialogSelect

checkboxSwitch

The checkboxSwitch control provides a simpler alternative to the checkbox control when only a single checkbox or option is appropriate.

Control type: checkboxSwitch

API: DialogButtonSet

multiselect

The multiselect control allows the user to select multiple values in a single field. Depending on the configuration, it can be used to store multiple text entries or multiple internal links. In the latter case, the user can browse for the link target using the repository explorer.

This control is commonly used in Magnolia security to assign multiple roles and groups to a user.

Control type: multiselect

In the Data module, the dataMultiSelect control should be used instead of multiselect. The Data module offers also a dataUUIDMultiSelect control stores values as UUIDs.

API: DialogMultiSelect

button

The button control renders an HTML button in the dialog.

Control type: button

API: DialogButton

static

The static control renders non-editable text that displays a value next to the label.

Control type: static

API: DialogStatic

hidden

The hidden control defines a hidden field. No field is rendered in the dialog and the control itself does not have any properties of its own. The only relevant generic property is defaultValue.

Hidden fields can be useful on forms to collect variables that are not filled in by the user, for example a session ID, language preference or IP address. Even though the field is not rendered or available to the user, the data collected is stored in the repository and can be viewed in the JCR Browser.

The hidden field is used in STK for example in the stkTeaserPureLinkList component which renders a list of text links. Unlike most teasers, the component does not render a teaser image. A hidden control is used to set the hideTeaserImage property to true.

Control type: hidden

API: DialogHidden

password

The password control renders two text input boxes designed for entry and verification of passwords. For security purposes, the input text is disguised with asterisks and the plain text password is saved using Base-64 encoding.

API: DialogPassword

Control type: password

passwordHash

The passwordHash control renders the same password box as the password control but is more secure. The control stores cryptographic Bcrypt hash of the password rather than the password itself. Since the website does not know the password it cannot send it to the user in email if the user forgets their password. The website can only send the user a reset password link. If you use the passwordHash control for public user registration then you should set up a password retrieval strategy that sends a reset link.

API: DialogPasswordHash

Control type: passwordHash

Amend

include

The include control allows a JSP or other URI to be called and rendered in the dialog. The use of this control is described in wiki article Creating a custom control with DialogInclude.

API: DialogInclude

Control type: include

freemarker

The freemarker control renders a Freemarker script. You can use it to render HTML controls that Magnolia CMS does not provide out of the box.

Control type: freemarker

API: DialogFreemarker

The control passes parameters to the Freemarker script. For example, the value parameter is useful for setting the field to the value that was provided previously.

Here is an example of how the configuration parameter works. This dialog configuration:

+ myDialog
  + contentNode1
    - property1 = value1
    - property2 = value2
    + contentNode2
      - property3 = value3
  - property4 = value4

Would be provided to the script as a map like this.

configuration = Map {
  "contentNode1"  = Map {
    "property1" = "value1",
    "property2" = "value2",
    "contentNode2"  =  Map {
      "property3" = "value3"
      }
  },
  "property4" = "value4"
 }

Here is a Freemarker script that renders an HTML5 color input control.

<input 
  type="color" 
  name="favoriteColor" 
  id="favoriteColor" 
  value="${value}">

Extending configuration

With an extends property you can point to a source configuration and inherit dialog configuration from the source. This can save some time and effort as you only need to define additions and exceptions explicitly. Extending is a mechanism used widely in site definitions.

Note In STK dialogs you may also see a reference property used to do the same thing. This property is now deprecated. Please use extends instead.

To extend a configuration, add an extends property to the relevant element in your configuration and set its value to the absolute path to the source configuration.

The example below extends the stkTextImage dialog by adding an image tab to it. The image tab is inherited through extension from the generic tab configured at /modules/standard-templating-kit/dialogs/generic/controls/tabImage.

Override

Setting the value of the extends property to override allows the extending node to completely remove the inherited configuration. The stkPromo component uses this feature. It inherits its configuration from the stkTeaser component but an override under the areas node prevents the linkList area from being inherited.

Learn more about overrides.

Examples

Templating Samples module includes examples of many controls. The module .jar file is in the add-ons folder under your Magnolia CMS installation. You can also download it from the Magnolia Store. Follow standard module installation instructions.

After installation you can find a dialog definition in /modules/samples/dialogs/controlsShowRoom.

To see the rendered dialog, open any of the samples pages in Website workspace and add the Controls sample component on the page.

Creating a custom control