This tutorial introduces the Magnolia templating mechanism. It covers creating your first page template, rendering content from the repository and creating a dialog for content entry. You also learn how a page is composed of areas and components.
What is templating?
The goal of templating is to render something. Rendering makes the content stored in the content management system visible and accessible to site visitors. In Magnolia you can render a page, a specific area of the page, or a component that displays editable content or performs a function.
Templates give the rendered element structure. Structure is crucial for presenting content in the correct order and for building a page layout. An example of a simple structure is headers and footers on a page. Header is at the top, footer at the bottom, and content that varies from page to page is in the middle. Templates make it possible to build such structure. And you can be confident that it remains the same across the website.
Templates also allow you to control what is rendered. You can define what components and how many are allowed in a particular area of the page. Without a template it would be difficult to keep the site design consistent.
Think of a typical corporate website. It has carefully designed branding and corporate identity: colors, fonts, images and page layout all contribute to making every page look and feel consistent and part of the whole. You want to safeguard that identity by protecting elements that should not be editable. A template allows you to define which parts of the page are editable and which are not. For example, an area template allows you to define components that are allowed in that area. If only images are allowed, there is no way for editors to introduce text into the area.
Magnolia provides three types of templates:
- Page is the highest level template. It renders a page. Pages are the building blocks of a site hierarchy. They create a tree hierarchy of parent pages and child pages that you can see in Magnolia AdminCentral and visualize to site visitors in a sitemap and in navigation. Each part of a URI is also a page. For example,
example.com/products/bicycleswould have at least three pages: home page, products section page, and a bicycles page.
- Area is the next level down. Pages consist of areas which can consist of further areas or components. Areas have two purposes: they structure the page and control what components editors can place inside the area. This makes area the most powerful template. It ensures consistency across the site. Areas also provide repeatability. An area template typically loops through the components inside it, rendering the components one by one. Most areas are rendered with containing div elements in the generated HTML so you can control their layout on the page with CSS.
- Component is the smallest block of content that editors can edit, delete and move as a single unit. Think of a component as content that belongs together. At its simplest, a component may be a heading and some text that belong together. However, it can contain almost anything: text and a related image, list of links, teased content from another page and so on.
All templates need the following common properties:
renderTypetells the system which renderer to use. Renderer is a program that understands the syntax of the template script and generates HTML output from it. (To be exact, it can generate any kind of output but HTML is the most common.) Think of the renderer as an application that opens a particular type of file. Your computer knows that a
.dotfile should be opened in Microsoft Word. Similarly, the type property tells Magnolia that a
ftlscript should be rendered with a Freemarker renderer and a
jspscript with a JSP renderer.
templateScriptis written in FreeMarker, JSP or a custom templating language. The script instructs the renderer where to place the content and also contains placeholders for content elements such as headings and images.
dialogis an optional property. Editors use dialogs to enter and edit content. Most templates have a dialog.
These are not the only properties templates can have. But they are the necessary ones.
This tutorial relies on the basic templating framework included in all versions of Magnolia. There is also a better alternative: Standard Templating Kit (STK) is a set of best practice templates for common use cases. It is an out-of-the-box solution designed to speed up the development. After going through this tutorial and understanding how the templating mechanism works, try the STK. You can adapt and modify STK templates to suit your needs.