Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.

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

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.

Layout

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.

 

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.

true or false

enabled

Enables and disables the area. Defines whether the area is available on the site.

true or false

class

Area configuration class. The class instantiates the area object through the Content2Bean mechanism.

Fully qualified class name.

maxComponentsMaximum number of components an editor can add to the area.Number.

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.

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.

 

In the skeleton below, mandatory properties are red and optional properties are black.

Rendering empty areas

(warning) 4.5.10+ 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. Typically empty areas are not visible to the user although 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.

  • No labels