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
areas: header: # header area configuration content: # content area configuration footer: # footer area configuration
Simple area definition:
areas: content: renderType: freemarker type: list availableComponents: text: id: my-module:components/text optional: false
You can use common template properties and the following properties in an area definition:
Area names must be unique within a
This means, you cannot have two areas named
required, default is `list`
Type of the area. Defines whether editors can add components inside the area and how many:
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
Maximum number of components an editor can add to the area. Only
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.
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.
Creates components inside the area automatically without editor
involvement. Anything you define inside the
optional (DX Core only)
Allows you to mark an area as dynamic. See Advanced Cache and Sitemesh modules for more.Properties:
Setting the area type
type property determines what is rendered in the area:
singlearea 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.
listarea 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 the
maxComponentsproperty. 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.
noComponentarea 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.
Since version 1.0.6 of the Magnolia Front-end helpers, you can use the
noComponenttype in your SPA projects to create custom area scripts with as little overhead as possible.
See it used in the following ReactJS example template definition: git.magnolia-cms.com/projects/MODULES/repos/frontend-helpers/browse/samples/react-sample/light-modules/react-lm/templates/pages/standard.yaml.
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
Notes about the example:
listis the default value for the
typeproperty, it is not defined in the
mainareas don’t have a
templateScriptproperty. Instead, they fall back on the default area scripts.
Editing a dialog for areas
To enable the Edit area option on your instance, you first need to add a dialog to the area definition.
First, add an
areas folder in
<my-module>/dialogs (in our example
<my-module> name is
hello-magnolia). In this folder, you’ll create a definition file named, for example,
area-dialog.yaml and copy the content below into it:
form: properties: text: label: Text $type: textField footerLayout: $type: defaultEditorActionLayout
Now, go to
/hello-magnolia/templates/pages folder, open the
hello.yaml file and add the following to the
areas: main: dialog: hello-magnolia:areas/area-dialog availableComponents: quotation: id: hello-magnolia:components/quotation
The Edit area action should be enabled now.
Default area scripts
Even though the
is required, it is not necessary to add the property to
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
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. WARNING: 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
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