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

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

Defines the concrete Java class to instantiate.

Fully-qualified class name. This property needs to be in appropriate Magnolia class syntax.

deletableDetermines if component can be deleted. Set to false to prevent editors deleting the component. (warning) 4.5.9+true (default), false

description

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

Path to the dialog associated with the component.

<module name>:<path to dialog> format. Conventional syntax for path definitions.

i18nBasename

Message bundle used for the component.

Any properly defined message bundle. This value should match the message bundle set in the dialog definition.

modelClass

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.

moveableDetermines if component can be moved. Set to false to prevent editors moving the component. (warning) 4.5.9+

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

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.

writableDetermines if component can be edited. Set to false to prevent editors editing the component. (warning) 4.5.9+true (default), false

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

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.

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