Developing A Magnolia CMS Page With Freemarker
This document covers the development of web pages in the Magnolia Content Management System using the Freemarker template engine.
Overview
Three basic elements are required when developing a web application on the Magnolia CMS platform that requires dynamic content. These elements are the following: Template Template Definition Bean Backer Web Page The following sections of this document cover each of these items.
Components
This section of the document will provide a brief set of instructions for each component of the UI.
Templates
The Freemarker templates are used to provide a framework for the user interface. They are a mixture of HTML and Freemarker specific tags used to map data from the content management system to the UI. A simple Freemarker example is shown below:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>Sample Template 1</title> </head> <body> <div> <h1>Sample Page 1</h1> <div id="contact" class="contactFormStyle"> <label>Search</label> <div id="searchArea"> <input type="text" id="clause" name="clause" /> <input type="submit" value="Search" /> </div> </div> <p>The book is ${model.title} and the author is ${model.author}.</p> </div> </body> </html>
The example above looks like basic HTML with the exception of the two tags in brackets ${model.title} and ${model.author}.
Templates
The user interface is built using a Freemarker template. This template provides the basic framework upon which data will be presented to the end user of the site. Freemarker tags are used to present dynamic content1.
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>Sample Template 2</title> </head> <body> <div> <h1>Sample Page 2</h1> <div id="contact" class="contactFormStyle"> <label>Search</label> <div id="searchArea"> <input type="text" id="clause" name="clause" /> <input type="submit" value="Search" /> </div> </div> <p>The book is ${model.title} and the author is ${model.author}.</p> </div> </body> </html>
Add the new freemarker template to the Magnolia CMS. 1. Log into the Magnolia CMS instance. 2. Navigate to the Templating Kit or Better Templating module in the left pane. 3. Expand the left menu item and select Templates.
4. Expand the templating-kit or jsp-templating tree in the main pane, depending on where the template is desired. 5. Right-click or control-click a directory to get the contextual menu and select new template. A new template will be created called untitled
Refer to the Freemarker site at www.freemarker.org for details on developing templates with Freemarker.
1
6. Change the name of the template from untitled to a desired name.
Template Definitions
The template definitions are used to bring all of the UI components together, so that they can be used by the web pages generated by the CMS. 1. Navigate to the Templating Kit or Better Templating module in the left pane. 2. Expand the left menu item and select Template Definitions.
3. In the main pane of the Magnolia CMS, expand the ucp node to see the template definitions. The screen is shown in the example below:
4. Select the desired node and expand it or create a new node. Expand the htmlPage node. The components of the template definition should now be visible:
5. There are seven common components that are used in most template definitions. a. description this is used to provide a brief description of the purpose of the template b. modelClass this is used to provide the full qualified path to the java class that backs the template c. templatePath this is the path in the MagnoliaCMS to the source code of the template that is defined d. type this is the sort of template that is being used. For our purposes this value will always be freemarker. e. visible this is set to either true or false and determines whether a template is visible when defining a web page. f. i18nBasename use the default ucp.books.messages for all templates 6. NOTE: If it is necessary to change a template and it does not seem to be available, check the visible property of the template definition. If this property is set to false, it will not be available. Reset this property to true
and use the template just like any other template. Once the template has been set for the web page, the visible property can be reset to false so it is no longer visible as an option.
Bean Backer (model class)
The Bean Backers are classes that are used as the model for the freemarker templates. They are associated with a template in the Template Definitions in the Better Templating module. A bean backer must extend the RenderingModelImpl class or one of its sub-classes or must implement the RenderingModel interface. An example of a bean backer class is shown below.
package com.jaydot2.magnolia.beanbacker; import import import import info.magnolia.cms.core.Content; info.magnolia.module.templating.RenderableDefinition; info.magnolia.module.templating.RenderingModel; info.magnolia.module.templating.RenderingModelImpl;
import com.jaydot2.magnolia.model.Distribution; import java.util.Collection; import java.util.ArrayList; import java.util.logging.Logger; /** * @author James R. Bray, Jr. * */ public class SampleBeanBacker extends RenderingModelImpl { protected static final Logger logger = Logger.getLogger("com.jaydot2.magnolia.beanbacker"); @SuppressWarnings({"unchecked"}) public SampleBeanBacker(final Content content, final RenderableDefinition definition, final RenderingModel parent) { super(content, definition, parent); } public String getTitle() { return "Moby Dick"; } public String getAuthor() { return "Herman Melville"; } public Collection<Distribution> getDistributions() { return generateDist(); } protected String getString(final String text) {
return ( ( text == null ) || text.isEmpty() ) ? null : text; } private Collection<Distribution> generateDist() { Collection<Distribution> distributions = new ArrayList<Distribution>(); Distribution Distribution Distribution Distribution Distribution dist1 dist2 dist3 dist4 dist5 = = = = = new new new new new Distribution("New York"); Distribution("Chicago"); Distribution("Los Angeles"); Distribution("Miami"); Distribution("Atlanta");
distributions.add(dist1); distributions.add(dist2); distributions.add(dist3); distributions.add(dist4); distributions.add(dist5); return distributions; } }
Complex Page
Here we present a more complex sample template that presents a collection is a list.
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>${content.title}</title> </head> <body> <div> <h1>Sample Search Page</h1> <div id="contact" class="contactFormStyle"> <label>Search</label> <div id="searchArea"> <input type="text" id="clause" name="clause" /> <input type="submit" value="Search" /> </div> </div> <p>The book is ${model.title} and the author is ${model.author}.</p> [#list model.distributions as distribution] <p>City: ${distribution.location} </p> [/#list] </div> </body> </html>
Deployment References
FreeMarker
http://www.freemarker.org JCR 170 http://www.jcp.org/en/jsr/detail?id=170 JCR 283 http://www.jcp.org/en/jsr/detail?id=283
