All Web pages created with Magnolia CMS are based on templates. Templates ensure that page structure and presentation remain the same while the content varies from one page to another. For example, an event template helps you generate event pages that look and feel the same but display a different unique event each.

The system generates pages by merging a template with corresponding content from the repository. The position and inclusion of each paragraph on the page is defined by the page template. In many instances, the page template will allow authors to choose from a number of different paragraph types in a single content area.

• Pages and paragraphs
• Templating mechanism
• Component relations
• Templating languages
• Tag library
• Example of CMS tags in use
• Templating support objects
• Accessing your own Java methods from Freemarker

Pages and paragraphs

Content nodes in the JCR hierarchy are rendered as headings, paragraphs, images, menus, forms, Javascript, meta-data and many other things. The following diagram shows the relationship between some content nodes and the corresponding page elements.

Note! The diagram shows the detailed JCR view on the left. This is not how authors see content. The user interface for authors and editors hides much of the complexity, providing a user-friendlier way to manage pages and paragraphs.

Numbered items:

1. An article about basketball in the New York Times Sports sections has the following page properties:
• title rendered as an H1 element on the page, "Bulls and the Thunder Make a Stand".
• date and author rendered on the dateline.
• abstract to provide an introductory paragraph.
2. The next element on the page is the main collection which contains paragraphs.
3. Paragraph 0 is a text paragraph ("LeBron James scored 13...") with a matching image. The image file and its caption and credit are stored in the document management system (DMS).
4. Paragraph 00 consist of text and an optional subtitle element "THUNDER 101, LAKERS 96".
5. The page ends with a footer singleton paragraph which is a kind of placeholder. It can contain content such as a copyright statement.

Templating mechanism

Magnolia CMS templating mechanism consists of the follow components:

• Template definition makes a template script available to the system by providing a name for it. It is the configuration for the template script. For instance, it defines the model class to use.
• Template script renders the content. The script is written in FreeMarker, JSP or a custom templating language. The script instructs the renderer where to place the content on the page and also contains placeholders for content attributes such as headings and images.
• Dialog is used to enter and edit content. It is a customized HTML form with fields for entering text and meta data and selecting images.
• Content for the page or paragraph is retrieved from the repository. It may contain text and references to images that need to be rendered. The content node meta data assigns it to a particular template definition. This way the rendering engine knows which template definition applies to the content. Through the definition, it can then choose the correct renderer. Note that the reference to a template definition is only a suggestion. It is also possible to use something else to render the content. You might define an alternative template when rendering content for a mobile device, for example.

Component relations

Below you find a more detailed map of relationships between the components that make up the template mechanism. Starting at the top left corner, a template definition defines the template script used to render the content. The location of the script is given in the templatePath property. The template definition also assigns a dialog definition in the dialog property. The dialog definition is a group of configuration nodes just like the template definition. It defines what tabs and fields should be present in the dialog.

The template definition further defines a modelClass. Model is a Java program that holds your business logic. The model can do any task required such as execute a Google search or calculate an insurance policy. It holds the results of the logic execution and passes them to a renderer. The renderer includes the results on the page as instructed by the template script. The script tells the renderer where to place the content. It contains placeholders for content attributes such as headings, images and the results of the business logic execution.

A Web page is the output of the rendering process where template and content are combined.

The following class diagram shows the relationships between the objects collaborating in rendering of a template.

Templating languages

The system provides two renderers out-of-the-box: JSP and Freemarker.

JSP stands for Java Server Pages. It is an extension of Java Servlet technology for combining Java server-side programs and HTML.

Writing a Magnolia CMS paragraph in JSP:

<?xml version="1.0" encoding="UTF-8" ?>
<jsp:root version="1.2" xmlns:jsp="http://java.sun.com/JSP/Page" xmlns:c="http://java.sun.com/jsp/jstl/core"> 
    <jsp:directive.page contentType="text/html; charset=UTF-8" 
    session="false" />
    <c:if test="${not empty content.image}"> 
        <img src="${pageContext.request.contextPath}${content.image}" 
        class="contentImage_${content.imageFloat}" 
        alt="${content.imageAlt}" /> 
    </c:if> 
    <c:if test="${not empty content.title}"> 
        <h2>${content.title}</h2> 
    </c:if> ${content.text} 
</jsp:root>

With Magnolia CMS 4.0, we added support for Freemarker for several reasons: not only for its flexibility, cleaner syntax and better error reporting but also because it does not depend on the file system; templates don't have to be extracted to the file system so they can easily be stored in the repository.

Writing the same paragraph in Freemarker:

[#if content.image?has_content]
    <img src="${contextPath}${content.image}" 
    class="contentImage_${content.imageFloat}" 
    alt='${content.imageAlt!""}' />
[/#if]
[#if content.title?has_content]
    <h2>${content.title}</h2>
[/#if]
${content.text!""}

You can mix and match templates and paragraphs using both templating languages at will. You can also use another templating language. If a renderer for your language is available, it is likely that you can incorporate it into Magnolia CMS. This allows you to use a templating language that you are already familiar with.

Tag library

The Magnolia CMS tag library allows developers to customize the authoring environment and create templates in a fast, efficient and re-usable way. The system additionally supports third-party tag libraries such as JSTL to minimize the amount of code developers have to write.

Most important tags:

mainBar. Displays a toolbar that allows you to change page properties and switch to the preview mode. This tag can also add CSS and JavaScript links on the page if not previously defined but it is recommended to you add the cms:links tag to the header of the page instead. CSS links are not valid inside the HTML body element.

[@cms.mainBar label="Page Info" dialog="stkHomeProperties" /]

newBar. Displays a toolbar that allows you to create new paragraphs. The list of available paragraphs is passed as a list.

[@cms.newBar contentNodeCollectionName="mainColumnParagraphs" paragraph="samplesTextImage,samplesDownload,samplesLink" /]

editBar. Displays a toolbar that allows you to edit a paragraph. This tag is often used within contentNodeIterator, which in turn will set all relevant parameters automatically.

[@cms.editBar /]

contentNodeIterator. Iterates over a contentNode collection. This tag is used whenever you want to loop over content, typically paragraphs. Parameter contentNodeCollectionName contains the name of the contentNode you are looping over. The contentNodeCollectionName is created in the first place by providing the name to a newBar. This will result in elements being created within that contentNode, and allows you to loop over them later.

[@cms.contentNodeIterator contentNodeCollectionName="main"]
   [@cms.includeTemplate /]
[/@cms.contentNodeIterator]

includeTemplate. Delegates the task of rendering a paragraph to an appropriate ParagraphRenderer or includes JSP. When used within contentNodeIterator the parameters are provided automatically by the loop.

[@cms.includeTemplate contentNode=content.footer /]

Example of CMS tags in use

Here is an example how tags are rendered.

1. The mainBar tag creates a toolbar at the top of the page for setting page properties.
2. The main area of the page includes a contentNodeIterator tag. It looks for any paragraphs that reside inside the main area and includes their paragraph scripts using the includeTemplate tag. Note that the paragraph with the basketball players is not rendered by the page script but the included paragraph script below it. The editBar associated with this paragraph is added in the paragraph script, not in the page script.
3. A newBar creates a toolbar that allows authors to add new paragraphs on the page.
4. The footer section also uses the includeTemplate tag. It calls another paragraph script (not displayed) that creates navigation links and a copyright statement.

contentNodeIterator (2) and newBar (3) are typically used together. contentNodeIterator renders the stored content, in this case the main collection. newBar stores new content into the main collection. The collection name is not fixed, it is defined within the script by the developer.

Templating support objects

These objects are available to template scripts to simplify development.

Example usage:

[#-- Accessing content --]
The value of "someProperty": ${content.someProperty}
Accessing a child node: ${content.childNode}
Accessing the child node collection: ${content?children}
Accessing the parent node: ${content?parent}

[#-- Special content properties --]
The current node handle: ${content.@handle}
The current node name: ${content.@name}
The current node uuid: ${content.@uuid}
[#-- MetaData --]
The creation date: ${content.metaData.creationDate}
Metadata.modificationDate: ${content.metaData.modificationDate!" 
This node has never been modified."}
[#-- Paragraph definition --]
The current paragraph definition: ${def.name}
A paragraph definition property: ${def.style}
[#-- Context: ctx --]
A request parmeter: ${ctx.myParam}
The current user name ${ctx.user.name} 
The current locale ${ctx.locale}
[#-- MagnoliaTemplatingUtilities: mgnl --]
Create a link to a page: ${mgnl.createLink(content)}
Create a binary link: ${mgnl.createLink(content.image)}
Referenced page: ${mgnl.getContentByUUID(content.referencedPage) 
@handle}
[#-- Status based rendering --]
This is ${mgnl.authorInstance?string('indeed', 'not')} an author instance.
This is ${mgnl.editMode?string('indeed', 'not')} the edit mode.
This is ${mgnl.previewMode?string('indeed', 'not')} the preview mode.
[#-- The Model executed before the paragraph rendering: model --]
The parent model: {model.parent}
The result of the execute method: ${actionResult}
[#-- AggregationState: state --]
Entry point of the rendering: ${state.mainContent}
Current content node: ${state.currenContent}

Accessing your own Java methods from Freemarker

1. Write and compile your Java class as you normally would.
2. Copy the class file in WEB-INF/classes folder of your Magnolia web application.
3. In AdminCentral, go to Configuration > /server/rendering/freemarker/sharedVariables.
4. Under sharedVariables, create a content node myClass.
5. Under myClass, create a data node class and set its value to the class name of your class, previously placed in WEB-INF/classes.