Area definition

Areas control template structure and define which parts of a template can be edited by an author. Areas are typically used on page templates, but they can also be used on components. An area definition defines what components editors can add in the area and how many. You can define areas inside your page definitions and component 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 or component definition, inside the areas property:

example/templates/pages/home.yaml
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:

Property Description

<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 for more details.

     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

optional, default is false

FreeMarker development only

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

optional, default 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

The maximum number of components an editor can add to the area.

This is only applicable to list areas.

     enabled

optional, default is true

  • If null, the area’s configuration inherits the values from the prototype.

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

  • In SPA development, if false, area nodes are not included in the endpoint response.

    This only applies in SPA development if the delivery endpoint type is jcrPagesDeliveryEndpoint_v2 and Magnolia front-end helper versions are:

    • 1.4.2 (or higher) for @magnolia/react-editor

    • 1.5.1 (or higher) for @magnolia/angular-editor

     createAreaNode

optional, default 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 for more details.

     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 for more details.

     autoGeneration

optional

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

See Component autogeneration for more details.

     fragmentDefinition

optional (DX Core only)

FreeMarker development only

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

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.

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.

    Since version 1.0.6 of the Magnolia Front-end helpers, you can use the noComponent type 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: (1) (2)
  intro:
    type: single
    availableComponents:
      styledIntroText:
        id: my-module:components/styledIntroText
  main: (1)
    availableComponents:
      textImage:
        id: my-module:components/textImage
      blockQuote:
        id: my-module:components/blockQuote
  close:
    type: noComponent
    templateScript: /my-module/templates/misc/close.ftl
1 Since list is the default value for the type property, it is not defined in the main area.
2 The intro and main areas don’t have a templateScript property. 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:

/hello-magnolia/dialogs/areas/area-dialog.yaml
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 section:

/hello-magnolia/templates/pages/hello.yaml
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 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 creating 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
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules