Page template properties

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

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.

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 name	Value
  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 modelClass, GlossaryTemplateModel, that extends STKPageModel<STKPage> to complete the alphabetical glossary list.

  Node name	Value
  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:
• modelClass: RedirectTemplateModel 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.

• templateScript: redirectMain.ftl renders the path appropriately on the page. You can view this script in STK > Templates /templating-kit/pages/functional/redirectMain.ftl.

  Node name	Value
  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 name	Value
  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. 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.

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

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