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

Basic Configuration 

What is an area definition?

The area definition represents the configuration of an area within a concrete page or component. An area is a very powerful and flexible renderable item within pages and components.





  • Typical examples are: the linkList area within a linkList component, the main area within a page.
  • The area definition uses the ConfiguredAreaDefinition, therefore implements the AreaDefinition and also the TemplateDefinition interface.
  • The AreaDefinition adds more configuration possibilities to an area than does a template.

A area definition has three minimum properties:

  • type
  • availableComponents
  • enabled

and a fourth important, optional configuration: maxComponents




Default render behaviour

List area without an attached script.
[#list components as component ]
    [@cms.component content=component /]
Single area without an attached script.
[@cms.component content=component/]
    • availableComponents: a list of components, addable to the area.  
      • the available component id is defined by two values: module-name:path-to-component
      • in this example: training-samples:components/sampleComponent

    • enabled: default value is true, possibility of enabling/disabling an area.
    • Optional: maxComponents = Integer defines the maximum of Components that can be added into the area itself.
    • This main area definition example produces the rendered output.

Triggering Area Rendering

The rendering of the area is triggered by the @cms.area directive, passing the area name.  The area rendering is done in the script of the configuration holding the area configuration: page defines an area → the page script triggers its rendering. The area rendering triggered:

Default render behavior of 'single' area without an attached script.
[@cms.area name="main" /]

Using a script to render an area

As the area definition also implements the TemplateDefinition interface, it can also use a script to render the area.  Two configurations are needed for using a script, just as in any other component or page definition. 

  • templateScript: What script to render the output with.
  • renderType: What renderer to use.

Optional area

An area definition can be configured as optional. In this case the author can decide, whether the area should exist at all.  The area node is created only after author creates the area.

Component Inheritance 

Every area definition is capable of inheriting components. An area in a sub page can inherit components from a parent page where the area was initially defined. To enable the inheritance of components, a node 'inheritance' is added to the area definition. Two configurations are needed for the 'inheritance' node:

  • enabled: true or false, enabling or disabling the inheritance.
  • components: behavior of the component inheritance.

Other properties include

  • all : all components will be inherited
  • filtered : only components containing a property inheritable=true will be inherited.
  • none : no component will be inherited.''


When an area is rendered for the first time, an area node is created. Any content could be stored directly into the area node, needed for the area's rendering. The created jcr:primaryType of an area node is mgnl:area. Because AreaDefinition extends TemplateDefintion wl a dialog can also be attached to an area as to any other TemplateDefiniton.  The dialog for an area stores the properties into the area node itself.  When adding a component into an area, a component sub-node is created within the area's node.

Learn more

Next unit

Model class.

  • No labels