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

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

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 nameValue

 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.

deletableOptional. 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.

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

moveableOptional. 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.

writableOptional. 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 nameValue

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

 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.

Related documentation

Here's a list documentation relevant to components:

  • No labels