The OpenCms taglib (<cms:>)

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

OpenCms ships with its own taglib. It allows to easily invoke OpenCms functionality from JSPs. Whenever you write a formatter or create a list of contents, you will use tags from the OpenCms taglib. But it provides a lot more. Here's how to use the taglib and a brief overview on the available tags.

Related links

How to insert the "taglib" directive?

To use the OpenCms taglib, you must insert the taglib directive in your JSP page to specify where the OpenCms taglib definition can be found. This can be done in two different ways:

  1. With the standard JSP-/Servlet-technology:
<%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms" %>

This directive must be set before any cms tags are used. If used as shown in the example, the prefix cms is unique for the OpenCms taglib. In our examples, all tags of the OpenCms taglib start with the prefix cms:.

  1. With OpenCms specific short form:
<%@page buffer="none" session="false" taglibs="c,cms" %>
Note: If you use the short version to add taglibs, you will not get autocompletion when editing the JSP in your preferred IDE.

Tags exposed by the OpenCms taglib

The following list of <cms:>-tags is available in the OpenCms standard taglib. A tag can be executed by calling:

<cms:tagName attributes...></cms:tagName>
Tags exposed by the OpenCms taglib
cms:bundle

Loads a resource bundle to be used by its tag body. The tag is similar to <fmt:bundle>, but able to handle OpenCms XML-bundles.
cms:container

Enables the template mechanism for container pages.
cms:contentaccess

Provides access to the content for the JSP EL.
cms:contentcheck

Provides conditional logic for checking the element of a XML content.
cms:contentinfo

Provides access to the result set of a contentload.
cms:contentload

Loads XML content items from the OpenCms VFS.
cms:contentloop

Allows looping through XML content node element values.
cms:contentshow

Provides access to individual XML content node element values.
cms:decorate

Provides decoration of HTML content.
cms:device

Provides different HTML output for various device types.
cms:editable

Enables direct editing within a template.
cms:elementsetting

Provides access to the settings of an ADE container element.
cms:enable-ade

Enables advanced direct editing within a template.
cms:export

Writes JSP code from a JSP to files in the static export.
cms:formatter

Loads single XML content items for ADE formatters.
cms:headincludes

Includes required CSS or Javascript resources, placed in html/head.
cms:img

Supports image scaling using the OpenCms native image scaling mechanism.
cms:include

Includes other JSP elements dynamically at runtime.
cms:info

Enables access to some system information like OpenCms version etc.
cms:jquery

Allows inclusion of jQuery, some jQuery plugins code and stylesheets.
cms:label

Reads localized values from resource bundles (Java property files like workplace.properties) that hold user messages.
cms:link

Builds a valid OpenCms URL for a given resource.
cms:navigation

Provides access to the navigation information.
cms:nocache

Sends no-cache headers to the browser.
cms:param

Adds a parameter to the outer tag (if supported).
cms:parse

Decorates HTML with custom A_CmsConfiguredHtmlParser implementations given in the parserClass attribute.
cms:pdf

This tag is used to generate a link to a PDF generated from XML content given the path of the XML content.
cms:pdfthumbnail

This tag is used to generate a link to a thumbnail for a PDF.
cms:property

Enables read access to the current VFS file's properties.
cms:resourceaccess

Provides access to the resources for the JSP EL.
cms:resourceload

Loads resources from the OpenCms VFS.
cms:secureparams

Enables automatic parameter escaping for the current flex request.
cms:template

Splits a JSP page into elements to be included by the <cms:include>-tag.
cms:user

Enables access to the properties of the currently logged in user.
cms:usertracking

Performs user tracking actions like visit resources or subscribe/unsubscribe.

EL functions exposed by the OpenCms taglib

The following list of EL-functions are available in the OpenCms standard taglib. An EL-function can be accessed by calling:

${cms:functionName(parameters)}
EL functions exposed by the OpenCms taglib
cms:convertDate

Allows conversion of Long values to Dates. Can also handle Strings that represent a Long or a Date.
cms:convertList

Returns a list of attribute values specified by the attribute name of the items of the given list.
cms:convertLocale

Allows conversion of Objects to Locales. Can also handle Strings that are locales, or Locales itself.
cms:convertUUID

Allows conversion of String values to CmsUUIDs. Can also handle byte[] that are CmsUUIDs, or CmsUUID itself.
cms:escape

Encodes a String in a way that is compatible with the JavaScript escape function.
cms:getCmsObject

Returns the current OpenCms user context from the page context.
cms:getListSize

Returns the size of the given list.
cms:getRequestLink

Returns the link without parameters from a String that is formatted for a GET request.
cms:getRequestParam

Returns the value of a parameter from a String that is formatted for a GET request.
cms:lookup

Uses the first String as key to look up from the map that is passed as the second String, and returns either the element found or the empty String. The map String must have the form key1:value1|key2:value2 etc.
cms:lookupDefault

Uses the first String as key to look up from the map that is passed as the second String, and returns either the element found or the default value from the third String. The map String must have the form key1:value1|key2:value2 etc.
cms:navUri

Returns the current navigation URI.
cms:stripHtml

Strips all HTML markup from the given input.
cms:trimToSize

Returns a substring of the input, which isn’t longer than the given int value.
cms:unescape

Decodes a String in a way that is compatible with the JavaScript unescape function.
cms:vfs

Provides simple access to a OpenCms JSP/EL content VFS access bean.

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.

To the wiki