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

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:

example/templates/pages/home.yaml
areas:
  header:
    # header area configuration
  content:
    # content area configuration
  footer:
    # footer area configuration
Node nameValue
 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 nameValue

 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 column in the same page definition but you can have column1 and column2.

type

required , default is list

Type of the area. Defines whether editors can add components inside the area and how many:

  • single can only contain one component.
  • list can contain many components.
  • noComponent cannot contain any editable components.
See Setting the area type .

availableComponents 

required for list and single areas

A map of components that editors can add in the area. Reference a component by its ID: <module>:<path> . See Restricting component availability in an area template.This property is not applicable to areas of type noComponent .

optional

optionaldefault is false

Makes the area optional. true adds a delete button in the area toolbar that editors can use to remove the area from the page. 

editable

optionaldefault is true

Typically this property is used in reverse. By setting the value to false you can prevent area editing. Useful for areas like header and footer.

maxComponents

optional

Maximum number of components an editor can add to the area. Only applicable to list areas.

enabled

optionaldefault is true

When set to false, the area is not rendered, regardless of whether it contains content such as components, auto-generated content or content rendered by a script.Content is retained in the repository and will render when the area is re-enabled.

createAreaNode

optionaldefault is true

Creates a node for the area in the repository. Set the property to false if an area node is not needed. See Creating area nodes.

name

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

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.

autoGeneration

optional

Creates components inside the area automatically without editor involvement. Anything you define inside the content item will be generated. See Component autogeneration.

fragmentDefinition

optional (EE only)

Allows you to mark an area as dynamic. See Advanced Cache and Sitemesh modules for more.Properties:

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

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

 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 the type property, it is not defined in the main area.
  • The intro and main areas don't have a templateScript 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.

areas:
  main:
    type: single
    areas:
      content:
        type: list
        availableComponents:
          textImage:
            id: my-templates:components/textImage 
Node nameValue

 areas

 

 main

 

 areas

 

 content

 

 type

 list

 availableComponents

 

 textImage

 

 id

my-templates:components/textImage 

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 nameValue

 areas

 

 stockExchangeTicker

 

 createAreaNode

false

 templateScript

/my-module/templates/misc/stockExchangeTicker.ftl

 type

 noComponent