Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

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

These properties apply to all control types.

Property

Description

Default value

controlType

Type of control. Mandatory. This determines which control is rendered. Value can be a type or a class name. For instance, the control type button is associated with class DialogButton so either could be used to specify the type. Some class names correspond to multiple control types such as class DialogButtonSet which corresponds to types checkbox and checkboxSwitch.

Class name if no control type is specified.

name

Name assigned to the control. Optional. Determines the name of the data node where the value entered by the user is stored. If no name is specified, the name of the control's content node is used instead to store the field value. Avoid special characters.

Name of the control node.

required

Makes the field mandatory. Indicated by an asterisk next to the label. Simple validation is applied to the control when this property is set to true. false does not perform any validation. See also Checking for null values.

false

validationPattern

Regular expression pattern used to validate the field value.

 

type

Defines the data type of the stored value. Possible types are String, Boolean, Date, Double, Long or any other support and defined data type.

Most controls set a default value automatically. An exception is the file control for which you need to specify type Binary.

defaultValue

Pre-filled value displayed in the field. The value can be overwritten by the user. Available for all controls except multiselect in Magnolia 4.5.10 and earlier.

 

label

Text displayed as field label. Typically retrieved from a message bundle  .

 

labelDescription

Text displayed below the label providing additional information.

 

description

Text displayed below the input field. Can be used to explain the purpose the control or to provide value examples.

 

line

Draws a line above the control.

true

lineSemi

Draws a line above the input area of a two-column control only, not over the label.

false

i18nBasename

Message bundle for localized field labels. This property is set at the   dialog level , not for individual controls.

Value provided in the dialog definition is used as a default.

i18n

Enables i18n authoring support. This allows authors to write foreign language or regionally targeted content. A two-letter language identifier (en, ge, fr etc.) is displayed on controls where i18n is set to true. Content entered into a localized control is stored in the repository under the same name as the control name property, with a locale identifier appended, for example title_de. Learn more in Language .

In STK controls this property is typically set to true by default.

boxType

Determines the number of columns used. Possible values are 1Col where label is above the input field and 2Col where label is on the left and the input field on the right.

2Col

mgnlSessionAttribute

A session attribute. Add a value here if you want to associate it with the session.

 

saveInfo

Defines whether field data should be saved. The dialog saveHandler performs the save operation.

true

list

Displays the field in a column in AdminCentral when set to true.
Important! This property is only available in the Data module. It is enabled by the GenericDataAdminTreeConfig class.

false

Controls

tab

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

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

Control type: tab

Property

Description

Default

label

Label displayed to the user. This is the text on the tab. Typically retrieved from a message bundle  .

 

API: DialogTab

edit

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

Control type: edit

Property

Description

Default

onChange

Javascript that commits a change in the field value.

 

rows

Number of text rows.

1

width

Width of the input field. Values can be in percentages (100%) or pixels (150px)

100%

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

Property

Description

Default

useCodeHighlighter

Enables syntax highlighting. When disabled, falls back to a plain textarea with a fixed-width font. In that case the language, readOnly and lineNumbers options will have no effect.

true

language

Enables syntax highlighting for a specific programmming language. Supported languages supported are javascript or js, css, html, groovy and freemarker or ftl. Default value is generic which will colorize html, js and css.

generic

readOnly

Makes the editor read-only.

false

lineNumbers

Displays line numbers.

true

rows

Determines the number of rows initially shown.

20

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

Encourage editors to use Paste as plain text as opposed to Paste from Word to avoid potential CSS issues. The latter occasionally wraps the text in <div> elements causing font size reduction. Alternatively, you can set FCKConfig.ForcePasteAsPlainText = true in magnoliaStandard.js, but this will also disable the button.

Property

Description

Default

fonts

Displays a font dropdown. Value is a list of font names separated by a semicolon.

none

fontSizes

Displays a font size dropdown. Value is a list of sizes separated by a semicolon

none

alignment

Enables the alignment buttons (left, center, right) when set to true.

true

colors

Enables the font color palette. To disable the button, delete the property.

 

css

Cascading style sheet (CSS) applied to the edited text. The standard Magnolia CSS is used as a default. Other CSS locations can be specified.

/.resources/fckeditor/custom/
css/magnoliaStandard.css

styles

Enables the styles dropdown. Value is a URI reference to an fckEditor style XML file. Styles displayed in the dropdown are defined in the XML file. See Styles in FCKEditor documentation.

none

templates

Enables the templates dropdown. A template is a piece of HTML that is placed inside the editor, in this way the user doesn't need to start writing it from scratch. See Templates in FCKEditor documentation.

none

height

Height of the control in pixels.

200

width

Width of the control in pixels.

543

images

Enables the image feature that allows users to insert images and Flash files in the text.

false

tables

Enables a table editor.

false

source

Enables the source code button which allows the user to edit the HTML source of the text.

false

lists

Enables bulleted and numbered lists. This property is used by other properties such as colors, fonts and fontSizes.

true

fileUpload

Enables a file upload control.

true

spellChecker

Enables a spellchecker. Spell checking is disabled by default. You can choose from a number of third party services to do the checking:

  • ieSpell - A Spell Checker for Internet Explorer
  • SpellerPages - Open source Web spell checker
  • WSC - Web Spell Checker provided by SpellChecker.net
  • SCAYT - Spell Check as You Type provided by SpellChecker.net
    See FCKEditor spell check documentation for details.
    If you specify an invalid value, an alert will be shown to the user. This won't prevent fckEditor from working, only the spell checking feature will not be available.

 

showSpellChecker

Show the spellchecker button.

true. Button is only displayed if you define a spellChecker too.

jsConfigFile

Custom JavaScript configuration file used by FCKEditor. Value is a path to the .js file. The value is used to set FCKEditor's CustomConfigurationsPath property. You can use this feature when normal configuration options are not enough. See FCKEditor configuration options.

/.resources/fckeditor/custom/
config/magnoliaStandard.js

jsInitFile

Code for initializing the fckEdit control. Alternatively, JavaScript object fckInstance can be used. This code is executed before the fckInstance.Create() call.

/.resources/fckeditor/custom/
init/magnoliaStandard.js

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.

In the Data module  , use the dataFile control instead of the file control.

Control type: file

Property

Description

Default

type

Data type the value is stored as. You must set this to Binary or the control will not work.

 

nodeDataTemplate

Template to use to render the stored binary code. Since the file control is not frequently used, the nodeDataTemplate property is also used infrequently.

 

width

Width of the text field where the file name is displayed.

100%

preview

Controls whether a thumbnail preview of the saved digital file is displayed in the dialog. Preview rendering is supported for jpg, jpeg, gif, png, bmp and swf files. If the property is set to false a basic MIME type icon is displayed.

true

readonly

Hides the Remove file button, filename and extension to prevent editing.

false

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.

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

Property

Description

Default

repository

Repository to browse such as website, dms or data.

website

extension

Optional file extension that is added to the link.

 

tree

Tree to browse. This property allows you to set a starting point for the browsing. The value needs to be the name of the tree configuration. See wiki for instructions on how to open a specific path in a repository. In the data repository the tree property is included automatically when the control is created. In the website and dms repositories it needs to be created manually to limit users to a specific tree.

Name of the repository.

buttonOnClick

Name of the JavaScript function executed to activate the browsing function. Typically left empty for Magnolia standard tree browsing. This can be customized for specific functionality.

 

width

Width of the input field. Values can be percentages (100%) or pixels (150px).

100%

API: DialogLink

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

Property

Description

Default

repository

Repository to browse such as website, dms or data.

website

extension

Optional file extension that is added to the link.

 

tree

Tree to browse. This property allows you to set a starting point for the browsing. The value needs to be the name of the tree configuration. See wiki for instructions on how to open a specific path in a repository. In the data repository the tree property is included automatically when the control is created. In the website and dms repositories it needs to be created manually to limit users to a specific tree.

Name of the repository.

buttonOnClick

Name of the JavaScript function executed to activate the browsing function. Typically left empty for Magnolia standard tree browsing. This can be customized for specific functionality.

 

width

Width of the input field. Values can be percentages (100%) or pixels (150px).

100%

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

Property

Description

Default

time

Enables time selection in addition to date.

false

dateFormat

Date format adhering to SimpleDateFormat patterns.

yyyy-MM-dd

timeFormat

Time format adhering to SimpleDateFormat patterns.

HH:mm:ss

jsDateFormat

Date format using the DHTML calendar widget's date format syntax.

%Y-%m-%d

jsTimeFormat

Time format using the DHTML calendar widget's time format syntax.

%h-%M-%S

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

Property

Description

Default

cssClass

CSS class to use for the control. Can be changed from the default to a custom CSS.

mgnlDialogButtonsetButton

cols

Determines the number of columns the options are arranged in. Not applicable to the select control.1 for one column, 2 for two columns.

1

labelNodeData

Reads a label from an alternate nodeData control. The default setting for this control is the label for the individualOption node which as a default is the same as the value stored in the nodeData property).

 

options

The options property is a content node which contains the selectable options subnodes.

 

    value

Value is stored internally in the JCR. The label is displayed to the user.

 

    name

Name of the node that stores the selected value. If this property is not set, the name of the option content node is used instead.

 

    selected

Sets the option as pre-selected. Setting this to true will select the radio button or dropdown option by default. (Note: Not implemented for checkbox)

 

    label

The human-readable label for this option.

 

    iconSrc

Displays an image next to the option. Value is a path to the image.

 

path

Instead of defining the options in the control you can reference an existing option set. This property identifies a path to the substitute configuration nodes.

 

repository

When using path to reference an existing option set, the system looks for the path in the config workspace by default. You look in other workspace by setting the repository property.

config

valueNodeData

Read option values from a different data node. Set this property to the name of your custom value node.

value

labelNodeData

Read option labels from a different data node. Set this property to the name of your custom label node.

label

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

Property

Description

Default

selected

Determines whether checkbox is selected on opening.

true

buttonLabel

Allows you to include a label next to the checkbox.

 

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

Property

Description

Default

chooseOnClick

JavaScript executed when a button is clicked. If no JavaScript is assigned to this property, no button is rendered.

Standard repository browser mgnlOpenTreeBrowserWithControl

tree

Defines the tree to be browsed. Inclusion of this property activates the browsing feature

 

saveMode

Specifies the structure the data will be saved in. Possible values are:

  • list. Comma delimited list.
  • json. JSON (JavaScript Object Notation) style. Useful when one entry contains multiple values (one-to-many relationship)
  • multiple. Child node created for each entry, complete with associated properties.

multiple

 (warning) Magnolia 4.5.10+. The defaultValue property that is common to all dialogs is also available for the multiselect control and supports a single defaultValue.

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

Property

Description

Default

onclick

JavaScript executed when the button is clicked.

 

buttonLabel

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

buttonLabel

small

By default a large button is rendered. The size can be reduced by setting this property to true.

false

API: DialogButton

static

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

Control type: static

Property

Description

Default

value

Text displayed next to the label control.

 

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

Property

Description

Default

defaultValue

Specifies a default value.

 

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

Property

Description

Default

onChange

JavaScript to execute when value is changed.

 

verification

Verifies that the contents of the two boxes match. When set to false the verification box is not rendered.

true

width

Width of the input field. Values can be in percentages (100%) or pixels (150px).

100%

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

Property

Description

Default

onChange

JavaScript to execute when value is changed.

 

verification

Verifies that the contents of the two boxes match. When set to false the verification box is not rendered.

true

width

Width of the input field. Values can be in percentages (100%) or pixels (150px).

100%

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

Property

Default

Description

file

The default for this control property is blank or empty.

This property allows the URI for the include property to be specified. Normally this is a .jsp file.

freemarker

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

Control type: freemarker

API: DialogFreemarker

Property

Default

Description

path

 

Path to the Freemarker script.

multiple

false

Store a single value or multiple values. Depends on the type of HTML control you are rendering.

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.

Parameter

Description

value

A single field value entered by the user if multiple=false. You can access the in the Freemarker script with ${value}.

values

Multiple field values entered by the user if multiple=true. In this case ${values} is retrieved as a list. Use [#list values as item] to iterate and get the individual values.

requestCurrent HTTPServletRequest.
configurationA complex dialog configuration is provided to the script as a map.

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.

(warning) 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 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.

Checking for null values

Best practice

Define default values for controls or check for null values. This ensures that you can submit the form. For example, if you define an optional radio button and don't provide a default value, an error occurs when a user submits the form by mail. The email processor does not check for null value in the template. It is good practice to check for null values of any variables you call.

You can check for null values and provide a default value in a Freemarker script like this:

field: ${field!"value not provided"}

Creating a custom control

See Creating a custom control.