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

This tutorial shows you how to create a custom template by extending an existing STK template. The tutorial extends the stkArticle template but you can adapt the steps to extend any STK template that matches your requirements. The tutorial focuses on the template merging process and the use of the extends mechanism and explains the difference between the two. You can download configuration files at the end of the page.

Best practices

As a best practice, Magnolia recommends that you:

  • Create custom templates in your own module. This keeps the STK clean and ensures that your customizations are not lost when the STK is updated. After completing this tutorial, move the custom template definition into your module.
  • Use the STK templates as a starting point. The templates have been extensively tested on all browsers, operating systems and devices.
  • Extend, don't copy. This saves effort and makes updates easier.

stkArticle template features

The stkArticle template is the source template and it's a good idea to be clear on what it contains and how it differs from the prototype template. Below is a brief summary of the merged configuration. We will change many of these so you can use it as a check-list.

The stkArticle configurations come from two sources:

  1. Template prototype that defines the fallback position for all concrete templates. stkArticle uses the following prototype configurations:
    • Without modification:
      • Page properties: templateScript=/templating-kit/pages/main.ftl
      • Areas: htmlHeader, branding, footer, sectionHeader, extras, promos, base, main/breadbcrumb and main/comments. These areas are enabled by default.
      • Navigation: horizontal and vertical. Both navigations are enabled by default.
    • With modification:
      • Areas: main/intro, /content and /contentNavigation (see below).

  2. Template definition that defines changes to the prototype template. stkArticle adds to and/or changes the following prototype configurations:
    • Template properties:
      • bodyID=article.

      • category=content.

      • class=STKPage.

      • dialog=standard-templating-kit:pages/article/stkArticleProperties.

      • modelClass=STKPageModel.

      • renderType=stk.

      • subcategory=article.

      • title= templates.stkArticle.title (key to the word "Article").

      • visible=true.

    • Areas
      • main/intro: dialog=standard-templating-kit:pages/article/stkArticleIntro.

      • main/content: 6 content and 2 teaser components are made available in the /availableComponents node.

      • main/contentNavigation enabled (disabled in the prototype).

STK documentation:

Create the template

The first step is to create the new template in Templating Kit > Template Definitions.

  1. Create a new content node in the /pages folder. This is where page template definitions are stored in the STK.
  2. Add two data nodes:
    1. extends: Set the value to /modules/standard-templating-kit/templates/pages/stkArticle. This tells Magnolia to use stkArtcle template definition in the new template.
    2. title: Type a title. This is used in the Template dropdown list in Website and allows you to identify the template when you create a test page.

At this stage our template is an exact replica of the stkArticle template, except for the title property.

STK documentationn:

Make the template available

The next step is to make the template available to the system so we can view it as we go.

Templates are assigned to a site in the templates/availability/templates node of a site definition. This node is in Templating Kit > Site Definitions /default in the EE and Templating Kit > Site Configuration in the CE. In this node:

  1. Copy the stkArticle content node and rename it to match your new template definition.
  2. Amend the the value of the id property to point to your new template definition. Note the <module name>:<path to definition> format.

STK Documentation:

Create a test page

Once the new template has been made available, it will show up in the list of templates in Website, provided that the visible template property set to true. This is the case in the stkArticle template and therefore by extension also in the new template. Where the template can be assigned in the template hierarchy is determined by the category property. The new template inherits this property from stkArticle and falls into the content category. This effectively means that it can be assigned under all pages except the home page, and cannot be assigned to a root or level 2 page.

Create a new test page in Website and assign the new template to it. Optionally, also create a child page structure at this stage, to later test the behaviour of dependent pages and components.

STK documentation:

Enable the platform area

The first change we make is to enable the platform area with inheritance enabled in the area. The platform area is fully configured, but disabled in the prototype template, and is not used by stkArticle. The prototype defines the area as a list area and makes the stkTeaserPaging component available.

To enable the platform area:

  1. In Template Definitions under the new /<template name> node, create a new content node structure /areas/platform.
  2. Add a data node enabled and set the value to true.
  3. Create a child content node /inheritance under the /areas/platform node.
  4. Add two data nodes:
    1. enabled and set the value to true.
    2. components and set the value to all. This makes the available component cascade automatically on child pages. As an alternative you can set this to filtered and add the generic inheritable field to the component dialog to allow editors to choose whether or not to the component should be inherited. 

The new template now includes the platform area that renders after the breadcrumb and spans main and extras areas. In preview mode the breadcrumb renders perfectly.

STK documentation:

Modify the Page Header component

Our new template is intended to be used for news (as opposed to standard article) pages, so we modify the Page Header component in the /main/intro area to disable categorization and make a few other changes.

To modify the Page Header component:

  1. In the /areas node, create a new content node structure /main/areas/intro.
  2. Add the following data nodes:
    1. dialog and set the value to standard-templating-kit:pages/<template folder>/<intro dialog name> (to be created)
    2. A node for each show property that you would like to modify. All of these properties are set to true in the prototype, except showTOC. In our template we add:
      1. showCategories set to false to disable categorization.
      2. showTOC set to true to add a Table of Contents.
      3. showImage set to false to not render an image in the component.

Next we create a new dialog to accommodate the settings in the intro area.

To create a new dialog:

  1. In Dialog Definitions create a new folder for the template in /pages
  2. Copy an existing dialog that is the closest match for the new dialog and add and delete as necessary. We copied the stkNewsIntro dialog, renamed it stkArticleExtensionIntro and deleted the image and imageLocation fields.
  3. Change the label properties for the dialog definition and tabMain to identify the new dialog. These properties render in the dialog header and the tab label.

You can add a properties dialog if you like. The stkArticleProperties dialog that our template points to is fine for our purposes.

Here's the new Page Header component and associated dialog.

  • A TOC using the titles of each component in the content area will be rendered.
  • The tabCategorization that is available in the stkArticle template is not available.
  • The Print and Bookmark features are retained.
  • Editors can add all the normal content, except an image. Our dialog includes the location field that is not available in the stkArticle template.

STK documentation:

Change the template subcategory

Our template is intended for news pages and we want pages based on it to be included in aggregation components that render results of the template subcategory news. A number of STK components do this, for example the stkTeaserNewsList, stkExtrasNewsList and stkExtrasContentTypeRSSFeed components.

To change the template subcategory, in the /<template name> node add a data node subcategory and set the value to a new subcategory, news in our example.

We demonstrate the use of this property later in the Test the template section.

STK documentation:

Add a new area

Next, we add a new area in main area. The area will contain a stkTeaserNewsList component. In the new template we want this component to render in a specific position (below the content area) on the page. 

To create the new area:

  1. Copy an existing area configuration. We copied the stkSection/areas/main/areas/opener configuration.
  2. Position the coped configuration as a child of the /areas/main/areas node and amend as necessary. 
  3. In our template the new area is named teaser and:
    1. Is a single area meaning that only one component can render.
    2. Is optional meaning that editors can delete it.
    3. Does not explicitly reference an area script so default standard code is used to render it.
    4. Sets the title property to Teaser which renders in the area bar.
    5. Makes the stkTeaserNewsList component available in the /availableComponents node.
  4. Add a new data node templateScript to the areas/main node and set the value to a valid path. We will create this script next and store it in /templating-kit/pages/custom/mainArea.ftl.

The new template cannot use the same script as stkArticle to render main area because the /content/mainArea.ftl script does not include the new area. You can create a new script in the templates workspace. To do this:

  1. In Templates create a new child folder in /templating-kit/pages. Our folder is named /custom.
  2. Copy the /content/mainArea.ftl script and add it to the new folder.
  3. Open the script for editing and add [@cms.area name="teaser"/] after the content area tag.
  4. Check the Enable template box to ensure that the script is served from the repository.

Refresh the test page. The teaser area now renders after the content area, and the stkTeaserNewsList component is available.

STK documentation:

Override available components

In the stkArticle template, the components available to editors in main/content area include two teasers, stkTeaserHorizontalTabbed and stkDownloadList. We want to exclude the teasers and only allow content components in the area.

To exclude components:

  1. In the /areas/main/areas node create a new content node /content.
  2. Add a data node extends to the new /content node and set the value to override. This tells Magnolia to ignore the corresponding definition in the stkArticle template.
  3. Copy the stkArticle/areas/main/areas/content/availableComponents node and position the copy as a child of the new /content node.
  4. Delete the components that you do not want to make available. We deleted the stkTeaserHorizontalTabbed, stkDownloadList and STKContact components.

Refresh the test page and click New Content Component in main/content area. Only the components made available in the new template definition are available to editors in the selector dialog.

STK documentation:

Disable available components

The stkArticle template does not modify the base area. The components available in the area are configured in the prototype template and result from the template merging process, not the extension mechanism. For this reason, individual components can be omitted using the enabled property and the extends=override property is inappropriate.The prototype template makes two components available: stkTeaserCarousel and catCloudWide and in our template we limit this to a single component. We also change the area type to prevent editors from adding more than one component.

  1. To disable components in the base area:
    1. In the /areas node, add a new content node structure /base/availableComponents.
    2. Add a new child content node named to match that in the prototype definition, stkTeaserCarousel in our example.
    3. Add a data node enabled and set the value to false.
  2. To change the area behavior add two data nodes to the /base node:
    1. type and set the value to single. In the prototype this is a list area.
    2. templateScript and set the value to a valid path. We will create this script next and store it in /templating-kit/pages/custom/baseArea.ftl.

The new template cannot use the same script as the prototype to render base area because the /global/baseArea.ftl script is a standard list area script.

Create the new script in the same way as in Add a new area above using the following standard single area code:

baseArea.ftl
[#if component??]
     [@cms.component content=component /]
[/#if]

Refresh the test page and click New Base Component in base area. Only the catCloudWide component is available.

STK documentation:

Change the extras area layout

Next, we change the layout of the extras area to demonstrate one of the available configuration options and the use of body classes and ids.The new template will use the extras/module area that spans two columns, with two extras columns beneath it. Enabling the module area changes the page layout and therefore also the automatically resolved bodyClass. The BodyClassResolver Java class takes the vertical navigation and, main and extras areas into account and must resolve to an allowedBodyClass. In the new template we want to retain the vertical navigation, render a single column in main area and two extras columns. This would resolve automatically to nav-col-subcol-subcol which is NOT an allowed bodyClass. We therefore override the bodyClass by explicitly defining an allowedBodyClass in the template. It is also necessary to disable the promos area to ensure that the content fits on the page.

The stkArticle template does not modify the extras area prototype configuration. In the prototype:

  • The module area is disabled by default. It is a single area and the stkExtrasHorizotalTabbed component is available.
  • The extras1 and extras2 areas are identical and enabled by default. These areas are list areas in which numerous components are available. They are rendered by the extrasArea.ftl script that only renders the extras2 area if the columns property is set to 2.

To modify the prototype configuration:

  1. To change the page body class, in the /<template name> node add a data node bodyClass and set the value to col-subcol-subcol. This is an allowedBodyClass.
  2. To use all available extras child areas, in the /areas node:
    1. Add a new child content node /extras.
    2. Add three data nodes:
      1. class and set the value to info.magnolia.module.templatingkit.templates.ExtrasArea. The addition of this property is necessary because the prototype defines a different class to the default ConfiguredAreaDefinition class.
      2. columns and set the value to 2. This changes the prototype configuration of 1.
      3. small and set the value to false. This changes the prototype configuration of true.
  3. To enable the module area:
    1. In the /areas/extras node, add a new content node structure /areas/module.
    2. Add a data node enabled and set the value to true.
  4. To disable the promos area:
    1. In the /areas node add a new child content node /promos.
    2. Add a data node enabled and set the value to false.

Refresh the test page. The extras area uses all available child areas . The <body id> tag includes the bodyID=article property assigned in the stkArticle template. This id is used for all content templates. The class attribute in the tag includes the bodyClass property defined in the new template. Compare this tag to a page based on the stkArticle template. No class attribute is added because the page resolves to the default bodyClass of nav-col-subcol.

STK documentation:

Add an autogenerated component

Next we add an autogenerated stkHTML component that renders an embedded video in the extras/module area. The video will render in the area on every page based on the new template. We also disable the stkExtrasHorizotalTabbed component that is made available in the prototype and make the area non-editable, preventing editors from deleting or changing the autogenerated component.

  1. To add an autogenerated component in the module area:
    1. In the /areas/extras/areas/module node, add a new content node structure /autoGeneration/content/<name>. You can name the component anything your like (magnolia5 in our example). 
    2. Add a data node generatorClass to the /content node and set the value to info.magnolia.rendering.generator.CopyGenerator.
    3. Add three data nodes to the /<name> node:
      1. editHTML and insert the HTML code in the Value column.
      2. nodeType and set the value to mgnl:component.
      3. templateId and set the value to standard-templating-kit:components/content/stkHTML.
  2. To disable the prototype component:
    1. In the /areas/extras/areas/module node add a new content node structure /availableComponents/stkExtrasHorizontalTabbed.

    2. Add a data node enabled and set the value to false.

  3. To make the area non-editable add a data node editable to the /areas/module node and set the value to false.

Refresh the test page. The autogenerated component renders in in the module area and the area bar no longer renders.

STK documentation:

Other template properties

The stkArticle template has other page properties that we have not used in the new template. These properties are inherited by the new template and we have elected not to change them. Here's a brief discussion of each property:

  • class: All STK templates use the STKPage class that defines the base template definition.
  • modelClass: The majority of STK templates use the STKPageModel modelClass that extends STKPage.You can extend this class to provide custom business logic. For examples of how to do this see the stkRedirect and stkGlossary templates. Both templates use modelClasses that extend STKPageModel.
  • category:This property determines where in the page hierarchy a template may be assigned. Available options are:homefunctionalsectionfeature and content. We retained content because it is appropriate for the template, but you can experiment by changing this property.
  • dialog: Each template references it's own stk<template name>Properties dialog configured in Dialog Definitions. With the exception of stkHomeProperties, these dialogs are identical in each edition and extend the basePageProperties configuration in the /generic/master folder.. tabDependencies is an EE feature. Meta information (keywords and description) entered by editors in tabMetaData is rendered by the htmlHeader.ftl script. You could for example extend the dialogs and script to include a robots tag.
  • renderType: STKRenderer assigned by value stk is the STK-specific renderer used by all STK templates (pages and components).

STK documentation:

Add CSS

You can add template-specific styling at a template level. To demonstrate we add a few style rules to the new TOC that renders in the Page Header component. It is rarely necessary to do this and it may well be a better idea to modify the main CSS file styles.css accessible in Resourcestemplating-kit/themes/pop/css.

To add template-specific CSS:

  1. In the /<template name> node add a new content node structure /cssFiles/<name>. In our example name=extensionStyles and you can name this node anything you like.
  2. Add three data nodes:
    1. farFutureCaching and set the value to true.
    2. link and set the value to the path to the new sheet (to be created). You can point to any valid internal or external URL.
    3. media and set the value to a valid media type.

You can create the new CSS sheet in the resources workspace. To do this: 

  1. In Resources, create a new item of type Processed CSS and name it. Our sheet is named articleExtensionStyles.css.
  2. Edit the new item and insert the style rules in the dialog.
  3. Save.

The new sheet will automatically be loaded from the repository. There are alternatives in the Advanced tab of the Edit dialog that you can explore.

Refresh the test page. The htmlHeader.ftl script has added the new sheet in the <head> element of the HTML and the new styles render on the page.

STK documentation:

Add JavaScript

You can also add template-specific JavaScript at a template level, in the same way as you add styling. This is also rarely necessary as the pop theme includes all you will most likely need. To demonstrate we added a script that enables a timing event in an infinite loop. You can find the code (Javascript and HTML) at w3schools.com.

To add template-specific JavaScript:

  1. In the /<template name> node add a new content node structure /jsFiles/<name>. In our example name=timer and you can name this node anything you like.
  2. Add two data nodes:
    1. farFutureCaching and set the value to true.
    2. link and set the value to the path to the new script (to be created). You can point to any valid internal or external URL.

You can create the new JavaScript in the resources workspace. To do this:

  1. In Resources. create a new item of type Processed Javascript and name it. Our script is named timer.js
  2. Edit the new item and paste the script into the dialog.
  3. Save.

Refresh the test page and note that the htmlHeader.ftl script has added the new script in the <head> element of the HTML. We demonstrate the use of this JavaScript in Test the template > JavaScript.

STK documentation:

Test the template

Here's the body of the source stkArticle template compared to the new stkArticleExtension template.

  

Next we add test content to the test page and child pages to ensure that all areas and components are behaving and rendering as expected.

platform area

The stkTeaserPaging component requires minor CSS adjustments because the component does not fill the entire platform area. To keep things simple, we added the amended style rules to the sheet added in Add CSS above. Ideally, you should amend the main sheet styles.css accessible in Resources > /templating-kit/themes/pop/css. You can find the relevant rules in the /* ### TW-PAGING ### */..../* Inside #wrapper-2 -> Platform Area */ section. We used the child test pages for the internal teaser items and checked that the component was inherited by all child pages. Here's the amended component

intro area

Here's the Page Header component with amended styling.

teaser area in main

The new main/teaser area renders the stkTeaserNewsList component. It picks up the child pages based on the subcategory of the new template.

contentNavigation area

The contentNavigation area is enabled in the stkArticle template and therefore also in the new template. The area renders above the Page Header component and  allows a user to navigate to pages deep within the page hierarchy.

STK documentation:

extras area

Our template has two extras columns that are marginally smaller than the default single column. We only picked up one styling error with the stkExtrasCalendar component so we went back and disabled it in the extras2 area of our new template. 

JavaScript

To test our new JavaScript we added a stkHTML component in main/content area with the following code:

<form>
<input type="button" value="Start count!" onclick="doTimer()" />
<input type="text" id="txt" />
<input type="button" value="Stop count!" onclick="stopCount()" />
</form>
<p>
Click on the "Start count!" button above to start the timer. The input field will count forever, starting at 0. Click on the "Stop count!" button to stop the counting. Click on the "Start count!" button to start the timer again.
</p>

Here's our test component. Without the addition of the timer.js script the timer does not work.

Download the template

Download article-extension-template.zip and import the XML into the demo-project website and configuration.

 

1 Comment

  1. I like the basic idea of this tutorial, however there's one little quirk I'm not too happy with. The example shows that you should create your template under Templating-Kit > Template Definitions. I can see why this would be beneficiary for someone who wants to do a quick tutorial with the bundle or so, but this tutorial should mention that as a best practice, the new template should ideally reside in your own module under templates > pages. We do it in the dev training as well that we let the participants create templates in a "foreign" module but then we have them move over everything to their own and update paths and IDs to show how tedious it is to correctly implement this once you started "wrong".