Areas

Pages consist of areas which can consist of further areas or components. Areas have two purposes: they structure the page and control what components editors can place inside the area. This makes area the most powerful template type. It ensures consistency across the site.

Areas also provide repeatability. An area template typically loops through the components inside it, rendering the components one by one. Most areas are rendered with containing div elements in the generated HTML so that you can control their layout on the page with CSS.

An area has a toolbar which displays the name of the area. Areas also have an end marker, a narrow green bar at the bottom. The toolbar and the end marker indicate the dimensions of the area. Inside the area are its components or, if no components have been added yet, a gray placeholder.

This diagram shows where some of the areas defined in the template prototype are on the page. Learn more about areas in the STK.

Area definition

An area definition enables the area, defines what template script is used to render it, and what components are allowed inside it. Area definitions are very similar to page definitions. You could say that area = template + component availability + inheritance.

You can define areas in the following places:

In the default site definition for the whole instance. This makes an area available on every site.
In a site definition for a particular site. This makes the area available on all pages of that site but not on other sites.
In a page template definition for that page only. This makes the area available on all pages that adhere to the page template but not on other pages.

Properties

Areas have the following common properties. In addition, each area can provide its own custom properties. The area model class can process the custom properties to change how the area behaves or how it is rendered. For example, the intro area has several custom properties such as showAbstract and showAuthorDate which define whether these metadata fields should be rendered inside the area.

Property	Description	Value
`type`	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
`templateScript`	Optional. Path to an area script. The script is used to render the area. Areas render any components inside them automatically, without a script. You only need a script if you want to render something in addition to the components.	A valid path on the file system, `templates` workspace or in the web application's classpath.
`renderType`	Optional, need only if `templateScript` is also used. Determines which renderer to use. Out of the box, Magnolia supports `jsp` and `freemarker` renderers. The type for STK components is `stk`.	`jsp` `freemarker` `stk`
`dialog`	Optional. Dialog used to edit area properties and content.	`<module name>:<path to dialog definition>`
`availableComponents`	A map of components that are allowed in the area. This node controls what editors can place inside the area.
`createAreaNode`	Creates a node for the area in the repository when set to `true` (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. The `branding` area is an example of this. Another use case for `false` is an area that operates on some other node's content, not its own. When the content is stored under that other node, no area node is needed. This has the same effect as setting the `content` attribute in the area directive: [@cms.area name="branding" content=content/] Magnolia 5.2.4+	`true` (default) `false`
`editable`	Makes the area editable when set to `true`. Typically this property is used in the reverse. By setting the value to `false` you can prevent area editing, which is the default setting for metaNavigation, sectionHeader and footer areas.	`truefalse`
`enabled`	Enables and disables the area. Defines whether the area is available on the site.	`truefalse`
`class`	Area configuration class. The class instantiates the area object through the Content2Bean mechanism.	Fully-qualified class name.
`maxComponents`	Maximum number of components an editor can add to the area.	Number of components, for example `3`
`modelClass`	Area model class which contains business logic.	Fully qualified class name.
`name`	Name of the area. Identifies the area so the page can call it to be rendered. If you don't provide this property, the area node's name is used as a fallback.
`title`	A title displayed in the edit bar.	A literal string or a key in a message bundle. The default is the name of the area's content node with the first letter capitalized.
`inheritance`	Inheritance makes it possible to render the area on child pages automatically.	Subnodes: `enabled=true\|false` `components=all\|filtered\|none` `nodeComparatorClass` `predicateClass` `properties=all\|none`
`optional`	Makes the area optional. Adds a delete button in the area toolbar that editors can use to remove the area from the page.	`true` or `false`. Default is `false`.
`floating`	Allows components to shift to the right into a two-column layout.	`enabled = true\|false`
`autoGeneration`	Creates content inside the area automatically without editor involvement. Anything defined inside the child node `content` will be generated.

Rendering empty areas

By default, empty areas are rendered in the page HTML. For example, a link list area that doesn't have any link components inside it is still rendered as an empty <div> element. Empty areas are typically not visible to the user but they are present in the HTML.

<div class="links">
  <ul></ul>
</div><!-- end links -->

This rendering behavior is configurable. You can disable the rendering of empty areas if it causes issues for layout or design. For example, you may have an area that is visible even when empty. Having an empty box on the page may not be what you want.

Add a renderEmptyAreas property to the Configuration > /server/rendering/engine node and set the value to false to turn off the rendering of empty areas. Default value is true.

Page tree

Areas

Area definition

Properties

Rendering empty areas