Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current ·  View Page History

Templating

Basics

Before attempting to write new STK templates, we suggest that you first become familiar with Magnolia templating.The following guides and resources are available:

The STK uses Freemarker as the standard templating language. You can find a Magnolia-related introduction to this language is given atFreeMarker Primer.

STK Templating

FreeMarker Template Scripts

All of the FreeMarker STK template scripts are accessible in the  Templating Kit - Templates workspace. The templates can be immediately changed in Magnolia itself, which is ideal for evaluation, prototyping or smaller projects.

Edit Dialog:

Once a template has been modified one has to check "enable template" to tell the STK to use the customized template.

Template scripts loading

The template scripts can be loaded in three ways. The system searches for a template in the following places and order:

  1. in the filesystem of the webapp
  2. in the inplace-templates workspace (the template must be enabled to be considered)
  3. in the class path (this is where the default STK templates are located)

The question is now where would you ideally put the scripts:

  • webapp: you want to edit real files but not going as far as creating a java project
  • inplace templates: prototyping, if you use magnolia as a service or wiki style system
  • class path: if you use a module (is recommended for bigger projects or to facilitate team collaboration)
    • modifications you make in you IDE are then immediately loaded

main.ftl

This is the default entry point for all templates and is configure in the template prototype of the site definition. It is a very good entry point to explore the system.

Following an abbreviated version of that template script.

Lets analyze some parts in detail.

Loads the tag libraries and assign them.

The template loads dynamically the template which has been configure for the HTML header. This template is responsible to load the various CSS and javascripts. To extend the HTML header one could do the following:

  1. create a custom header template (for instance /myproject/templates/global/htmlHeader.ftl)
  2. include the original header template ([#include /templating-kit/templates/global/htmlHeader.ftl])
  3. add the addition content (some special meta tags, inline javascript, ...)

The same schema can be applied for many other use cases.

The bodyID and bodyClass is set. The bodyID is configured in the template definition and allows custom styling per template while using a single CSS file. The bodyClass is calculated by the model if not configured directly on the template: ${model.bodyClass}. It transforms the actual configuration into an allowed body class. The considered configurations are:

  • vertical navigation shown? can change based on the page's level)
  • floating teasers
  • extras (enabled, columns, small or big)

The bodyClass is then used in the CSS to style a page differently. For instance the width of the main div will be different if no vertical navigation is shown, which is the case as long the current page has not reached a deep enough level to extend the horizontal navigation.

Adds the main bar and configures it to use the dialog specified in the template definition.

This snipped can be seen in many variation for all the areas. It checks if an area is enabled and if yes included the configured template.

STK specific context object

In addition to the normal context objects (being content, def, ..) we add also an stk object. Some of the common objects are enhanced by additional features.

Object

Note

stk

An instance of the STKUtil

content

Same as normal but will print the content HTML encoded by default. To avoid that one uses the following code: $

Unknown macro: {stk.decode(content).title}

def

In case of a template definition most likely an instance of STKTemplate

model

Depends on the modelClass defined in the template but most likely an instance of an STKTemplateModel

Following some useful snippets

Inheritance

Resources (Javascripts and CSS)

\

Configuration

CSS and javascript files to load can be defined on three levels.

  • theme
  • site definition
  • template definition

It is not needed that the resources are stored in the resources workspace. They can point to any valid internal or external URL.

Bypassing the workspace

The content in the workspace can be bypassed by checking the "bypass" option in the advanced tab. In that case the corresponding file in the class path will be used. This is mainly useful while developing or testing.

FreeMarker based resources

If a resources is of type "processed", the content is interpreted as a FreeMarker template. This allows to use constants, variables or any other logic.

In the dialog of such a resource one can also define the model class to use so that one can use any Java logic or Magnolia functionality.

Aggregation of Javascripts

/templating-kit/js/all is an aggregation script combining all child pages into a single file. It also sets a context path variable used by some of the scripts.

Site aware Resources

A resource will never know the current page as it is only loaded once per site. This must be so that heavy javascripts or CSS files are only downloaded once and cacheable.

But the resource can access the site definition through the model: ${model.site}

Labels
  • None