Area definition

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

Area properties

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:

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 

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