Components

A component is the smallest block of content that editors can edit, delete and move as a single unit on the page. At its simplest a component may be just text. However, a component can contain almost anything: a related image, a list of links or a teaser to another page. Components render content entered by editors in dialogs.

A basic component has three building blocks:

Component definition in the Configuration >/<module name>/templates/components folder.
Template script to render the component. Referenced in the templateScript property of the definition.
Dialog for content entry. Referenced in the dialog property of the definition.

Node name	Value
modules
standard-templating-kit
templates
components
content
stkTextImage
parameters
description	paragraphs.content.stkTextImage.description
dialog	standard-templating-kit:components/content/stkTextImage
i18nBasename	info.magnolia.module.templatingkit.messages
modelClass	info.magnolia.module.templatingkit.templates.components.TextImageModel
renderType	stk
templateScript	/templating-kit/components/content/textImage.ftl
title	paragraphs.content.stkTextImage.title

Properties

Component properties common to all components are defined by the ConfiguredRenderableDefinition class as extended by the ConfiguredTemplateDefinition class. If specific subclasses are used, additional properties can be available.

You can use these common properties in any component definition:

Property	Description	Valid values
`class`	Optional. Defines the concrete Java class to instantiate.	Fully-qualified class name. This property needs to be in appropriate Magnolia class syntax.
`deletable`	Optional. Determines if component can be deleted. Set to `false` to prevent editors deleting the component.	`true` (default), `false`
`description`	Optional. Component description. Type a literal value or retrieve the value from a message bundle using a key. The message bundle is defined in the `i18nBasename` property.	No limitations. Conventional alphanumeric characters are recommended. Otherwise a properly defined key.
`dialog`	Optional. Path to the dialog associated with the component.	`<module name>:<path to dialog>` format. Conventional syntax for path definitions.
`escapeHtml`	Escapes any HTML code entered into the component if the component is a form input field. This is a security feature that prevents XSS attacks. Default is `true` for all form fields except password where default is `false`. Magnolia 5.2.9+ / 5.3.4+	`false` `true`
`i18nBasename`	Optional. Message bundle used for the component.	Any properly defined message bundle. This value should match the message bundle set in the dialog definition.
`modelClass`	Optional. Class that contains business logic for the component. The class needs to implement the RenderingModel interface. The renderer creates a bean based on the `modelClass`. Current content, definition and the parent model are passed to the constructor. This object is instantiated for each rendering of a page or component.	Fully-qualified class name. This property needs to be in appropriate Magnolia class syntax and specifically refer to the `modelClass` for the component.
`moveable`	Optional. Determines if component can be moved. Set to `false` to prevent editors moving the component.	`true` (default), `false`
`renderType`	Determines which renderer to use. Out of the box, Magnolia supports JSP and Freemarker renderers. The type for STK components is `stk`. The Standard Templating Kit module defines its own component renderer, `STKRenderer`.	`jsp` `freemarker`
`templateScript`	Path to the template script used by the component. Template scripts can be stored on the file system of the webapp, in the `templates` workspace, or in the webapp's classpath.	Conventional syntax for path definitions.
`title`	Optional. Title of the component. Type a literal value or retrieve the value from a message bundle using a key. The message bundle is defined in the `i18nBasename` property.	If typed, no limitations. Conventional alphanumeric characters are recommended. Otherwise a properly defined key.
`writable`	Optional. Determines if component can be edited. Set to `false` to prevent editors editing the component.	`true` (default), `false`

In the skeleton below, mandatory properties are red and optional properties are black.

Node name	Value
<component name>
parameters
<custom param>
areas
<area name>
class	<fully qualified class name>
deletable	<true \| false>
description	<description text>
dialog	<module>:<path>
i18nBasename	<message bundle>
modelClass	<fully qualified class name>
moveable	<true \| false>
renderType	<stk \| fremarker \| jsp>
templateScript	</path/to/template/script>
title	<key in message bundle>
writable	<true \| false>

Parameters

Parameters can be made available to the template script in the /<component name>/parameters node of the component definition. These properties can have arbitrary names. For example, the catCloud component includes divClass and headingLevel properties.

Node name	Value
modules
categorization
templates
components
catCloud
parameters
divClass	tagCloud
headingLevel	h3

This is how the parameters are rendered by the categoryCloud.ftl script.

[#-------------- RENDERING PART --------------]
[#-- Rendering: Category Cloud --]
<div class="${divClass}" ${divID}>
    [#if has_categories]
        [#if catCloudTitle?has_content]<${def.headingLevel!"h3"}>${catCloudTitle}</${def.headingLevel!"h3"}>[/#if]
        <ul>
            [#list categories as item]
                [#-- Macro: Item Assigns --]
                [@assignItemValues item=item /]
                <li class="${itemLevel}">
                    <a href="${itemLink}" >${itemDisplayName}</a>
                </li>
            [/#list]
        </ul>
    [/#if]
</div>

Reference

Each Magnolia module can provide its own components. You can reuse and extend them to provide your own.

Page tree

Properties

Parameters

Reference

Related documentation