Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
Magnolia Templating Samples module is a showcase of Magnolia templating features for developers. It contains customizable examples of dialogs, page and component templates, and servlets. The examples demonstrate how to write the same action in Freemarker and JSP and introduce the tag libraries.
Templating Samples is a community module. It is not typically installed. Go to Magnolia Store > Installed modules in AdminCentral to check. To install the module individually, see the general module installation instructions.
See the general.
Shortcuts to the module configuration are in the Samples > Configuration menu in AdminCentral.
The module demonstrates how to customize the following page elements and components:
There are a number of toolbars on each page:
The authoring system uses Dialogs for content contribution and editing. Component dialogs are accessed by clicking edit icon in the toolbars.
The sample dialog definitions are in
There are six sample dialogs:
mainPropertiesconfigures page specific properties such as meta data.
howToedits component title, text, image upload and date selection.
samplesTextDialogedits component title and text.
externalLinkDialogedits component external link title and target URL.
intermalLinkDialogedits component internal link title and target URL.
samplesFieldShowRoomdemonstrates a variety of (input fields).
Dialogs can be linked to page, area and component definitions and the same dialog can be used reused multiple times. For example the
mainProperties dialog is used by the
main page definition and the
searchResult component definition, and the
samplesTextDialog by the
text components definitions.
A properties dialog typically allows for page specific properties such as the title displayed in the browser window and navigation menu, and page meta data such as the page keywords and description. Open any page on demoauthor and click Properties in the top bar to see how the dialog is used in the Standard Templating Kit.
To open the dialog, click Properties in the top bar on any page based on the
main template, for example the
jsp-sample-site page. Change the title and note how the page title, browser window and tab title change dynamically. The title inserted in Website when the page is created is used as the default
title property and is rendered by the main page script.
howTo dialog is an example of a component dialog. It is referenced in the howTo component definition. The dialog allows the user to enter a title and text, upload an image and select a date from a calendar. The
HowTo component script renders the dialog content and some additional content.
To open the dialog, open the
jsp-howTo page, click the Main toolbar and then the Edit icon in the HowTo component toolbar.
howTo dialog configuration is in Configuration
/modules/samples/dialogs/howTo. The four fields use the , , and controls.
samplesTextDialog is a simple dialog that contains two fields,
text. The dialog configuration is in Configuration
/modules/samples/dialogs/samplesTextDialog. This configuration is identical to the
howTo dialog with the omission of the
date fields. The dialog is referenced the
text component definitions.
internalLinkDialog dialogs demonstrate how input is collected to render external and internal links. The former uses the control for the target URL and the latter the control that allows for the selection of an internal page.
The dialogs are configured in Configuration
samplesFieldShowRoom dialog demonstrates numerous input available in Magnolia. This dialog is referenced by the
The component is meant to showcase the dialog tabs and fields, and only renders static content when added to a page. To view the dialog:
maintemplate click the Main toolbar.
Each tab of the dialog shows the many controls available with varying options.
The dialog is configured in Configuration
/modules/samples/dialogs/samplesFieldShowRoom and shows sample configurations for most available fields.
The module includes a number of page, area and component templates written in FreeMarker and JSP. The template definitions are in Configuration
/components. Area template definitions are configured in the page template definition.
A template definition makes a template script available to the system by providing a name and.
A template script renders content. It can be written in FreeMarker, JSP or a custom templating language. The script instructs the where on the page to place content. It contains placeholders for content attributes such as headings and images.
Template definition properties vary from definition to definition, but all have the following required properties:
renderTypethat determines the
templateScriptthat defines the URI to the script. For each sample template definition scripts in FreeMarker and JSP are provided.
With the exception of these two properties, the Freemarker and JSP template definitions are identical. Magnolia ships with two renderers FreemarkerRenderer and JspRenderer .
All of the sample FreeMarker and JSP scripts functionally identical. Scripts can also be written in a custom templating language provided that you integrate a renderer for that language into Magnolia.
JSP scripts can only reside on the file system. They are extracted onto the file system during module installation or update. To test JSP template scripts and see your changes take effect:
/<CATALINA_HOME>/webapps/<contextPath>/templates/samplesfolder. This is typically at
FreeMarker scripts can be loaded from any of the options below and the system searches for them in this order:
templatesworkspace. The template needs to be enabled to be considered.
The easiest way to test FreeMarker scripts is to recreate them in the
samples. This starts a folder hierarchy that matches the template path in the module JAR.
The module includes two page templates.
mainrenders the FTL and JSP Sample Site pages and all sub pages except the Sample Product Selection pages.
mainVirtualURIdemonstrates the use of virtual URI mapping and renders the Sample Product Selection pages. When you select a product, the page is reloaded with your selection in the URL.
The template definitions are in Configuration
The templates are used on pages like this:
Go to Website in AdminCentral to see how the templates are assigned to pages.
main page template is a generic template sample that demonstrates multiple elements and functionality.
main page template definitions are in Configuration
/jsp. Like all the sample template definitions the FreeMarker and JSP samples differ only in the renderer set in the
renderType property and the template script referenced in the
main template definition:
classnode. A model class can be used to extend the default template definition by adding custom properties. A model class provides additional functionality and many templates do not use one.
titleSizeproperty that is allowed for by the model class. This property defines the size of the title on the page. The model class reads the
titleSizeproperty and makes it available to the template script. The script can then either render the property value on the page or use it in some custom presentation logic. See main page script below.
mainPropertiesdialog. Click on Properties in the top bar of any page to see the dialog.
parameters content node with custom properties under it can be added to the definition as an alternative to using a custom model class, or in addition to using one. Any properties under
parameters are available to the template script automatically.
Model is a Java program that holds your business logic. It can do any task required, such as execute a search or calculate an insurance policy. It holds the results of the logic execution and passes them to a renderer.
model class demonstrates how to extend the default template with custom properties. The Java logic makes the
titleSize property available to the template script.
No Java logic is needed to make properties under the
parameters content node available. This is default functionality for which you do not need a custom class.
cms.init tag initializes the tag libraries. Once initialized the toolbars on the author instance render automatically.
In JSP in addition to the
cms.init tag, the libraries need to be referenced specifically. Appropriate references should be added to all scripts.
main script is an inclusive script i.e. it includes all page areas using the
cms.area name tag. Each area definition references its own script.
titleSizeproperty is an example of extending the default template definition with a custom property that is allowed by the model class. It defines the size of the main heading on the page. The model class makes the property available to the script.
customPropertyproperty under the
parameterscontent node is an example of automatically extending the default template definition. These properties are available to the template script automatically.
To see how they work amend the
main script as shown in the code examples below:
titleSizeproperty in the template definition to see how page title size can be changed by configuration.
For custom properties under the
parameters content node of the definition JSP needs the containing
parameters node as part of the notation.
Here is the result with the
titleSize set to
Example mappings are configured in Configuration
class allows you to specify a pattern that matches a sequence of characters. The regular expression in
fromURI maps an incoming request to a page defined in
toURI. The user is forwarded to what appears to be sub page of
jsp-sample-site/jsp-products but in fact the same page is loaded. The action prefix
forward hides the true target and displays the
fromURI URL in the browser address bar.
virtualURI page script creates links to products.
ctx.contextPath gets the context path corresponding to the current request and
ctx.parameters.product renders the selection.
pageContext.request.contextPath gets the context path corresponding to the current request and
param.product renders the selection.
When a user clicks a link, the selected product is appended to the request URL.
products virtual URI mapping captures the product from the URL and passes it back to the page as context parameter. It is now available to the script through the
ctx templating support object in FreeMarker.
The user is forwarded back to the originating page. The
forward action prefix ensures the true target URL is not visible to the user. The script displays the context parameter ("You selected: product3") on the page.
Pages consist of areas which can consist of further areas or components. Areas structure the page and control what components are available in the area. The area toolbar shows the name of the area. Areas also have an end marker, a narrower green bar that displays at the bottom of the area. For more information see .
Area definitions are configured in the page template definition. In the
main page template the areas definitions are in Configuration
An area definition:
typenode. There are three options:
single: Area can only contain one component at a time but multiple components can be made available as options. Example:
list: Area can contain multiple components that render in a list. Examples:
noComponent: Area cannot contain any editable components. Used for system-generated automatic content such as breadcrumbs or static content that changes rarely and remains the same across the site such as branding. Example:
Components are made available in the
availableComponents node that defines which componets may be added in the area.
availableComponents is map of components built by reading the configuration into a Java Bean using the Content2Bean mechanism.
To make a component available in an area, add a content node into the map and reference the component definition. The
id property identifies the component definition. The first part before the colon (:) is the name of the module folder where the component definition resides. The second part is the relative path.
autoGeneration node in an area definition allows you to create content automatically. An autogenerated component is configured in the
extras area of the
main template. This configuration in discussed later in Link components. To view the component open the
jsp-sample-site page. It is the second component in
extras area titled An autogenerated LinkList.
Areas support inheritance which is configured in the
inheritance node. The
footer area is an example of inheritance. The components in the area cascade down to child pages automatically. Inheritable component are only editable on the source page. For more information see Inheritable components.
enabledproperty enables and disables inheritance for the area.
none: No components are inheritable. This has the same effect as disabling inheritance by setting the enabled property to false.
all: All components added in the area cascade down to child pages automatically.
filtered: Components in the area cascade only if a Show in subpage checkbox is configured and selected in the component dialog.
The page areas are rendered by four area scripts:
The areas are rendered with containing
div elements in the generated HTML so that you can control their layout on the page with CSS. A sample CSS file is included in the module and you can view it in the Git respository.
single script renders a single component and is suitable for most areas where the
type property is set to
single in the area definition. The
cms.component content tag renders the component content. Compare the code to that of the
list script below.
list script can be used for most areas where the
type property is set to
list in the area definition. The template loops through the components in the area, rendering the them one by one.
In FreeMarker the
#List directive lists the content map of components in the
In JSP the tag libraries are referenced specifically and
forEach items lists the content map of components in the
type property of the
footer area is
list but the area uses its own script that wraps the content in
<div id="footer"> and nests the components in
type property of the
navigation area is
noComponent and the content is rendered entirely by the
navigation script. The
include directive includes two further scipts,
searchForm that renders the search box and
macros/navigation that renders the horizontal navigation. The
cmsfn.root method assigns the
mgnl:page nodes as children. For more
cmsfn methods see
The navigation bar is rendered by the
macros/navigation script. The script uses three
Component is the smallest block of content that end users can edit, delete and move as a unit. The Templating Samples module provides seven sample components:
howTorenders a title, text, image and date.
textrenders a title and text.
linkListrenders a link list.
searchResultrenders search results.
externalLinkrenders an external link.
internalLinkrenders an internal link.
fieldsShowRoomdemonstrates various input controls.
The component definitions are in Configuration
As in the case of page and area definitions, a component definition makes the component available to the system and references the script that renders the component. Among others, the definition also typically references the
dialog used to edit the component and a model class for additional functionality, but these properties are not strictly necessary.
Here is the
howTo component on the
ftl-sample-site/ftl-howTo page. It is edited with the
Here's the component definition for
descriptiondisplays below the
titlein the selector dialog when the component is added on a page.
i18nBasenamefinds the translations for the
titleproperties. For more information see .
titledisplays in the selector dialog and in the component toolbar.
modelClassproperty references the SampleComponentModel . This model class does not add functionality to the this component directly, but can be extended to do so. It's relevance here is the search box that renders in the component that in turn relates to the
searchResultcomponent that is discussed later.
Here's the selector dialog in
main area on the
main template. Match the text in the dialog to that in the
The allows you to see the content as it is stored in the
website repository. You can access the browser at Tools > JCR Browser (Website). This is how the content of the
howTo component is stored. Note that the search box and 'HowTo' component link that render on the page are not stored here. This content is rendered entirely by the
howTo script renders the
howTo component. Below are examples from the script that show how to create common page content in a component script.
Plain text content entered in a dialog is rendered using the
content.<field name> notation. The component title text is stored in the
title property of the content node, as defined in the
howTo dialog definition.
In FreeMarker a tag to check if a content node is empty is not necessary. The
! (exclamation mark) operator provides a default value.
not empty evaluates the body only if a container exists or the corresponding item exists and is not empty.
text property of the content node contains HTML markup as editorial content is added using the FCKEditor (
expose useful methods. Here the
decode method is used to escape the HTML.
The image is rendered using the
cmsfn.link method. The script retrieves the image from the repository at
The date is stored in the repository in the
mm/dd/yy format. The following code renders and reformats the date as
EEEE, d. MMMM yyyy.
include directive includes the
includes/searchForm script that renders the search box. This script is used multiple times in the samples. It is also included in the navigation script and searchResult script.
The 'HowTo' component link opens the component script file. Click the link on the page in preview mode to view the script in the browser. The
is executed when the requested path contains the pattern
/.sources/*. For more see Servlets below. The script provides an example of creating links by appending a static path to the context path.
In FreeMarker you can get the current context path from the
ctx templating support object.
linkList component is an example of a component that contains nested components. It is also used to demonstrate the configuration of an autogenerated component. Note how efficiently elements can be used multiple times.
A number of link components are available on pages based on
linkListcomponents can be added in
linkListcomponent is rendered in
externalLinkcomponents can be made available in any area, if preferred.
Here's how the various definitions interrelate.
externalLink components are used in the samples as nested components in the
linkList component. The component definitions are in Configuration
jsp. Both components are rendered by the
link script. The
externalLink component does not require or use a model class and the
internalLink component uses the
class that resolves internal links by identifier or path.
linkList component defintion is in Configuration
jsp/linkList. Nested components are configured in the
areas/links/availableComponents node. Note that this node has an almost identical structure to the corresponding in the page template definitions. Here
<area name> is substituted with the
links node. This structure identifies that the nested components reside within a sub area (node type=
mgnl:area) and are rendered by the script using the
cms.area name="links" tag. See Link component scripts below.
linkList component is configured in the
main page template in Configuration
/jsp/main/areas/extras/autoGeneration. Here the links that are rendered on the page are defined in the definition:
autoGeneration/generatorClassnode allows for the nodes and properties within the configuration.
linkListcomponent in the
templateIDproperty that in turn references the
linkListscript that renders the main component.
titleproperties of the nested components.
templateIdproperty. These component definitions,
samples:components/ftl/externalLinkin turn reference the
linkscript that renders the links.
Here is the autogenerated component on the
ftl-sample-site/ftl-howTo page. The component is created atuomatically on all pages based on the
main page template.
Two relatively simple scripts combine to render the numerous link components.
externalLink components are rendered by the
makes the internal link properties available to the script and the
model.targetLink notation is used. The title of the target page renders as the link title unless another title is specified.
External links are rendered using the standard
content.<field name> notation.
linkList script renders the
linkList component. The links of the nested components are in a nested
<div class> and are rendered using the
cms.area name tag because the component definition is structured to identify their node as an area.
searchResult component renders the results of a search term entered in the search box. A page containing this type of component would normally be excluded from the navigation as it only renders meaningful content when a search is executed. For demonstration purposes the component is included on the
Here's the FreeMarker component after requesting the results for the term "ftl".
The component definitions are in Configuration
jsp/searchResult. The component uses the
searchResult script and
SampleComponentModel model class contains the Jave logic that renders the search results. The class gets and sets the query string and lists the search results using the following SQL query.
searchResult script renders the results from the attributes made available by the model. Note the use of the
cmsfn.page method made available by
and the use of the
ctx templating support object. Here's the part of the script that renders the results.
DisplaySamplesSourcesServlet is an example of a custom servlet. Its purpose is to display the source file of a template or component script.
The servlet is registered in the servlets filter chain at Samples > Servlets
/server/filters/servlets/DisplaySamplesSourcesServlets. It is executed when the requested path contains the pattern
/.sources/* pattern is present in the *Display Component's Sources * links that render in the
searchResults components. When you click these links the servlet loads the source of the
For more information see Filters.
The module installs a number of sample users, groups and roles to show how the bootstrap mechanism work. Bootstrapping is the process of pre-loading the system with content and configuration. This is useful when you want to load some data as a baseline for testing.
The Templating Samples module JAR has two bootstrap folders:
mgnl-bootstrapcontains files that are always bootstrapped. In the Templating Samples module dialog, template, virtualURIMapping, config definitions and the
baseuser role are loaded from here.
mgnl-bootstrap-samplescontains files that are bootstrapped only if property is set to
true. Web pages, users, groups and roles are loaded from here.
You can find the sample users, groups and roles in the Security menu in AdminCentral.
modules/samples/config there are a number of sample configurations. These are provided as examples and are not used by the module as such.