Template prototype

Page configuration

The default template prototype structure and behavior is configured in Site Definitions /default/templates/prototype. The:

• templateScript property references the main page template script, main.ftl. This makes the script available to all concrete template definitions configured in Template Definitions > /pages.
• navigation node contains the default navigation configuration.
• areas node contains the area configurations.
• jsFiles and cssFiles nodes can be used to provide additional JavaScript functionality and CSS styling. These nodes are not used in the demo site as the default theme includes all that is necessary, but are available if anything additional is required.
  

  

Navigation configuration

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.

Properties:

• 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 1 and 2 for horizontal and 1, 2 and 3 for vertical.
• 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 vertical and horizontal nodes reference their own scripts.
  

  

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 > /templating-kit/pages/global/horizontalNavigation.ftl and /verticalNavigation.ftl. Here's a snippet from the horizontal script.

[#if model.navigation.showHorizontalNavigation]
    [#assign navigation = model.navigation.horizontalNavigation/]
    [#if (model.navigation.horizontalLevel >1 && navigation.selectedItem??) && (navigation.selectedItem.level>1 || !navigation.selectedItem.leaf)]
        [#assign cssClass = "class=\"plus-navsub\""]
    [/#if]
    <div id="nav-global" ${cssClass!} role="navigation">
        <div id="nav-global-box">
            <h6>${i18n['structural.navigation']}</h6>
            [@renderNavigation navigation=navigation/]
        </div><!-- end nav-global-box -->
    </div><!-- end nav-global -->
[/#if]

Here's the demo-project navigation menus with:

• The default settings:
  

  

• The horizontal/level property set to 2
  

  

Areas configuration

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.

Available areas

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.

• htmlHeader inserts meta elements in the HTML <head> element for keywords, description etc., creates the title element and links to style sheets and JavaScripts.
• branding contains the logo, tagline, search box, and internal and login links.
• sectionHeader is used only on section pages. Contains banner text for the section and is inherited by all child pages, unless these are configured differently.
• stage is used only for home pages. Contains a large teaser component.
• platform is not used, but can be added to any template. Contains a paging teaser.
• main contains 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.
• extras is 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.
• promos is typically used to promote special events or deals. The area floats to the right of main and extras if the window is wide enough or below if the window is narrow.
• base uses the full width of the page and can contain a large carousel or category cloud component.
• footer contains links, boilerplate text and the copyright statement.

Nested areas

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.

Area definitions

At a minimum, areas have the properties listed below. The only required property is type.

• description sets the message bundle key for the area description.
• enabled is a boolean property with true and false value 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.
• templateScript sets 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 main area is rendered by Templates >/templating-kit/pages/global/mainArea.ftl for all concrete templates, except stkSection and stkHome that use /templating-kit/pages/section/mainArea.ftl.
• title sets the message bundle key for the area title. This value renders in the area toolbar.
• type defines 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:

• class defines the concrete Java class to instantiate.
• dialog sets the path to the dialog definition in the <module name>:path to dialog format.
• editable is a boolean property with true and false value options that defines whether editors may add or edit content in the area.
• modelClass defines the Java class that contains business logic for the area.
• optional is a boolean property with true and false value options that defines whether editors may delete the area.
  

  

You can find a full list of area properties in our Reference section.

Area types

The type property determines what renders in the area. There are three options single, list and noComponent.

• The first two render components made available in the /<area name>/availableComponents node (see Available components below):
• single areas 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 stage area, where there is a choice of two large teasers, and opener and comments areas where only a single component type is type is made available.
• list areas 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 metaNavigation, content, extras1/2, base and footer areas, where many component types are available, and promos area where editors can add only one component type.
• noComponent areas do not render components made available in the <area name>/availableComponents node, but can render components that are configured differently. Examples of noComponent areas are:
• intro and sectionHeader areas that render the Page Header and Section Header components.
• branding, main and extras areas that contain child areas.
• htmlHeader, logo, search and breadcrumb areas that are rendered by area 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.

Area scripts

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 single or list area does not explicitly reference a templateScript the following default code is used:

[@cms.component content=component /]

[#list components as component]
   [@cms.component content=component /]
[/#list]

Area classes

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 class,  ConfiguredAreaDefinition , 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 templateScript.

This rule only applies when:

• There is a class property in the prototype area definition, and
• The area definition is modified in some way in a concrete area definition.

All other properties can be changed or added by a simple modification in the concrete definition if the area does not use a specific class.

Available components

The /areas/<area name>/availableComponents node makes components available in an area. This node can only be used for list and single areas types. It configures a content map of components built by reading the configuration into a Java Bean using the Content2Bean mechanism.

Note the following:

• The component definitions that are typically configured in Template Definitions > /components are made available to the template prototype here.
• Each component is configured in a child content node.
• Typically, the name of the content node corresponds to that of the component definition content node, but this is not strictly necessary.
• The id property 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.
• A standard set of components are made available in most areas in the prototype. Unless overrides or additions are configured in the concrete template definitions, a consistent choice of components is available in all templates. See extras area, base area and promos area for examples.
• The one notable exception is content area. This area distinguishes the concrete templates by making different component types available: content components in the content templates, teasers in home and section templates and unique components in the feature templates. For this reason the components are made available in the concrete template definitions, and no components are made available in the prototype.

Restricting component access

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 superuser role.

• The roles node alerts Magnolia to a possible access restriction.
• The superuser data node with value also set to superuser restricts access to the component to users assigned the superuser role. 

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.

Restricting component actions

 4.5.9+

You can define which users can edit, move and delete components based on the user's role. In the example below, users in the superuser and 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.
  
  • <write|move|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 superuser, delete-editors and editors roles see in the page editor. Only users in the superuser role can create new stkPromo components in the area because component access is restricted in the the /availableComponents/stkPromo/roles configuration.

Limiting the number of components

 STK 2.0.9+

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 2.

Area inheritance

Areas support component and property inheritance.

Component 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:

• Automatic inheritance: The component can only be added on the parent page and automatically cascades on all child pages. The metaNavigation area is an example of this type of inheritance.
• Selective inheritance: Editors can decide if a particular component should cascade on child pages. A Show in subpages checkbox field is available in the component dialog. The component cascades only when this box is checked. The extras1/2 and promos areas are examples of this type of inheritance.

Component inheritance is configured in the /areas/<area name>/inheritance content node and is only practical for list and single areas types.

• The enabled property enables and disables inheritance for the area, i.e. both component and property inheritance.
• There are three options for the components property.
• all configures automatic inheritance. All components added in the area cascade down to child pages automatically.
• filtered configures selective inheritance. Components added in the area cascade only if the Show in subpage box is checked in the component dialog. An inheritable property 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.
• none no components are inherited. This property effectively disables component inheritance, without simultaneously disabling property inheritance. See Property inheritance below.

When the 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 metaNavigation area:

• In the template prototype the property is set to false making the components non-editable by default.
• In the stkHome template definition the property is set to true ensuing 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 inheritable that needs to be present and set to true.
• 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 components property.

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

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.

Autogenerated components

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

A /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 autoGeneration, floating cannot be configured at the template prototype level without customization. It is available and used in the main/content area in the stkHome and stkSection templates. See Enabling floating for more information.

CSS and JavaScript

CSS and JavaScript can be added to the template prototype, if necessary. This option is not used in the /default/template/prototype configuration because all necessary style sheets and Javascripts are included by the default 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.

The example configuration below adds an additional Javascript and CSS file at the template prototype level in Site Definitions > /default/templates/prototype/cssFiles and /jsFiles.

The Javascript adds exploding fireworks to the page and the CSS sheet amends the header background color. Note how the htmlHeader script adds the additional JavaScript to the <head> element of the HTML code.