Controls

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.

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.

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

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

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

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

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.
`request`	Current HTTPServletRequest.
`configuration`	A 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.

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.

Page tree

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

Checking for null values

Creating a custom control