The 5.7 branch of Magnolia reached End-of-Life on December 31, 2023, as specified in our End-of-life policy. This means the 5.7 branch is no longer maintained or supported. Please upgrade to the latest Magnolia release. By upgrading, you will get the latest release of Magnolia featuring significant improvements to the author and developer experience. For a successful upgrade, please consult our Magnolia 6.2 documentation. If you need help, please contact info@magnolia-cms.com.

Light developers can use the create-component command in the Magnolia CLI to create page templates.

A component is the smallest block of content that editors can edit, delete and move as a single unit on the page. A component definition is similar to a page definition and uses the same definition object. You can configure a template in a YAML file or a JCR node.

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

Component properties

Simple example definition:

my-module/templates/components/text.yaml
renderType: freemarker
templateScript: /my-module/templates/components/text.ftl
dialog: my-module:components/text
modelClass: com.example.templates.TextComponentModel
deletable: false
moveable: false
personalizable: false
class: com.example.templates.TextComponentDefinition
Node nameValue

 
text

 

 
class

com.example.templates.TextComponentDefinition

 
deletable

false

 
dialog

my-module:components/text

 
modelClass

com.example.templates.TextComponentModel

 
moveable

false

 
personalizable

false

 
renderType

freemarker

 
templateScript

/my-module/templates/components/text.ftl

You can use common template properties and the following properties in a component definition:

deletable

optional, default is true

Determines if component can be deleted. Set to false to prevent editors deleting the component.

escapeHtml

optional, default is true

Escapes any HTML code entered into the component if the component contains an input field. This is a security feature that prevents XSS attacks. Default is true for all form fields except  password where default is false.

fragmentDefinition

optional (EE only)

Allows you to mark a component as dynamic. See Advanced Cache Dynamic Page Caching and SiteMesh module.

Properties:

  • class: info.magnolia.module.advancedcache.rendering.DynamicFragmentDefinition (Git) supports an advanced definition for dynamic fragments.
  • cacheKeyGeneratorClass: Cache key generator class. Default is null.
  • dynamic: Enables and disables dynamic caching. Default is true .
  • mechanism: Mechanism used. Sitemesh mechanism is supported. Default is null.
  • ttl: Time to live setting. Default is 0 .
moveable

optional, default is true

Determines if component can be moved. Set to false to prevent editors moving the component.   

personalizable

optional (5.4.9+ EE Pro), default is true

Determines if component can be personalized. Set to false to prevent editors personalizing the component. 

writable

optional, default is true

Determines if component can be edited. Set to false to prevent editors editing the component.   

Location of component definitions

Put your component definitions here:

  • YAML file: $magnolia.home/<module-name>/templates/components
  • JCR node: /modules/<module-name>/templates/components

Component templates can be provided by more than one module, and you can configure new component definitions in existing modules.

Component availability

Component availability is configured in an area definition. The area can then be used on many page definitions.

Configure a content map of components in each area definition using the id property to link to the component definition. See Restricting component availability in an area template.

Nested components

You can create composite components with nested subcomponents. The nested components are configured under an areas item or node. This part of the configuration follows the same pattern as an area definition.

Example: Two link components inside a composite link list component.

/my-module/components/linkList.yaml
renderType: freemarker
templateScript: /my-module/components/linkList.ftl
dialog: my-module:components/compositeLink
i18nBasename: info.magnolia.module.my-module.messages
title: components.compositeLink.title
description: components.compositeLink.description
areas:
  linkList:
    type: list
    templateScript: /my-module/components/linkList.ftl
    title: components.compositeLink.title
    description: components.link-list.description
    availableComponents:
      internalLink: 
        id: my-module:components/internalLink
      externalLink: 
        id: my-module:components/externalLink  
Node nameValue

 
compositeLink

 

 
areas

 

 
linkList

 

 
availableComponents

 

 
internalLink

 

 
id

my-module:components/internalLink

 
externalLink

 

 
id

my-module:components/externalLink

 
templateScript

/my-module/components/linkList.ftl

 
type

list

 
dialog

my-module:components/compositeLink

 
renderType

freemarker

 
templateScript

/my-module/components/linkList.ftl

Nodes and properties:

<component name>  

areas

Marks the configuration as an area.

<area name>

 

availableComponents

Components available in the area.

<component name>

Map of nested components available in the area.

id

Component definition ID in <module-name>:<path to component definition> format.

<area properties>

All properties available in list and single area definitions can be used.

<component properties>

All properties available in component definitions can be used.