Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
The STK concrete page template and component template definitions are configured in Templating Kit > Template Definitions.
Concrete template definitions for all STK page templates are configured in Template Definitions > /pages
.
These templates are made available to editors for selection in Website. They will show up in the dropdown list provided the:
visible
property is set to true in the template definition.role
based restrictions can be imposed in the /availability/<template name>/roles
node of the prototype.The templates available at the various page levels differ. For example, stkHome
and stkRedirect
are available at level 1 and stkSection
and others at level 2 etc. See Categories and subcategories below for more information on how the site hierarchy is achieved.
All concrete page templates are based on the template prototype. The prototype contains the default structure and behaviour and the concrete definitions define exceptions, additions and overrides of the prototype configuration. See Template merging for an example of how this works.
In order to be recognized by the system, configurations in the template definition need to be structured identically to the corresponding configuration in the template prototype. Compare the configurations of the infoBlock
area in the template prototype
and stkEvent
template below and note that the node structure is identical.
To make a template unique, in the template definition you can:
There are no hard and fast rules. In a custom installation the configurations that should be included in the template prototype, as opposed to the concrete templates, is a practical, rather than a technical, decision.
Modifications to the prototype can be made on a:
templateScript
. The stkRedirect
template discussed below is an example of this.stage
area in the stkHome
template.Most template properties are assigned on a concrete template level because they distinguish the different templates.
For a full list of available template properties and their usage see Pages > Properties in our Reference section.
The only property assigned in the template prototype and therefore available to all concrete templates is the templateScript
that references the master page script, main.ftl
.
With one exception, the following common properties are used by all STK templates:
class
node defines the base template definition.modelClass
node is the base page model that provides page level functionality. It extends STKPage
.renderType
node by the value stk
is the STK-specific renderer used by all STK templates (pages and components).info.magnolia.module.templatingkit.messages
, assigned in the i18nBasename
node. This is the key to the message bundle that contains STK translations.visible
property set to true
that makes the template available to editors in Website.There are two exceptions:
stkGlossary
template uses its own modelClass
, GlossaryTemplateModel, that extends STKPageModel<STKPage>
to complete the alphabetical glossary list.stkRedirect
template uses its own:modelClass
: RedirectTemplateModel that extends STKPageModel
and provides 3 alternative redirect modes that depend on the path
value provided by editors:templateScript
: redirectMain.ftl
renders the path appropriately on the page. You can view this script in Templates > /templating-kit/pages/functional/redirectMain.ftl
.In edit mode the path to the internal or external redirect renders on the page, but in preview mode the target page renders.
The following properties are specific to each template:
bodyID
: This is the tag used by the CSS sheets for template-specific styling. See Body classes and ids for more information. The bodyID
and subcategory
values often correspond but have no bearing on or relationship to each other.category
and subcategory
: Each template is assigned a category and most also a subcategory. Categories can be used in various scenarios see Categories and subcategories below.dialog
: Each page template links to its own stk<Template name>Properties
dialog configured in Dialog Definitions > /pages
. The Properties button in the top bar on each page opens this dialog, which controls the browser title and navigation title and behavior, page meta data (keywords and description), variation exclusion and page dependencies. See Properties dialogs for more information.title
: The template title that displays in the dropdown list in Website.The extends mechanism is used to minimize configuration. The mechanism is analogous to the relationship between an individual template definition and the prototype definition, but is explicit. Only changes, exceptions and additions are configured in the extended configuration, and all other configurations are taken from the base configuration.
The content templates, i.e. stkLargeArticle
, stkNews
, stkEvent
and stkGlossaryTerm
, are all extensions of the stkArticle
template that forms the base configuration. You can use this mechanism to easily create custom templates that are similar to the default STK templates.
Similarly, the templates in /pages/demo-features
are all extensions of the stkSection
template. These templates show numerous ways that you can change the page layout by configuration. You can view them in Section Variations in the demo-features site.
The extends
property can also be set to override
parts of an extended configuration. See the example in Making components available below.
Template merging is an automatic process that does not rely on the extends mechanism. The extends=override
property cannot be used in a template definition to modify the template prototype.
Each STK page template belongs to a category and all templates except stkHome
and stkRedirect
also have a subcategory
. Categories allow you to control where a template can be used on the site. If a template category is not allowed at a given place in the site structure, it will not be available to editors. The category mechanism therefore makes sure that templates are assigned in a consistent way and that your site has a controlled structure.
Categories establish an implicit template hierarchy. They define which template can be assigned to a page. For example the stkHome
template belongs to category home
. The home
category can only be used on the root page of the site. Similarly, templates that belong to category content
can only be used on a page that resides under a page whose template belongs to categories section
, feature
or functional
.
Subcategories are used for content aggregation. For example, the system aggregates all pages in the news
subcategory to generate a list of news teasers. An example is the creation of RSS feeds.
There are five template categories that correspond closely to the intended usage of the STK templates.
Category | Description | Templates in this category |
---|---|---|
home | Root of the site. | stkHome |
functional | Special templates that perform actions rather than render content. | stkRedirect |
section | Sections that organize the site. The demo-project site has sections such as News and Events and Service. Yours could be Products, Services or Support. | stkSection (including /demo-features variations), stkGlossaryLetter |
feature | Special templates and templates that collect or aggregate content. | stkForm stkFormStep stkImageGallery stkFAQ stkPublicUserRegistration stkSearchResult stkSiteMap stkGlossary stkNewsOverview stkEventsOverview stkCategoryOverview |
content | Core content pages. | stkArticle stkLargeArticle stkNews stkEvent stkGlossaryTerm |
Template availability and hierarchy are controlled by the STKTemplateAvailability class that implements TemplateAvailability wrapper class. The latter class contains the list of templates available on the site. Availability is configured first in the /template/availability
node in the site definition and second through categories. The availability logic for categories is hard-coded in TemplateCategory. They cannot be arbitrarily declared without extending this class. TemplateCategoryUtil adds utility methods for using template categories. Subcategories are not fixed. You can set them arbitrarily in the template definition.
The hard-coded default availability logic for categories are:
home
and functional
are the only categories that can be assigned to the root page of the site.home
can be assigned only once per site. You can define many home page templates, for example with different column layouts, which all have category home
. But you can assign only one of them at a time.functional
can be assigned to any page regardless of the category of the parent template. This means that you can for example have a redirect page anywhere on the site.section
can only be assigned to a page whose parent page has category home
, section
, functional
or feature
. In other words, it can be assigned to all pages except those whose parent is content
.content
can be assigned to a page whose parent page has category section
, content
, functional
or feature
. In other words, it can be assigned under all pages except the home page.feature
can be assigned to a page whose parent page has category section
, content
, functional
or feature
. In other words, it can be assigned under all pages except the home page.Area definitions are very powerful and you will find many of the configurations that distinguish the templates within these definitions. In this section we provide an overview of how area definitions are commonly used. To demonstrate we show a few examples of how the concrete templates differ from the template prototype to add functionality and features. For a more in-depth discussion of each area see the STK areas page. The examples show the flexibility of the system, but are not exhaustive. By combining them you can come up with many new possibilities.
Area definitions can reference a dialog. This option is used in the main/intro
area of all concrete templates (except stkHome
) to reference a template-specific properties dialogs. See intro area for more information.
The template prototype makes components available in areas where it makes sense to have a consistent set of components on all templates. The promotional areas: extras
, promos
and base
, are examples. The main/content
area is the distinguishing area and here components are made available in the concrete templates.
Components can be added to any list
or single
area. For more information see Area types.
You can add additional components to the /areas/<area name>/availableComponents
node of any template. The configuration below adds the stkTextImage
and stkQuotedText
components in the promos
area of the stkArticle
template. The prototype makes the stkPromo
component available so a total of three components become available in stkArticle
.
Not all components render perfectly in all areas and you may need change the CSS sheet or component definition. For example in the above configuration stkQuotedText
will not pick up the background font or quote.png
image used by the CSS sheet in promos
like it does in the main/content
area.
If you want to reduce the number of components made available in the prototype you can use the enabled
property to disable specific components. Note that the extends=override
property cannot be used in this case because template merging does not rely on the extends mechanism.
The example configuration below uses the stkEventsOverview
template.
/areas/promos/availableComponents
node makes Magnolia aware that changes to the prototype are configured in the area./availableComponents/stkPromo/enabled
node disables the stkPromo
component in the area./availableComponents/stkExtrasContact
node makes the stkExtrasContact
component available instead of the stkPromo
component.Here's the new component on the /demo-project/news-and-events/events-overview
page.
If you want to make different components available in a template that extends
another template you can use the extends=override
property.
The example configuration below uses the stkNews
template:
stkArticle
template. This is configured in the /stkNews/extends
node./areas/content/extends
property set to override
tells Magnolia to ignore (override) the /areas/content
configuration in the stkArticle
template. This configuration makes 8 content components available./areas/content/availableComponents
node makes only the stkTextImage
component available for use in the stkNews
template.You can restrict access to any component made available in an area in the template definition. There is an example configuration in the stkArticle
template that restricts access to the stkHTML
component to users assigned the superuser
role. Any user with lesser permissions cannot access the component. The configuration is in Template Definitions > /pages/stkArticle/areas/main/areas/content/availableComponents/stkHTML
:
roles
content node alerts Magnolia to a possible access restriction.superuser
data node with value also set to superuser
restricts access to the component to users assigned the superuser
role. See Roles for more information.You can test this by logging in as the Example Editor Eric (username/password=eric
) and attempting to add the stkHTML
component to the content
area of any article page. The stkHTML
component is not available in the selector dialog.
Magnolia 4.5.9 introduced two new features that relate to component availability. These are configured in the same way on a template level as in the prototype template. You can now also:
maxComponents
property.The main/content
area is the major distinguishing factor between the templates. In the template prototype the area is defined as type=list
allowing an unlimited number of sequential components to be added by default.
stkHome
, stkSection
and content templates retain the default type
. In the /areas/main/areas/content/availableComponents
node, teaser are made available in the first and second templates and content components in the third.
type
, changing it to single
. The feature component is added in the /areas/main/areas/content/autoGeneration/content/singleton
node. See Feature components and Autogenerated components below for more information.Most areas are enabled in the prototype and therefore need to be disabled in a specific template definition to change the default setting. This is done by adding an enabled
data node under the /areas/<area name>
content node and setting the value to false
. Areas like stage
and platform
that are rarely used are disabled in the prototype. In these cases set the enabled
property to true
to change the default behavior.
Enabling or disabling an area:
extras
on the stkArticle
template and viewing any article page in Tools > JCR Browser (Website).
extras
on stkArticle
it will also be disabled on all content templates. You can reverse this by adding the enabled property and setting it to true
on the template extensions on which you would like to include the area.extras
is disabled, main
area expands to use the available space.promos
is disabled nothing renders in the available space.base
, stage
or sectionHeader
are disabled the content moves up and renders as if the disabled area did not exist. This is also the behavior in preview mode when an area is enabled but contains no content. For the screenshot below we disabled the stage
on stkHome
template.
When floating
is enabled in main
and columns
set to 2
, the second column in main
will only render if extras
is disabled. The screenshot below shows the demo-features/section-variations/floating
page based on the /demo-features/stkSectionFloating
template.
In the template definition you can add areas that are not defined in the template prototype. The main
area of the stkSection
template creates a new nested area, opener
area.
The following changes to the prototype configuration relate to the new opener
area:
/areas/main
node:class
, SectionMainArea, that defines the opener
area properties./section/mainArea.ftl
script that is identical to the default script, /global/mainArea.ftl
, except that it adds the opener
area using the [@cms.area name="opener"/]
tag./areas/main/areas/opener
nodeopener
area.single
area meaning that only one component can render.enabled
and optional
meaning that it is available but editors may choose to delete it./section/opener.ftl
script that is a standard single area script.stkTeaserOpener
component available in the availableComponents
node.Floating means that components in the area render in a specified number of columns. By default, floating is enabled in main
area in the stkHome
and stkSectionFloating
templates. The demo-project
home page and the demo-features/section-variations/floating
pages are based on these templates. Here's main
area of demo-project
home page.
Floating is configured in the <template name>/areas/main
content node of the template definition. In the stkHome
template in Template Definitions > /pages/stkHome
:
/areas/main
:class
that defines the floating
properties.section/MainArea.ftl
script that simply renders all nested areas.areas/main/floating
:enabled
node is set true
enabling floating. You can disable it by setting this property to false
.columns
is set to 3
which tells Magnolia to render the components in three columns. Available options are 1
, 2
and 3
. Because the other nested areas are disabled, only components made available in the /areas/main/areas/content/availableComponents
node render in the main
area.areas/main/areas/content
:/availableComponents
node. These components are configured to work within a floating area (see below).section/contentArea.ftl
script. This script contains code that renders a teaserCount
(see below)./areas/main/areas/intro
, /opener
and /breadcrumb
are disabled, meaning that on this template floating only happens in /areas/main/areas/content
. It is not strictly necessary to disable the other nested areas./areas/extras
is disabled ensuring that the page resolves to an allowedBodyClass
(see below).By default, you can configure a floating template by extending the stkHome
and stkSection
templates because they use the SectionMainArea class and teaser components. All other scenarios require customization. The stkSectionFloating
template available in Template Definitions > /pages/demo-features/stkSectionFloating
is an example of extending the stkSection
template:
extends
the stkSection
template in the stkSectionFloating/extends
node. By extension:/areas/main/content/availableComponents
node.SectionMainArea
class is used./areas/main/floating
node floating
is enabled with columns set to 2
./areas/main/areas
node the intro
and opener
areas are disabled./areas/extras
node the extras
area is disabled.Here's the demo-features/section-variables/floating
page that is based on the stkSectionFloating
template. The page resolves to an allowedBodyClass=nav-col-float2
that is included as an attribute of the <body id>
element. Each teaser in main
area has an appended teaser id
in the <div class>
element.
Here are the elements that need to be considered to ensure that the components render correctly when floating is enabled:
bodyClass
automatically. Areas should be enabled and disabled as necessary to ensure that the page resolves to an allowedBodyClass
. See Body classes for more information.bodyClass
to ensure the correct styling.teaserCount
that tells Magnolia where to render each teaser. See Teaser ids for more information.divId
and divIdPrefix
property that facilitates the teaserCount
.id
and the section/contentArea.ftl script
renders the teaserCount
in the area.Variations can be used in a number of ways, for example to reformat content for devices like smartphones and tablets, or specific output for groups of logged in users. See Mobile for a full discussion of the example smartphone variation used in the demo sites and Channels for more information about this core functionality.
Variations are typically configured in the site definition, but can also be configured on a template level in the template definition. See Stage for an example of how this option is used to disable the stage
area for smartphones.
4.5.3 +
On a page template level you can configure a variation that is triggered by the page URL extension. Note that this type of variation cannot be configured in the site definition.
In the example configuration below the newsletter
variation disables the sectionHeader
, extras
, promos
and base
areas leaving only the main content. This variation may be suitable for example for an online version of a newsletter or a printable version of a page.
If you request content on any page based on the stkSection
template and change the extension from .html
to .newletter
the variation content is served.
You can combine this with the smartphone
variation configured in the site definition by adding the ?mgnlChannel=smartphone
parameter to serve the newsletter
variation in a format suitable for smartphones.
Variations are resolved by DefaultRenderableVariationResolver that combines ChannelVariationResolver and ExtensionVariationResolver.
This functionality should be used with caution because it allows users access to content by changing the URL extension. If used for sensitive content consider extending DefaultRenderableVariationResolver
to provide additional security measures.
You can also reference template-specific CSS sheets and JavaScripts for individual templates in the template definition. This option could be useful for example for holiday campaigns or dedicated sections of a site.
The example configuration below assigns a specific CSS sheet and an additional JavaScript to the stkArticle
template.
Components are the smallest block of content on a page. The STK includes components for all use cases and the available components range from simple text components to complex aggregation teasers and more. The individual components are discussed on the Components page.
Component definitions are configured in Template Definitions > /components
. The definitions are arranged in folders and the folder names indicate the component types.
A component definition is similar to the page definition. Both use the same template definition object. Pages and components reference their dialogs using the same path syntax. In addition, pages and components are rendered using the same renderer.
In many cases, it is not necessary to create a new component from scratch; you can copy or extend an existing one and adapt it to your needs.
Typically when creating new components, the following steps are involved:
Components are available to editors for content entry via the associated component dialog configured in Dialog Definitions. The dialog definition is mapped to the component definition using the dialog
property.
Most components are assigned to page templates within the area definitions in either the template prototype or concrete page template definition.
All STK component definitions have the the following properties:
description
: Message bundle key to the component descriptiondialog
: Path to the dialog definition with a <module name>:<path to definition
> structure. Most STK dialogs are configured in Dialog Defintions.118nBasename
: The internationalization key, info.magnolia.module.templatingkit.messages
, to the message bundle that contains STK translations.renderType
: STKRenderer assigned by the value stk
is a STK-specific renderer used by all STK templates (pages and components).templateScript
: Path to the script that renders the component. Component scripts are accessible in Templates > /templating-kit/components
.title
: The component title that renders in the component toolbar.deletable
determines if the component can be deleted. If set to false
the delete icon is rendered in the toolbar.
moveable
determines if the component can be moved. If set to false
the move icon is not rendered in the toolbar. writable
determines if the component can be edited. If set to false
the edit icon is not rendered in the toolbar. For a full list of available component template properties and their usage see Properties.
Here is an example of making a component editable while disallowing moving and deleting.
Here's what the editor sees in the page editor.
You can also restrict component actions in an area definition, in either the prototype or the concrete template definition, based on the roles assigned to users.
Many components use their own model class that provides the business logic for the component, and in some instances makes custom properties available to the script. For example the stkTeaser
component below uses InternalTeaserModel that allows linking to internal content in teaser components.
The internalPage.ftl
script renders the properties of the target content that are made available by the model. Here's a snippet from the script that is accessible in Templates > /templating-kit/components/teasers/interalPage.ftl
.
[#-- Assigns: Get and check Teaser Target --] [#assign target = model.target!] [#assign hasTarget = target?has_content] [#-- Assigns: Macro assigning Values --] [#macro assignValues] [#-- Assigns: Get Content --] [#assign title = content.teaserTitle!target.title!target.@name] [#assign kicker = target.kicker!] [#assign text = content.teaserAbstract!target.abstract!] [#assign teaserLink = model.teaserLink!]
Properties in a <component name>/parameters
node of a component definition are available to the template script without a supporting model class. This is built-in functionality. This node is also used for model class parameters.
Parameter properties are used extensively for CSS styling. For example, in the stkTeaserNewsList
component definition configuration below:
divClass
, divIDPrefix
and headingLevel
properties are made available to the template for CSS styling purposes and are not reliant on the model class. For more information see Teaser ids.searchForSubcategory
property is made available to the template by the modelClass
, NewsListModel. This component renders a list of teasers that have target pages based on page templates of subcategory=news
.teaserLinkType
property is also made available by the modelClass
and identifies the teaser links as internal
links.Here's how the newsList.ftl
script renders the divClass
, divIDPrefix
and headingLevel
properties. You can access this script in Templates > /templating-kit/components/teasers/newsList.ftl.
[#-------------- RENDERING PART --------------] [#-- Rendering: Latest News --] <div class="${divClass}" ${divID} > <${headingLevel}>${content.teaserTitle}</${headingLevel}>
Here's the rendered HTML of a stkNewsList
component.
Many STK components have nested components. On the page, the main component is created first and then the editor creates the child components. The main stkPureLinkList
component allows for only for a component title and the links are created using the stkInternalLink
, stkExternalLink
or stkDownloadLink
components.
In the main component definition:
/areas/<area name>/availableComponents
node. The node structure here is identical to that used when making components available in an area definition.id
property references the child component with the <module name>:<path to component>
structure./components/links
.The pureLinkList.ftl
script renders the main components with the same code used to render areas on page templates. The full script is accessible in Templates > /templating-kit/components/teasers/pureLinkList.ftl
. Here's the relevant snippet.
[#-- Rendering the teaser's linkList --] [@cms.area name="linkList"/]
The linkListArea.ftl
script renders the nested components using the [#list]
directive. The full script is accessible in Templates > /templating-kit/components/links/linkListArea.ftl
. Here's the relevant snippet.
… [#list components as component ] [@cms.component content=component /] [/#list] …
The extends mechanism is used extensively to minimize configuration of extras
components that have corresponding teaser
components. The components that render in the two areas are essentially the same except for CSS styling and inheritance behavior.
Here's the stkTeaserContact
component definition that is configured in full.
The stkExtrasContact
component extends the teaser component changing only the divIDPrefix
and dialog
reference. The stkExtrasContact
dialog is also an extension of the stkTeaserContact
dialog with the addition of the Show in Subpage field that allows for cascading on child pages. You can view the referenced dialogs at Dialog Definitions > /components/teasers/stkTeaserContact
and /extras/stkExtrasContact
. For more information see Inheritable components.
The autogeneration feature allows you to generate components automatically in any area of a page. This is Magnolia core functionality provided by the:
autoGeneration
node in an area definition.templateId
property and applies only to nodes named autoGeneration
.Autogenerated components can be configured in any area definition. The example configuration below autogenerates the stkExtrasCalendar
component in the nested extras1
area in the stkEvent
template. See extras area for more information about the configuration options available in the extras
area.
/areas/<area name>/autoGeneration
parent node and /content
child node need to have these specific names. The naming convention and node structure identifies the configuration as autogenerated content./autoGeneration/generatorClass
node assigns the CopyGenerator
class that allows the use of any properties available to the component referenced in the templateId
property./autoGeneration/content/calendar
node can be named anything you like. The properties in the example are the only required properties, but additional properties can be added depending on the component referenced (see example below).nodeType
is set to mgnl:component
identifying the referenced component as a component.templateId
defines the path to the component definition in the <module name>:<path to definition>
format.Here's the autogenerated component on a new page based on the stkEvent
template.
The example below autogenerates the stkHTML
component in the main/content
area on the stkArticle
template. Because the other content templates extend
this template the component also renders on the stkLargeArticle
, stkNews
, stkEvent
and stkGlossaryTerm
templates.
Here's the html.ftl
script that renders the stkHTML
component. Note that a single property, editHTML
, renders in the component.
[#if content.editHTML?has_content] ${cmsfn.decode(content).editHTML} [/#if]
Here's the example configuration the renders this component in main/content
area of the stkArticle
template:
editHTML
property adds the HTML code that is rendered by the [cmsfn.decode
] method.Here's the autogenerated component on a new page based on the stkArticle
template.
The behavior of autogenerated differs from standard components:
You can prevent editors deleting or moving autogenerated components by restricting component actions.
The feature templates are distinguishable mainly by the component that renders in the main/content
area of the page template. The stkImagGallery
, stkFAQ
, stkSiteMap
etc. components render in the area on the stkImageGallery
, stkFAQ
, stkSiteMap
templates etc. The component is rendered automatically by the page template and the autogeneration feature is used to accomplish this.
The component definitions are configured in the same way as other components and you can view them in Template Definitions > /components/features
.
The stkSiteMap
component shown below:
maxLevels
, showSiteMapRoot
and titleToUse
properties available to the script.siteMap.ftl
script accessible in Templates > /templating-kit/components/features/siteMap.ftl
.When a page based on the stkSiteMap
template is created, the component is rendered using default values configured in the area definition (see below). Editors can change these default values in the stkSiteMap
component dialog configured in Dialog Definitions > /components/features/stkSiteMap
. View the demo-project/service/site-map
page to see how this works.
In the stkSiteMap
page template in the areas/main/areas/content
node:
/autoGeneration
node is assigned the CopyGenerator class in the generatorClass
node. This generator creates nodes and properties identical to those found in the configuration linked to in the templateId
property and applies only to nodes named autoGeneration
.autoGeneration/content/singleton
node:nodeType
is set to mgnl:component
.templatedId
property references the stkSiteMap
component definition with the <module name>:<path to component>
structure.Here's the stkSiteMap
component and dialog on the demo-project/service/site-map
page.
In the dialog above the maxLevels
property is set to 4
. This is because the default of 3
defined in the template definition has been overriden on the page. The new value of 4
is stored in the JCR and you can verify this in Tools > JCR Browser (Website) > /demo-project/service/site-map/content/singleton
.
If you to change the default settings of an autogenerated component in the template definition, you need to first delete the component (singleton
node) in the JCR Browser and then refresh the page. The system will recreate the component on the page using the new template definition properties. This is a known bug and you can follow the progress in MAGNOLIA-4482.