Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
Areas control page structure. An area definition defines what components editors can add in the area and how many. Areas also provide repeatability: an area template typically loops through the components inside it, rendering them one by one. Define areas inside your page definitions. You can configure an area definition in a YAML file or a JCR node.
Where to define areas
Areas are defined in a page definition, inside the areas
item:
areas: header: # header area configuration content: # content area configuration footer: # footer area configuration
Node name | Value |
---|---|
my-module | |
templates | |
pages | |
home | |
areas | |
header | |
content | |
footer |
Area properties
Simple area definition:
areas: content: renderType: freemarker type: list availableComponents: text: id: my-module:components/text optional: false
Node name | Value |
---|---|
areas | |
content | |
availableComponents | |
text | |
id | my-module:components/text |
optional | false |
renderType | freemarker |
type | list |
You can use common template properties and the following properties in an area definition:
<area‑name> | required Area names must be unique within a page definition. This means, you cannot have two areas named |
| required , default is Type of the area. Defines whether editors can add components inside the area and how many:
|
| required for A map of components that editors can add in the area. Reference a component by its ID: |
| optional, default is Makes the area optional. |
| optional, default is Typically this property is used in reverse. By setting the value to |
| optional Maximum number of components an editor can add to the area. Only applicable to |
| optional, default is When set to By setting it to |
| optional, default is Creates a node for the area in the repository. Set the property to |
| optional , default is the parent area item's name Name of the area. Identifies the area so the page can call it to be rendered. |
| optional Inheritance renders the area's components on child pages automatically. Inheritance saves time and effort and helps you display content consistently across the site. See Component inheritance. |
| optional Creates components inside the area automatically without editor involvement. Anything you define inside the |
| optional (EE only) Allows you to mark an area as dynamic. See Advanced Cache and Sitemesh modules for more.Properties:
|
Setting the area type
The type
property determines what is rendered in the area:
single
area renders a single component. You can make many components available to editors, but they can only add one. This area type works well in areas designed to grab the visitor's attention. For example a flashy stage at the top of a home or section page, or templates designed for a specific purpose like an image gallery.list
area renders multiple components that are displayed sequentially. You can make one or more components available to editors, and by default they can add as many as they like. You can limit the number of components with themaxComponents
property. List areas work best where you want to give editors a lot of freedom, for example in a news template. One news article may have a mix of images, text, videos, embeds and feeds, whereas another may need only text.noComponent
area does not make any components available to editors. Use this area type for content that is generated automatically, not edited. Examples include rendering content entirely by a script, code-generated content like a breadcrumb or search box, and content that is not displayed to visitors such as a meta title and description.
This example shows a minimal configuration of the three area types.
areas: intro: type: single availableComponents: styledIntroText: id: my-module:components/styledIntroText main: availableComponents: textImage: id: my-module:components/textImage blockQuote: id: my-module:components/blockQuote close: type: noComponent templateScript: /my-module/templates/misc/close.ftl
Node name | Value |
---|---|
areas | |
intro | |
availableComponents | |
styledIntroText | |
id | my-module:components/styledIntroText |
type | single |
main | |
availableComponents | |
textImage | |
id | my-module:components/textImage |
blockQuote | |
id | my-module:components/blockQuote |
close | |
templateScript | /my-module/templates/misc/close.ftl |
type | noComponent |
Notes about the example:
- Since
list
is the default value for thetype
property, it is not defined in themain
area. - The
intro
andmain
areas don't have atemplateScript
property. Instead, they fall back on the default area scripts.
Default area scripts
Even though the templateScript
property is required, it is not necessary to add the property to single
and list
area definitions. The system uses the default scripts below. If you need to render anything additional, like area div
tags or nested areas, write an script and reference it in the templateScript
property.
single
area default script:
[#-- Single component area that can only contain one component --] [#-- Area Definition should have property type=single --] [@cms.component content=component /]
list
area default script:
[#-- Multi component area that will list all content elements and enables adding more that one --] [#-- Area Definition should have property type=list --] [#list components as component] [@cms.component content=component /] [/#list]
Creating nested areas
Areas can contain nested areas, which can in turn contain nested areas. If you use a nested area, you need to assign a separate template script to the parent area in which the child area is rendered.
areas: navigation: templateScript: /my-web/templates/areas/navigation.ftl areas: navigationTeaser: type: single availableComponents: articleTeaser: id: my-web:components/navigationTeaser
Node name | Value |
---|---|
areas | |
navigation | |
templateScript | /my-web/templates/areas/navigation.ftl |
areas | |
navigationTeaser | |
type | single |
availableComponents | |
articleTeaser | |
id | my-web:components/navigationTeaser |
Creating area nodes
Area nodes are created in the JCR for each configured area by default. This is controlled by the createAreaNode
property that is set to true
by default.
Set the property to false
if an area node is not needed, such as when the area type is noComponent
or it has no content that editors could edit. Another use case for false
is an area that operates on some other item or node's content, not its own. When the content is stored elsewhere, no area node is needed.
areas: stockExchangeTicker: createAreaNode: false templateScript: /my-module/templates/misc/stockExchangeTicker.ftl type: noComponent
Node name | Value |
---|---|
areas | |
stockExchangeTicker | |
createAreaNode | false |
templateScript | /my-module/templates/misc/stockExchangeTicker.ftl |
type | noComponent |