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

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

Concrete template definitions for all STK page templates are configured in STK > Template Definitions /pages.

Node nameValue

   pages

 

 demo-features

 

 stkHome

 

 stkSection

 

 stkArticle

 

These templates are made available to editors for selection in the Pages app. They show up in the Template field in the Pages app provided the:

  • visible property is set to true in the template definition.
  • Template is made available in the default site definition, or any other site definition in the EE.
  • Editor's permissions are sufficient to access the particular template. 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.

Template prototype

Node nameValue

 default

 

 templates

 

 prototype

 

 areas

 

 main

 

 areas

 

 intro

 

 areas

 

 infoBlock

 

Template definition

Node nameValue
 pages 

 stkEvent

 

 areas

 

 main

 

 areas

 

 intro

 

 areas

 

 infoBlock

 

 

To make a template unique, in the template definition you can:

  • Override most properties and content node configurations found in the prototype.
  • Configure additions to the prototype. Additions are new configurations not found in the prototype that add functionality, areas, components and other features.

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:

  • Page level, for example by referencing a new templateScript. The stkRedirect template discussed below is an example of this.
  • Navigation level by changing the default navigation configuration or coding an entirely new one. This would rarely be necessary but may be appropriate on special custom templates.
  • Area level by referencing different scripts and changing area behavior. See main area for an example.
  • Variation level by disabling areas for a specific template so that the area renders for one variation but not the other. See Mobile for how this option is used for the stage area in the stkHome template.
  • JavaScript and CSS level by referencing different CSS sheets or JavaScripts. This option is rarely necessary and not used in either the prototype or concrete template definitions, but there is an example configuration in Configuring variations in a page template > CSS and JavaScript.

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.

Common properties

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:

  • STKPage assigned in the class node defines the base template definition.
  • STKPageModel assigned in the modelClass node is the base page model that provides page level functionality. It extends STKPage.
  • STKRenderer assigned in the renderType node by the value stk is the STK-specific renderer used by all STK templates (pages and components).
  • The internationalization key, info.magnolia.module.templatingkit.messages, assigned in the i18nBasename node. This is the key to the message bundle that contains STK translations.
  • The visible property set to true that makes the template available to editors in the Pages app.

    Node nameValue

       pages

     

     stkArticle

     

     areas

     

     bodyID

    article

     category

    content

     class

    info.magnolia.module.templatingkit.templates.pages.STKPage

     dialog

    standard-templating-kit:pages/article/stkArticleProperties

     i18nBasename

    info.magnolia.module.templatingkit.messages

     modelClass

    info.magnolia.module.templatingkit.templates.pages.STKPageModel

     renderType

    stk

     subcategory

    article

     title

    templates.stkArticle.title

     visible

    true

There are two exceptions:

  • The stkGlossary template uses its own modelClassGlossaryTemplateModel, that extends STKPageModel<STKPage> to complete the alphabetical glossary list.

    Node nameValue

       pages

     

     stkGlossary

     

     areas

     

     bodyID

    glossary

     category

    feature

     class

    info.magnolia.module.templatingkit.templates.pages.STKPage

     dialog

    standard-templating-kit:pages/glossary/stkGlossaryProperties

     i18nBasename

    info.magnolia.module.templatingkit.messages

     modelClass

    info.magnolia.module.templatingkit.templates.GlossaryTemplateModel

     renderType

    stk

     subcategory

    glossary

     title

    templates.stkGlossary.title

     visible

    true
  • The stkRedirect template uses its own:
    • modelClassRedirectTemplateModel that extends STKPageModel and provides 3 alternative redirect modes that depend on the path value provided by editors:
      • If an internal path or external URL is entered in the dialog, users are redirected directly to it and the rendering is skipped avoiding writing of the response.
      • If no path is entered the page redirects to the first child page found. This is useful to directly display a page defined in a second or third level of a redirect tree.
      • templateScriptredirectMain.ftl renders the path appropriately on the page. You can view this script in STK > Templates /templating-kit/pages/functional/redirectMain.ftl.

        Node nameValue

           pages

         

         stkRedirect

         

         areas

         

         bodyID

        redirect

         category

        functional

         class

        info.magnolia.module.templatingkit.templates.pages.STKPage

         dialog

        standard-templating-kit:functional/stkRedirect

         i18nBasename

        info.magnolia.module.templatingkit.messages

         modelClass

        info.magnolia.module.templatingkit.templates.RedirectTemplateModel

         renderType

        stk

         subcategory

        redirect

         templateScript

        /templating-kit/pages/functional/redirectMain.ftl

         title

        templates.stkRedirect.title

         visible

        true

In the page editor the path to the internal or external redirect renders on the page, but in preview the target page renders. The /demo-project/service/m5-campaign page is based on the stkRedirect template.

Template specific properties

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 STK > 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 Template field in the Pages app. .

    Node nameValue

       pages

     

     stkImageGallery

     

     areas

     

     bodyID

    image-gallery

     category

    feature

     class

    info.magnolia.module.templatingkit.templates.pages.STKPage

     dialog

    standard-templating-kit:pages/imageGallery/stkImageGalleryProperties

     i18nBasename

    info.magnolia.module.templatingkit.messages

     modelClass

    info.magnolia.module.templatingkit.templates.pages.STKPageModel

     renderType

    stk

     subcategory

    imageGallery

     title

    templates.stkImageGallery.title

     visible

    true

Extends property

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

Node nameValue

   pages

 

 stkArticle

 

 stkLargeArticle

 

 stkNews

 

 areas

 

 dialog

standard-templating-kit:pages/news/stkNewsProperties

 extends

/modules/standard-templating-kit/templates/pages/stkArticle

 subcategory

news

 title

templates.stkNews.title

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.

Node nameValue

   pages

 

 demo-features

 

 stkSectionNoExtras

 

 areas

 

 extends

/modules/standard-templating-kit/templates/pages/stkSection

 title

Section no Extras

 stkSectionNoHeader

 

 stkSectionFloating

 

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.

Categories and subcategories

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

CategoryDescriptionTemplates in this category
homeRoot of the site.stkHome
functionalSpecial templates that perform actions rather than render content.stkRedirect
sectionSections 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
featureSpecial templates and templates that collect or aggregate content.stkForm
stkFormStep
stkImageGallery
stkFAQ
stkPublicUserRegistration
stkSearchResult
stkSiteMap
stkGlossary
stkNewsOverview
stkEventsOverview
stkCategoryOverview
contentCore content pages.stkArticle
stkLargeArticle
stkNews
stkEvent
stkGlossaryTerm

Template availability and hierarchy are controlled by the STKTemplateAvailability class that implements the 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 homesectionfunctional 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 sectioncontentfunctional 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 sectioncontentfunctional or feature. In other words, it can be assigned under all pages except the home page.