The Standard Templating Kit is a best-practice framework for creating websites. It builds upon the generic templating mechanism. The kit ships with configurable, production-ready templates for common use cases such as articles, news, events, site-maps and image galleries, while letting developers and creative designers build completely custom sites. Templates can be written in JSP and Freemarker or another templating language. Renderers for Freemarker and JSP are provided out-of-the-box. You need to implement your own renderer for a custom templating language, see FreemarkerTemplateRenderer for inspiration.

• Contents
• Benefits
• STK components
• Site definition
• Areas
• Template inclusion
• Customization
• Template prototype
• Static HTML prototype
• Design with CSS
• Layout and grid
• HTML structure
• Body classes and IDs
• CSS configuration
• Learn more

Contents

Standard Templating Kit includes:

• Reusable paragraphs
• A mechanism for assembling page templates through definition rather than coding.
• A mechanism for creating custom paragraphs without affecting or even touching the page templates that use them.
• A set of use case driven page templates which can be used as such, modified or replaced with your own templates.
• Clear and clean separation of duties on server and client side: HTML structure (template) is created with Freemarker or Java Server Pages, business logic is written in Java or Groovy, content is stored in a JSR-283 compliant Java Content Repository, design is controlled with CSS, and client-side functionality is done with JavaScript (jQuery). A static HTML prototype is provided for designers who prefer to start with CSS and a basic HTML wireframe.

Benefits

• Out-of-the-box solution. The use case driven page templates shipped with the kit provide a quick start to building your website. The kit gives you a significant head start since much of what you need is already provided. Less effort generally means you will be faster but more importantly it means your project will be more predictable. You have less uncertainty, which for project managers means less risk.
• Use case based templates. Templates and paragraphs included in the kit are all based on real-life use cases. Templates include home, section, search, news, events, contact form, article and many more. Numerous ready to go live paragraphs are also available such as content paragraphs, teasers, stages, promos, event lists and more.
• Configurable layout and style. The look and feel of the website is controlled mainly by a single CSS file. Since the HTML structure is designed to be styled by CSS, the look and feel of the site can be changed without touching the templates. And since CSS is configured in the site configuration, you can create a custom CSS for each site.
• Role-based development. Designers and CSS developers don't necessarily need to know anything about Magnolia CMS in order to create a compatible site design. They can start with the static HTML prototype shipped with the system. From the prototype they can pick an HTML structure that is a close match to their original design and modify it further. Style sheets are also provided.
• Accessibility. The generated HTML adheres to W3C WCAG2m and German BITV accessibility standards. Invisible navigation messages for vision-impaired users are included.
• Extensibility. As the template script and model class are separated, you can modify the templates or extend the model. Many aspects can be configured in the template or site definitions without writing code. For example, you can define paragraphs that are available for individual page templates and their positioning.

STK components

The STK consist of:

• Site definition. A site definition configures the behavior of your site. A site is one tree in the website workspace. The definition determines the theme, available templates, available paragraphs and more. You can have multiple site definitions, each configuring one or more sites. This mechanism allows you to configure multi-site setups.
• Theme. A theme gives the site its visual identity through the use of images, colors and typography. A theme consists of Cascading Style Sheets (CSS), Javascript files, and an imaging configuration which tells the Imaging module how to resize and crop images for a particular page or paragraph. Magnolia CMS ships with an example theme called "pop". You can see it in action on the demonstration sites (see below).
• Templates and paragraphs. STK templates are normal Magnolia CMS templates but make use of the template definition mechanism. Thanks to this, all templates (Home, Section, Article...) use the same base. In a similar fashion the kit provides paragraphs for use cases such as stkLinkList, stkTextImage, stkQuotedText etc.
• Digital asset management (DAM) support. You can place images and videos on pages by uploading them from the user's computer or by selecting from the built-in document management system. Both of these default mechanisms can be enabled in the site definition. If you want to use your own mechanism, for example to get images from an external server, you can plug in a custom image processor.

Site definition

A site definition applies templates, themes and internationalization support to your site. It consists of:

• Template prototype. Is a base definition of a site-wide template from which all concrete templates (Home, Section, Article...) inherit. When building a site you will do the bulk of work here, such as defining the overall page skeleton.
• Template availability. Registration of available templates.
• Internationalization and localization (i18n). Enabling i18n support in the site definition allows authors to write foreign-language content. When enabled, the mainBar has a language dropdown (this feature is available with the Extended Templating Kit). Dialogs display the language identifier (en, fr, de...) to make it clear what language should be entered. Foreign-language content is served to visitors at a specific URL, such as www.mywebsite.com/de/article.html. Redirecting visitors to the language-specific URL is configured in the web server.

• Domains. Mapping of a domain name to a site. (Extended Templating Kit)
• Mappings. A mapping applies a site definition to a site. Here you can use prefixes and handles. For example, if a prefix such as dms is detected in the request the requested asset is served from the repository given in the repository property. A handle can be used in building the URI. For example, if the requested URL contains /demo-project alone, map it to the website repository. If it contains /demo-project/docs, map it to the dms repository.

The Standard Templating Kit ships with two fully-functional demonstration sites:

• Demo project shows how templates work in realistic site context. It has working examples of article, news, event and many other page templates as well as paragraphs such as video, teaser and stage.
• Author instance username/password: superuser/superuser
• Public instance
• Demo features shows the same templates grouped categorically: content templates, special templates, aggregation paragraphs, areas, sections and modules
• Author instance username/password: superuser/superuser
• Public instance

Areas

The page templates shipped with the Standard Templating Kit organize the page layout using areas. These are controllable blocks, typically rendered as div elements, that help you customize the template structure.

An area definition is used to configure whether the area is enabled and, if enabled, what template is used to render it. It also defines what paragraphs are allowed within the area.

Typically each area is wrapped in a div element, having a correspondingly name ID attribute, for example main area has id=main.

Note!: An area is not the same as a paragraph. Paragraph is a content element with an associated paragraph definition while areas are structural elements in the template script. In fact, areas are dynamic include directives which together compose a single template script.

The following diagram illustrates some key elements you will find on a page based on the article page template. The box captions indicate div element ID attributes. For example, the element that renders the vertical navigation on the left is <div id="nav">.

Template inclusion

Templates at higher level can include lower-level templates using Freemarker's #include directive. This approach allows you to modularize and re-purpose your template scripts. It also has the benefit of keeping scripts brief and readable.

The following diagram shows how inclusion works. The page template has a header area. Inside the header div element there is a Freemarker #include directive that calls another template script, header.ftl. The header template script in turn includes two further templates to render branding and horizontal navigation.

Numbered items:

1. Includes the template script configured in template definition (configured either in the prototype or overwritten in the concrete template).
2. Template script referenced from the template definition.

Customization

This dynamic approach allows you to combine your own templates with those of STK. Use the STK templates as much as you can to speed up development. When you can't move further without customizing, create your own template.

Two customization options:

• Change the main template used by all STK templates if you want to change the main HTML structure. This is configured in /prototype/templatePath. The default value is /templating-kit/templates/main.ftl.
• Reconfigure template scripts used for specific areas.

In most cases you would copy an existing template. In the site definition, override the used template by setting the template attribute to the customized one.

Template prototype

The prototype template definition is a good entry point for understanding the STK. It is a "fallback object" for all template definitions of a site. Any template will extend the prototype, which means any template configuration that you don't define in the template is automatically inherited from the prototype. It is likely that you can take advantage of the prototype templates and reuse them for your custom site with small changes.

Examples of template configuration options available in the prototype site definition:

This is what happens when a template prototype is merged with a concrete template:

1. Template prototype is the basis.
2. Concrete template definition adds and overrides.
3. The result is exposed as the template definition (def) to the template script.

stkHome defines which paragraphs are available in the mainArea. It also uses a custom template script for the mainArea and disables the extrasArea. The prototype defines the main template (main.ftl) and pre-configures the main and extras areas.

Static HTML prototype

The STK bundle (download) ships with a static HTML prototype. It is a collection of STK page templates delivered as stand-alone HTML files. Referenced CSS and images are also included. The static prototype is aimed at creative teams who don't know how Magnolia CMS works or have no particular desire to learn it. It allows designers to work on positioning, typography and color outside of Magnolia CMS, using their own tools, in their own environment.

You can (and should) use the HTML prototype to develop your CSS. The advantages of this approach include:

• See all possible variations of an element instantly
• Perform CSS programming independent of Magnolia CMS
• Better testability
• Faster turnaround

The static prototype contains an index page which serves as the starting point for paragraph and page templates provided with the STK.

Navigation at all levels is also available at a single glance. Developing a CSS against this view saves a lot of time when you can see all variations right away.

Design with CSS

The modular templating approach gives creative designers free hands. Positioning, layout and styling is convenient with CSS given that each key page element can have its own template script and is enclosed in a div element that has an ID attribute.

Magnolia CMS supports role-based development by letting everyone work on what they are good at. Designers can change the appearance of a page without having to change a template. Likewise, templates do not become cluttered with design fragments.

Layout and grid

The template layouts are dynamic. The default layout of three fixed columns is optimized for a screen resolution of 1024. The grid is extremely flexible and offers easy grid variations.

The dynamic template layouts change on the fly, to adapt to the user's viewport:

• For larger screens, with a minimum width of 1200 px an extra style: wide.css is added. The effect of this is that an additional promo sidebar is displayed on the right of the screen.
• For medium screens, width 981-1199 px, the layout accommodates the narrower viewport by displaying promo sidebar beneath the main content.
• For small screens, with a maximum width of 980px an extra style: small.css is added. The main area displays two columns of teasers instead of three.

Wide: min. width 1200 px	Medium: 981 to 1199 px	Small: max. width 980 px

The technique used to achieve this is CSS media queries (and JavaScript for IE6). For older browsers that do not recognize JavaScript it is completely unobtrusive and the default CSS resolution is 1024 x 768 px.

HTML structure

HTML structure, as provided by the default template:

Body classes and IDs

The body class attribute is used to control the number of columns and the column width. It provides for instance information about whether we have vertical navigation or not.

The body classes are automatically generated by the STK system. STK determines which body class to render based on the specific template definition. Alternatively, you can define a property bodyClass which bypasses the automatically generated value. This overwrites the auto-generated body class value.

Some body classes are:

• nav-col-subcol: Three-column setup with navigation on the left and a small extras area.
• nav-col: Two-column setup with a navigation on the left and one large content column.
• col-float3: One large column and three floating teasers. Home page is an example of this.

Some examples of body IDs are:

• home
• section
• article
• image-gallery

CSS configuration

Style sheets used with STK templates are stored as content nodes within Magnolia CMS. This allows you to manage them in AdminCentral instead of having to work at the file system level.

STK ships with a collection of style sheets targeted to different viewports and media. You can see these sheets at work on the demonstration sites and the static HTML prototype.

Referencing a style sheet works like this:

1. Style sheets are stored as content nodes under Templating Kit > Resources. They are organized into folders according to the theme they belong. In this example, the pop theme has five style sheets aimed at different media and viewports.
   
   
2. In Templating Kit > Themes, a theme definition contains a link to each stylesheet. It also defines the targeted media type (screen, print etc).
   
   
   Note that in the media property you can use CSS3 media queries to test the features of the output device. The sheet is applied if the test evaluates to true. In the example above we evaluate the minimum width of the viewport before applying the wide sheet.
   
   
3. In the htmlHeader page template, a Freemarker #list directive collects the style sheets from the pop theme. It creates link elements and writes them in the page head element.

[#list model.site.theme.cssFiles as cssFile]
   <link rel="stylesheet" type="text/css" href="${cssFile.link}" 
   media="${cssFile.media}" />
[/#list]

Learn more

Check out these videos of STK templates in action:

• Introduction to STK and basic demonstration.
• Glossary, grouped teaser paragraphs, events overview, FAQ.