Search the documentation
 Show GitHub edit links  Hide GitHub edit links
Documented since: 9.5.2 Latest revision for: 9.5.2 Valid for OpenCms: 10.5.2

OpenCms comes with several Java beans to provide access to OpenCms-specific functionality in JSPs. In general, if required, an object of each bean could be made available separately in a JSP. Also several tags of the <cms:>-taglib initialize and expose objects of such beans.

Since OpenCms 9.0.1 the variable cms is present in the page scope for each JSP. It makes an object of type org.opencms.jsp.util.CmsJspStandardContextBean available. The object provides a convenient way to access the most important OpenCms functions via JSTL/EL. Thus, in most cases no bean at all has to be included and initialized manually, and also formerly required use of scriptlet code becomes obsolete.

The standard context bean has a very rich interface. In particular, access to several other Java beans shipped with OpenCms is granted. A complete overview of the functionality exposed via the standard context bean can be looked up in the JavaDoc. Look up the documentation of the class CmsJspStandardContextBean. Starting there, you can easily explore the interfaces of all other beans accessible via the standard context bean as well. If you are aware of the naming conventions for Java Beans, you can obtain an overview of the properties available in EL.

Another starting point to get an overview is this documentation page, only listing interesting beans and how to obtain an object of that bean.

Here, we describe only the most important Java beans shipped with OpenCms. We do not aim for completeness when describing the properties of the beans. We also do not cover all beans. In particular, we exclude beans for content access, since they are handled when formatters are explained.

The standard context bean

Provider and availability

Provider class

org.opencms.jsp.util.CmsJspStandardContextBean

Access via

cms

Availability

In each JSP, initialized according to the current request.

Useful properties in a template

List of properties useful in a template
title

Get the title property of the currently requested page. Note, that the property has a special behavior for detail pages: Instead of using the title property of the displayed page, the title property of the resource providing the detail content is chosen.

isOnlineProject

Returns true if the request is performed in the “online” project. Otherwise returns false.

isEditMode

Returns true if edit mode is enabled. Otherwise returns false.

We exemplify the use of the properties in a template. The tasks are as follows:

  • Insert minimized javascript sources only in the online project, for debug reasons use the standard version otherwise
  • Set the page title of the web page according to the requested resource.
  • Place a special placeholder on top of the page if (and only if) in edit mode

The following code snippet fulfills the three tasks:

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core"%>
<html>
 <head>
  <title><c:out value="${cms.title}"/></title>
  <meta charset="${cms.requestContext.encoding}">
  <!-- meta info etc. -->
  <cms:enable-ade/>
  <c:choice>
   <c:when test="${cms.isOnlineProject}">
    <cms:headincludes type="javascript" 
                      defaults="%(link.weak:/.../jquery-1.10.2.min.js)" />
   </c:when>
   <c:otherwise>
    <cms:headincludes type="javascript" 
                      defaults="%(link.weak:/.../jquery-1.10.2.js)" />
   </c:otherwise>
  </c:choice>
 </head>
 <body>
  <c:if test="${cms.isEditMode}">
   <!--=== Placeholder for OpenCms toolbar ===-->
   <div style="background: lightgray; height: 35px">&nbsp;</div>
  </c:if>
  <!-- Further code for creating the template -->
 </body>
</html>

Useful properties for localization

OpenCms supports a multi-language design for web pages. Thus, functionality and especially text output might be language specific. Which language to choose should be selected via a locale parameter. The standard context bean provides two choices for such locales:

List of useful properties for localization
locale

Returns the locale that is specific for the request context. The same locale is returned by cms.requestContext.locale.

workplaceLocale

Returns the locale configured in the workplace of the current user.

Here is a toy example:

<p>The locale of the request specific locale is "${cms.locale}".</p>

<p>The locale of your workplace is "${cms.workplaceLocale}".</p>

<p>To change the request specific locale, add the parameter "__locale=de" to the url.</p>

<p>The workplace locale is set via the preferences in your OpenCms workplace.</p>

Useful properties for formatting elements

It is sometimes useful to adjust formatters or function providers depending on the context. The standard context bean provides the following useful properties:

List of useful properties for formatting elements
edited

Returns true if the element was re-rendered without reloading the whole page, e.g., after editing the element’s content or moving the element on the page. This state might lead to limited functionality of javascript. Therefore, you might display just a “please reload” message.

enableReload

Placing ${cms.enableReload} somewhere in your formatter will result in an automatically page reload when content is edited (or moved to a different container).

element

Returns the currently rendered element.
Return type: org.opencms.xml.containerpage.CmsContainerElementBean

container

Returns the container the currently rendered element is part of.
Return type: org.opencms.xml.containerpage.CmsContainerBean

detailContent

Returns the current detail content, or null if no detail content is requested.
Return type: org.opencms.file.CmsResource (see here)

detailPageAvailable

Returns true if a detail page is available for the current element.

detailRequest

Returns true if this is a request to a detail page.

Useful properties to access further interesting Java beans

Via the following properties, you obtain objects of the given beans, that are initialized according to the current request.

List of useful properties to access further interesting Java beans
requestContext

Access to the request context bean org.opencms.file.CmsRequestContext.

vfs

Access to the VFS access bean org.opencms.jsp.util.CmsJspVfsAccessBean.

Note that here more properties that return objects of further Java beans are explained. In contrast to the properties listed above, these properties only make sense when formatting elements in container pages.

The request context bean

In OpenCms there is much more request specific information than in a usual stand-alone JSP. The request context bean provide access to such information. Do not confuse an object of such a bean with the implicitly present object requestScope that does not provide OpenCms specific information.

Provider and availability

Provider class

org.opencms.file.CmsRequestContext

Access via

cms.requestContext

Availabiliity

In each JSP, initialized according to the current request.

Useful properties of general interest

List of properties of general interest
uri

Returns the OpenCms VFS URI of the requested resource.

Useful properties in a template

List of properties useful in a template
encoding

Returns the current content encoding to be used in HTTP response.

The encoding property should be used to define the charset as follows:

<meta charset="${cms.requestContext.encoding}">

Useful properties to access further interesting Java beans

List of properties to access further interesting Java beans
currentUser

Access to the user bean org.opencms.file.CmsUser.

currentProject

Access to the project bean org.opencms.file.CmsProject.

The VFS access bean

The VFS access bean provides access to all resources in the OpenCms virtual file system. The bean is used to check if files exist, to read and set properties and permissions, to read XML documents, etc. In summary, you can access every resource in the VFS, read its metadata or access content. To enable such functionality, most properties of the bean return a lazy map that requires the URI of a resource as key to extract a value. If the current user has no access to the resource, or the resource does not exist, the return value will be empty.

When object.property returns a map, use object.property[key] to ask for the value of key key.

Provider and availability

Provider class

org.opencms.jsp.util.CmsJspVfsAccessBean

Access via

cms.vfs

Availability

In each JSP, initialized according to the current request.

Useful properties to explore resources in the VFS

List of useful properties to explore resources in the VFS
exists

Returns true if a resource, whose URI is given as key, exists.

existsXML

Returns true if a resource, whose URI is given as key, exists and is an XML content or XML page.

property

Given an URI as key, a lazy map with property names as keys and their values as values is returned.

propertySearch

Like property, but the returned map also contains inherited values for properties.

The following example shows how to read the “NavText” property of a file and how to access a value in an XML content item.

<%@page taglibs="c" %>

<c:set var="uri" value="${cms.requestContext.uri}" />

<p> The "NavText" property value of the current URI (file
    ${cms.vfs.resource[uri].name}) is 
    "${cms.vfs.property[uri]['NavText']}".
</p>
<p> The Text value of a selected Jumbotron XML content is
    "${cms.vfs.xml['/demo/.content/jumbotrons/jt_00001.xml'].value.Text}".
</p>

Useful properties to access further Java beans

List of useful properties to access further Java beans
permissions

Access to the permission set bean org.opencms.security.CmsPermissionSet.

resource

Access to the resource bean org.opencms.file.CmsResource.

xml

Access to the content access bean org.opencms.jsp.util.CmsJspContentAccessBean.

The user bean

The user bean provides an interface to access manifold user information.

Provider and availability

Provider class

org.opencms.file.CmsUser

Access via

cms.requestContext.currentUser

Availability

In each JSP, initialized according to the current request.

Useful properties

List of useful properties
guestUser

Returns true if the user is not logged in.

fullName

Returns “firstname lastname (username)”.

firstname

Returns the firstname of the user.

lastname

Returns the lastname of the user.

email

Returns the email of the user.

address

Returns the address of the user.

institution

Returns the institution information of the user.

In the following example JSP we check if a user is logged on. If so, we greet them by name.

<%@page taglibs="c" %>

<c:set var="user" value="${cms.requestContext.currentUser}" />

<c:choose>
  <c:when test="${user.guestUser}">
  	You are not logged in.
  </c:when>
  <c:otherwise>Hi ${user.fullName}!</c:otherwise>
</c:choose>

The project bean

The project bean provides access to project information. In OpenCms files can belong to different projects. There is just one “online” project, but several different projects that contain “offline” resources are possible. One such project, the “offline” project, is predefined.

Provider and availability

Provider class

org.opencms.file.CmsProject

Access via

cms.requestContext.currentProject

Availability

In each JSP, initialized according to the current request.

Useful properties

List of useful properties
name

Returns the name of the project.

description

Returns the description of the project.

dateCreated

Returns the creation date of the project.

uuid

Returns the id of the project.

In the following example JSP, we output when the current project’s name and creation date.

<%@page taglibs="c" %>

<c:set var="project" value="${cms.requestContext.currentProject}" />

<p> 
Your are in the project "${project.name}" that was created on
${cms:convertDate(project.dateCreated)}.
</p>

The resource bean

Each entry in the OpenCms VFS can be considered as a resource. The resource bean allows accessing metadata of such resources, such as properties, attributes, version, name, etc.

Provider and availability

Provider class

org.opencms.file.CmsResource

Access via

cms.vfs.resource[<URI>]

Availability

Whenever the requested URI exists and the current user has the necessary permissions.

Useful properties

List of useful properties
dateCreated

Returns the date of the creation of this resource.

dateReleased

Returns the release date of this resource.

dateExpired

Returns the expiration date of this resource.

dateLastModified

Returns the date of the last modification of this resource.

dateContent

Returns the date of the last modification of the content of this resource.

name

Returns the file name of this resource without parent folders, for example “index.html”.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.