Using formatters in OpenCms
Contents |
Abstract
This document explains the concept of formatters used in OpenCms since Version 8.0.0. This concept replaces the <cms:contenload> and <cms:contentacces> tags used in older OpenCms versions. It is not backwards compatible.
Template
A page layout is defined in the template JSP. A page can have multiple containers where XML content of different resource types can be moved to by Drag & Drop in the ADE. Containers can be defined by using the <cms:container> tag in your template JSP.
<html> <head> ... <cms:enable-ade /> </head> <body> ... <cms:container name="LEFTCOLUMN" type="sidecolumn" width="200" /> <cms:container name="CENTERCOLUMN" type="center" width="500" /> <cms:container name="RIGHTCOLUMN" type="sidecolumn" width="200" /> ... </body> </html>
Formatter configuration
Formatters are defined in the XML Schema Definition of the container page resource type. Formatters get defined in the <formatters> node within the <xsd:appinfo> node of the XSD of the content. A formatter names the JSP that should be used to render the XML content.
<xsd:annotation> <xsd:appinfo> ... <formatters> <formatter minWidth="400" maxWidth="700" uri="path to formatter JSP" /> ... </formatters> </xsd:appinfo> </xsd:annotation>
The same XML Content can be rendered by different formatter JSPs. Which formatter JSP is used for which container can be configured in the resource type schema. The formatter is chosen by the given container width or container type.
<xsd:annotation> <xsd:appinfo> ... <formatters> <formatter minWidth="100" uri="path to formatter JSP" /> <formatter minWidth="400" maxWidth="700" uri="path to formatter JSP" /> ... </formatters> </xsd:appinfo> </xsd:annotation>
<xsd:annotation> <xsd:appinfo> ... <formatters> <formatter type="center" uri="path to formatter JSP" /> <formatter type="sidecolumn" uri="path to formatter JSP" /> ... </formatters> </xsd:appinfo> </xsd:annotation>
The defined formatter has to match the attributes of the used template:
- If "width" is used for defining the formatter in your XSD, the container in the template has to have an attribute "width".
- Using "type" in your XSD formatter definition assumes that the template containers has an attribute "type".
The <cms:formatter> tag
In the JSP that should render the XML content the <cms:formatter> tag is to be used.
<cms:formatter var="content" val="value"> ... </cms:formatter>
Within the <cms:formatter> tag the XML content can be accessed with EL
<cms:formatter var="content" val="value">
<div class="article">
<h1>${content.value.Title}</h1>
<p>${content.value.Text}</p>
</div>
</cms:formatter>
JSP Standard Context Bean
The Expression Language makes it possible to easily access application data stored in JavaBeans components.
Taglib declaration
Make sure to declare the all used taglibs at the first lines of the JSP
<%@page session="false" taglibs="c,cms" %>
EL access to Bean methods
Within the <cms:formatter> tag the JSP Standard Context Bean can be accessed with EL. This Bean provides several useful methods like:
- getContainer()
- getPage()
- getElement()
- getRequestContext()
In EL this turns to
- ${cms.container}
- ${cms.page}
- ${cms.element}
- ${cms.requestContext}
Combined example
<%@page session="false" taglibs="c,cms" %>
<cms:formatter var="content" val="value">
<div class="article">
<h1>${value.title}</h1>
${cms.requestContext.uri}
${cms.requestContext.currentUser.name}
${cms.element.sitePath}
${cms.container.width}
</div>
</cms:formatter>
