Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
Within the site definition, the template prototype configures the default fallback template definition. It:
Each concrete page template configured in Template Definitions has features that makes it unique. The template prototype defines settings that are more likely to be used in the majority of templates. This makes for efficient configuration as it is only necessary to define exceptions in the page template definitions. For example the platform area is disabled by default in the prototype. This area is not used by any of the concrete templates, but makes a nice addition to a page. It can be enabled by the simple addition of a node.
The template prototype is merged with the concrete template when the page is requested. The example below shows how the merging happens on the
stkHome page template. Pay attention to the
extrasareas so that they work on all pages. The prototype also defines the child areas for each (not displayed in the diagram).
stkHomeis the concrete template definition. It inherits the base area configuration from the template prototype. The concrete definition can add and override anything that was inherited. For example,
floatingconfiguration is added to the
main. It was not in the prototype. The
templateScriptproperty is an example of an override. The concrete definition includes the property but provides a different value. It uses a different
mainArea.ftlscript that is tailored to section pages. Similarly, the
extrasarea is disabled by setting the
(def)templating support object. This means that a script can get the value of a property with
The default template prototype structure and behavior is configured in Site Definitions
templateScriptproperty references the main page template script,
main.ftl. This makes the script available to all concrete template definitions configured in Template Definitions >
navigationnode contains the default navigation configuration.
areasnode contains the area configurations.
By default, the STK supports 2 levels of horizontal and 3 levels of vertical navigation but this is configurable. The first horizontal level includes the home pages and the section pages, that is levels 1 and 2 in the site hierarchy. After that the levels follow the site hierarchy. For example, when you set horizontal navigation to display two levels, hierarchy levels 1 (home), 2 (sections) and 3 are displayed horizontally. Hierarchy levels 4, 5 and 6 are displayed vertically.
allOpen: When set to
true, all available navigation levels are expanded. When set to
false, new levels are expanded as users click the navigation links.
enabled: Enables and disables the navigation menu.
level: Sets the depth of levels. Available options are
2for horizontal and
startLevel: Starting depth level where navigation starts. Typically vertical follows horizontal without level overlap. This property allows you to display a level in both navigations, for example.
template: Path to the template script. The
horizontalnodes reference their own scripts.
You can set the vertical navigation at greater than 3, but will run into CSS issues. Edit the main CSS sheet
styles.css in Resources
The SiteNavigationModel exposes the configuration properties to the navigation scripts that render the vertical and horizontal navigations. The scripts are accessible in Templating Kit > Templates >
/verticalNavigation.ftl. Here's a snippet from the horizontal script.
demo-project navigation menus with:
horizontal/levelproperty set to
Area definitions are configured within the template prototype page definition. The Site Definitions >
/default/templates/prototype/areas content node contains the definitions for the available page areas. Areas are made available as a content map. The area definitions make the areas available to the template, define the behaviour of the area and which components, if any, are available within the area.
This section provides an overview of area definition configurations. For a more in depth discussion about each STK area see the STK areas page.
The prototype template defines the available areas. The individual concrete templates use most, but not all, areas.
The page script,
main.ftl, determines the order in which the areas render and where they fall within the
wrappers. This makes the area node sequence in the configuration immaterial. Areas are included by the page script using the [
cms.area name="<area name>"] tag.
The screenshot of the left shows the parent areas configured in the prototype and the diagram on the right the positioning and wrapping of the areas on pages.
Briefly, each area has the following content and function. See the Areas page for a more detailed discussion.
htmlHeaderinserts meta elements in the HTML
brandingcontains the logo, tagline, search box, and internal and login links.
sectionHeaderis used only on section pages. Contains banner text for the section and is inherited by all child pages, unless these are configured differently.
stageis used only for home pages. Contains a large teaser component.
platformis not used, but can be added to any template. Contains a paging teaser.
maincontains the main content of the page. On an article page, the main content is the article story, on a news page the news item and so on. On section and home pages the main content is teasers to the content pages.
extrasis used for teaser components. Typically, these would be related to the main content. For example, if the main content is an event, the extras could be Calendar, Contact and Next Events teaser components providing a clickable calendar, contact information and a list of upcoming events.
promosis typically used to promote special events or deals. The area floats to the right of
extrasif the window is wide enough or below if the window is narrow.
baseuses the full width of the page and can contain a large carousel or category cloud component.
footercontains links, boilerplate text and the copyright statement.
Areas can include nested child areas that can in turn have their own nested areas. Nested areas are configured in
/default/templates/areas/<parent area name>/areas/<child area name> nodes. The second (or third)
areas content node name identifies the child configuration as an area. Parent and child areas support the same properties and configuration options.
At a minimum, areas have the properties listed below. The only required property is
descriptionsets the message bundle key for the area description.
enabledis a boolean property with
falsevalue options to enable and disable the area. The default for this property is
true, so when the property is omitted the area is enabled by default. Areas enabled in the template prototype can be disabled in the concrete templates by reversing the prototype value.
templateScriptsets the path to the script that renders the area. A dedicated script is only strictly necessary when it does something in addition to simply rendering the area. All concrete templates use the script defined in the prototype unless another script is referenced in the template definition. For example
mainarea is rendered by Templates >
/templating-kit/pages/global/mainArea.ftlfor all concrete templates, except
titlesets the message bundle key for the area title. This value renders in the area toolbar.
typedefines how many components, if any, can render in the area. The available options are discussed in Area types below.
Many STK area definitions also use one or more of the following properties:
classdefines the concrete Java class to instantiate.
dialogsets the path to the dialog definition in the
<module name>:path to dialogformat.
editableis a boolean property with
falsevalue options that defines whether editors may add or edit content in the area.
modelClassdefines the Java class that contains business logic for the area.
optionalis a boolean property with
falsevalue options that defines whether editors may delete the area.
You can find a full list of area properties in our Reference section.
type property determines what renders in the area. There are three options
/<area name>/availableComponentsnode (see Available components below):
singleareas render one component on the page. Editors can be given a choice of multiple component types, but may only add one. Examples of single areas are
stagearea, where there is a choice of two large teasers, and
commentsareas where only a single component type is type is made available.
listareas render any number of sequential components on a page. The choice of component types made available to editors can range from one to many. Examples of list areas are
footerareas, where many component types are available, and
promosarea where editors can add only one component type.
noComponentareas do not render components made available in the
<area name>/availableComponentsnode, but can render components that are configured differently. Examples of
footer area is a
list area that renders both components in the
availableComponents node and the Footer component that is rendered by the script.
You can change the area
type in the concrete definitions. See Template definitions > Changing area behaviour for how this is done on the feature templates.
The area scripts used by the template prototype are accessible in Templates>
/templating-kit/pages. Most area scripts simply assign a
<div id> element and call for an area to be rendered. They do not define what is in the area. That is the responsibility of the area definition.
An area can be rendered by only an area definition. If a
list area does not explicitly reference a
templateScript the following default code is used:
|single area||list area|
Many area definitions define a specific Java class that instantiates when the area is called. If you want to modify the area definition in any way in a concrete template definition, the
class property reference needs to be repeated in the concrete area definition, i.e. a
class property referencing the same fully qualified class name should be present in both the template prototype and the concrete template definition. This reason for this is that both definitions and their
classes are instantiated at the same time during the template merging process. If no
class is found in the template definition the fallback
, is used.
Compare the screenshots below of the
main area definition in the template prototype and
stkArticle template. Note that the same
class is necessary in both because
stkArticle uses a different
This rule only applies when:
classproperty in the prototype area definition, and
All other properties can be changed or added by a simple modification in the concrete definition if the area does not use a specific
/areas/<area name>/availableComponents node makes components available in an area. This node can only be used for
types. It configures a content map of components built by reading the configuration into a Java Bean using the Content2Bean mechanism.
Note the following:
/componentsare made available to the template prototype here.
idproperty defines the path to the component definition in the
<module name>:<path to component definition>format. This allows for the addition of components from any module, not only STK components.
You can restrict the availability of individual components in the
availableComponents node to users assigned a specific role in Security > Roles. See Roles for more information. The example configuration below limits access to the
stkPromo component to the
rolesnode alerts Magnolia to a possible access restriction.
superuserdata node with value also set to
superuserrestricts access to the component to users assigned the
This effectively prevents users that have not been assigned the role from creating the component, but they can still edit, move and delete an existing component. Here's what
superuser, compared to Example Editor Eric (
username/password=eric), sees in the page editor.
You can define which users can edit, move and delete components based on the user's role. In the example below, users in the
delete-editors roles can edit, move and delete
stkPromo components. User in the
editors role can only edit and move components.
Nodes and properties:
permissions: contains the action restrictions.
delete>: action to which the restriction applies.
<roleName>identifies the role. The name of the attribute is arbitrary but the value must match an existing role.
Here's what users assigned the
editors roles see in the page editor. Only users in the
superuser role can new
stkPromo components in the area because component access is restricted in the the
You can also make components
deletable in the component definition.
You can restrict the number of components that render in a
list area by adding a
maxComponents property to the
<area name> name node and setting the value to an appropriate number. Once the limit is reached the New Component box not longer renders preventing editors from adding additional components. The example configuration below limits the number of components in
base area to
Areas support component and property inheritance.
Component inheritance has two benefits. It saves effort since the component is repeated on child pages by adding it once on a parent page. It also helps enforces consistency. Only the source component is editable, its inherited instances are not, so the component stays the same wherever it is displayed. Component inheritance means that the components in the area cascade down to child pages.
Two types of component inheritance are supported:
metaNavigationarea is an example of this type of inheritance.
promosareas are examples of this type of inheritance.
Component inheritance is configured in the
/areas/<area name>/inheritance content node and is only practical for
enabledproperty enables and disables inheritance for the area, i.e. both component and property inheritance.
allconfigures automatic inheritance. All components added in the area cascade down to child pages automatically.
filteredconfigures selective inheritance. Components added in the area cascade only if the Show in subpage box is checked in the component dialog. An
inheritableproperty is created on the component content node and its value is set to
true. This property is the trigger for the filter. Only nodes with the property set to true are inherited to child pages.
noneno components are inherited. This property effectively disables component inheritance, without simultaneously disabling property inheritance. See Property inheritance below.
components property is set to
all, you can use the
editabe area property to ensure that components are only added and edited on the appropriate page. This option is used in
falsemaking the components non-editable by default.
stkHometemplate definition the property is set to
trueensuing that the components are only editable on the home page.
The ConfiguredInheritance class defines inheritance behaviour. This class includes four nested classes:
AllComponentsAndResourcesInheritancePredicate: Predicate for component inheritance that includes all components.
FilteredComponentInheritancePredicate: Predicate for component inheritance that includes only nodes with a a property named
inheritablethat needs to be present and set to
InheritNothingInheritancePredicate: Predicate for component inheritance that includes no components.
NodeDepthComparator: Comparator for ordering nodes by depth. Nodes deeper in the hierarchy are placed after those further up. Nodes on the same level are placed in the order they appear as siblings.
The predicate classes define the behaviour options available for the
components property in the configuration. You can define your own predicate class by adding a
predicateClass property to the
inheritance configuration and setting the value to the fully qualified name of your class. This property takes precedence over the
The comparator class defines the order in which the inherited components render. You can define your own comparator class by adding a
nodeComparatorClass property in the
inheritance configuration and setting the value to the fully qualified name of your class. This will override the default ordering behaviour.
See Inheritable components for a tutorial on configuring component inheritance.
Property inheritance means that the area properties are inherited by child pages. This option is not used in the demo sites. Property inheritance is configured by adding a
properties data node to the
/areas/<area name>/inheritance content node. Available options are:
all: All area properties are inherited.
none: No properties are inherited.
The example configuration below shows a
list area in which only the area properties, and not the components, are inherited by child pages.
Area definitions can generate components automatically. Autogenerated components can be added in an
/areas/<area name>/autoGeneration/content node. This configuration option is available at the template prototype level, but is not used. It typically makes more sense on a concrete template level and in the STK it is used on the features templates and in the
extras area of the
stkNewsOverview template. See Autogenerated components for more information.
/floating content node within an area definitions specifies whether elements inside the area can float (display side-by-side), and if so, how many columns are they arranged in. Unlike
floating cannot be configured at the template prototype level without customization. It is available and used in the
main/content area in the
stkSection templates. See Enabling floating for more information.
pop theme that is referenced in the
/theme node of the site definition. See Themes and htlmHeader area for more information about the standard configuration.
<head> element of the HTML code.