OpenCms JSP standard taglib


Standard Syntax:
     <%@ taglib prefix="cms" uri="http://www.opencms.org/taglib/cms" %>

XML Syntax:
     <anyxmlelement xmlns:cms="http://www.opencms.org/taglib/cms" />

The OpenCms / JSP integration tag library

Used by OpenCms, the Open Source Content Management System.

(c) Alkacon Software GmbH & Co. KG
For more details about OpenCms, please see http://www.opencms.org/.
For more details about Alkacon Software GmbH, please see http://www.alkacon.com/.

Tag Library Information
Display NameOpenCms JSP standard taglib
Version1.0
Short Namecms
URIhttp://www.opencms.org/taglib/cms
 

Tag Summary
bundle

Loads a resource bundle to be used by its tag body.

Replaces the <fmt:bundle basename=""> tag which is not capable of using OpenCms resource bundles.

You can use <fmt:message key=""> tags inside the body of the <cms:bundle basename=""> tag as usual.

propertyThis tag enables read access to a file's OpenCms properties.
userThis tag enables access to the properties of the currently logged in user.
infoThis tag enables access to some system information like OpenCms version etc.
linkThe tag adjusts the links to the OpenCms VFS provided in the tag's body (including request parameters). Links MUST be adjusted to work correctly, because resources might be statically exported and also absolute pathes to resources that are not exported must be extended by the prefix "/{webapp name}/opencms".

Example: <cms:link>/vfslink/to/my/index.html</cms:link>

Note that the tag is necessary for all links given as arguments to "normal" HTML tags. For OpenCms specific tags, links are sometimes adjusted anyway and thus the tag must not be used.
pdfThis tag can be used for PDF generation. The primary use case is the PDF output of a specific content. It expands to a link for a PDF which is generated on the fly when the link is requested. The PDF is generated from an XHTML document via the Java library "Flying Saucer".
pdfthumbnailThis tag is used to generate a png or jpg thumbnail from a PDF and expands to a link to the thumbnail. The thumbnail is created when the link is requested for the first time.
ugcInitializes a user generated content form session.
decorateThis tag is used to decorate HTML.

The code in the body of the tag is decorated according to the given configuration file and locale.

A template for the config file is found at /system/shared/decoration/configuration.xml.

Look up the documentation for more information.
parseThis tag is used to postprocess HTML via custom HtmlParser extending org.opencms.jsp.parse.A_CmsConfiguredHtmlParser.

The "output" HTML of the JSP code in the tag's body becomes processed by the configured parser.
templateThis tag allows to split JSPs in several elements and use <cms:include> to include special elements.

Note that from the included JSPs, code not in the body of any <cms:element> tag will always be included.
contentloadThis tag loads XML content items from the OpenCms VFS. It is in particular useful to iterate over a list of collected content. For each content the code in the body is executed once.

Use <cms:contentaccess> to access loaded contents.
contentshowDeprecated.

This tag provides access to individual XML content node element values.
contentinfoThis tag provides access to information about the XML contents collected via <cms:contentload>. It has to be used in the body of <cms:contentload>.

Typically, the tag is employed to build up a page navigation or, when using the surrounding <cms:contentload> with the attribute preload="true", to get information about the number of contents collected.
contentaccessThis tag provides access to an XML content.

It has to be used in the body of <cms:contentload>.
contentloopDeprecated.

This tag allows looping through XML content node element values.
contentcheckDeprecated. Use properties of org.opencms.jsp.util.CmsJspContentAccessBean via the EL instead.

This tag provides conditional logic for checking the element of a XML content. The body of the tag is only processed if the conditions specified by the attributes and their values all evaluate to true.

The tag has to be used in the body of <cms:contentload>.
resourceloadThis tag loads resources from the OpenCms VFS. It is used similar to <cms:contentload>, but loads all kind of OpenCms resources.

Use <cms:resourceaccess> to access loaded resources.
resourceaccessThis tag provides access OpenCms resources. It has to be used in the body of <cms:resourceload>.
usertrackingMulti-purpose tag for tracking resource visits and subscription management.
labelThis tag is used to read values from the OpenCms workplace message bundles.

Place the key in the tag's body and the value for the locale of the current request context is returned.
includeThis tag is used for including OpenCms subelements in a page. It is similar to the "include" JSP directive. But, in contrast, it loads the input at runtime, not at compile time.

In the body of the tag, the <cms:param> tag can be used to pass parameters to the included file.

You could also specify the file to include in the tag's body.

Note that all Uris should be given as absolute or relative pathes without web application or servlet path, nor wrapped by a <cms:link>.
editThe tag can be used to place edit buttons around arbitrary HTML fragment. It allows to edit, add or delete XML contents. Typically it is used in the contexts of lists, e.g., news lists, where each list entry should be editable.
editable

This tag is used to enable the direct edit functionality.

It is placed in the header of a none-container-page template for most use cases.

An exeception is the use with attribute editEmpty, which is the last none-deprecated use case.

Note that most of the functionality is now done by <enable-ade> for container page templates.
deviceThis tag is used to output different HTML for various device types.

The body of the tag is only included if the device where the output is rendered matches a device listed via the type attribute.

Hint: You might want to use a template context provider instead of the tag to adjust your web site to multiple devices.

enable-adeThis tag is used to enable the advanced direct editing within a template.

Just place <cms:enable-ade /> in the head section of your template.
paramAdds a parameter to the outer tag (if supported).
imgThis tag allows using the OpenCms native image scaling mechanism. It generates the HTML required to include the selected image, adding the required image scaling parameters.

The following image formats are supported: BMP, GIF, JPEG, PNG, PNM, TIFF. Note: Picture scaling is by default only enabled for target size with width and height <=1500. The size can be changed in the image scaler configuration in the file opencms-vfs.xml in the body of the tag <loader>. Also other options for the image scaler are set there.
scaleImageThis tag allows flexible creation of scaled images using the OpenCms native image scaling mechanism. It generates a ScaledImage bean that can render scaled versions of the selected image, adding the required image scaling parameters.

The following image formats are supported: BMP, GIF, JPEG, PNG, PNM, TIFF. Note: Picture scaling is by default only enabled for target size with width and height <=1500. The size can be changed in the image scaler configuration in the file opencms-vfs.xml in the body of the tag <loader>. Also other options for the image scaler are set there.

This tag is an alternative to the cms:img tag, providing more flexibility by not generating any output but providing a bean that may be used to generate any output needed. This way you can use scaled images for
  • The standard img-Tag
  • The more modern picture-Tag with multiple sources for responsive design
  • Background-Image integration
exportThis tag can be used to write JSP code from a JSP to files in the static export.

Code in the tag's body is not processed by OpenCms.
jqueryThis tag allows to include jquery and some jquery plugins code and style sheets that are shipped with OpenCms.
The tag will include the unpacked version of JQuery in the offline project (for better debug facilities) and the packed version in the online project (for better performance).

Use the tag in the HTML head section of your template.
containerThis tag enables the template mechanism for container pages.
display

Via this tag, you can render an XML content with a given formatter from inside a (formatter) JSP.

In particular, the tag is useful for rendering list items from within a list formatter. The tag can be configured to work for contents of different type - thus it also for lists of mixed resources.

Optionally, you can display edit points at the output. They facilitate similar editing functionality as <cms:edit>.

In the body of the <cms:display> two other tags can be used

  • <cms:displayFormatter>

    Via this tag you can specify which formatters are used for which content types by the <cms:display>-tag. The choice can also be performed via the displayFormatters attribute (see the attribute's description below).

    If nothing is specified, the formatter with the highest rank, from within the formatters that have "Use as display formatter" enabled, is chosen.

  • <cms:param>

    This tag, contrary to it's default purpose, is used to pass element settings.

    To pass a setting, write:

    <cms:param name="settingName">settingValue</cms:param>

    The setting values specified here, overwrite the values that are possibly passed from the settings of the surrounding formatter (see the attribute passSettings.
displayFormatter

This tag can be used only inside <cms:display>. It specifies which formatter should be used to format a content of a special resource type.

Note that alternatively, the attribute displayFormatters of the tag <cms:display> can be used to specify these formatters.

formatterThis tag loads single XML content items.
nocacheThis tag sends no-cache headers to the browser.
headincludesThis tag enables content-dependent dynamic inclusion of css/javascript resources on a containerpage.

It should be placed in the HTML head-section of a container page template.

If dynamic inclusion is enabled, resources required by a special formatter that are configured in its formatter_config, are included on demand.
navigationThis tag provides access to a list of elements that should be shown in the navigation, i.e., elements where at least one of the properties NavText or NavPos are set. The tag is the standard tool to build up dynamic page navigations.
elementsettingProvides access to the settings of an ADE container element.

The tag is replaced with the value of the requested setting.

Useful, e.g., to adjust formatters to element settings.
search

This tag provides support to generate search forms and result lists for a server-side handled Solr search. It takes an (XML or JSON) configuration file or a JSON configuration String and essentially exposes an object with the search results and also the necessary information to suitably build up your search form. It supports facets and highlighting.

If you do not specify a search index explicitly, the tag uses "Solr Offline" and "Solr Online", depending on the current project.

To get detailed information on the configuraiton options, just have a look at an XML content of type jsp-search-form or look up the JavaDoc of the JSON configuration parser org.opencms.jsp.search.config.parser.CmsJSONSearchConfigurationParser.

secureparamsEnables automatic parameter escaping for a Flex Request.
jsonpartConverts the output of the contained JSP code to an encoded JSON form, to be used in combination with the servlet filter org.opencms.jsp.jsonpart.CmsJsonPartFilter.
 

Function Summary
voidaddToList( java.util.List, java.lang.Object)

Extends the given list by adding the provided object.

The 1st parameter is the list, the 2nd the value to add.

org.opencms.jsp.util.CmsJspVfsAccessBeanvfs( java.lang.Object)

Provides simple access to a org.opencms.jsp.util.CmsJspVfsAccessBean.

The argument object must in some way be suitable to extract a suitable instance of the org.opencms.file.CmsObject.

Hint: Easy access to the vfs access bean on a JSP is also provided via ${cms.vfs}.

java.util.DateconvertDate( java.lang.Object)

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

Example:

<fmt:formatDate value="${cms:convertDate(value.Date)}" dateStyle="SHORT" timeStyle="SHORT" type="both" />
java.util.ListconvertList( java.util.List, java.lang.String)Takes a list of Java beans as first argument and a property name for a property of these beans as second argument. The function returns a list where for each given bean the specified property is returned, i.e., for each bean, bean.property is returned.
org.opencms.file.CmsObjectgetCmsObject( java.lang.Object)Returns the current OpenCms user context from the page context when pageContext is given as argument.
java.lang.IntegergetListSize( java.util.Collection)Returns the size of the given list.
java.lang.StringgetModuleParam( java.lang.String, java.lang.String)Returns a parameter value from the module parameters.
java.util.LocaleconvertLocale( java.lang.Object)Allows conversion of Objects to Locales. Can also handle Strings that are locales, or Locales itself. If no valid locale is provided, the OpenCms default locale is returned.
java.lang.StringstripHtml( java.lang.Object)Strips all HTML markup from the given input.
java.lang.StringtrimToSize( java.lang.String, int)Returns a prefix of the String argument, that is not longer then the given int value.
org.opencms.util.CmsUUIDconvertUUID( java.lang.Object)Allows conversion of String values to CmsUUIDs. Can also handle byte[] that are CmsUUIDs, or CmsUUID itself.
java.util.ListcreateList( )

Returns a newly created, empty List object.

There is no way to create an empty list using standard JSTL methods, hence this function.

java.lang.StringgetRequestParam( java.lang.String, java.lang.String)Given an URL as String, formatted for a GET request, as first argument and a request parameter name as second parameter, the value of this request parameter in the first argument is returned.
java.lang.StringgetRequestLink( java.lang.String)Returns the link, that is given as argument of type String and formatted for a GET request, without parameters.
java.lang.Stringescape( java.lang.String, java.lang.String)

Encodes a String in a way similar to the JavaScript "encodeURIcomponent" function.

In order to avoid encoding hell, it's better to just use ${cms:encode(String)} on a JSP to transfer data that will be decoded using "decodeURIcomponent".

JavaScript "decodeURIcomponent" can decode Strings that have been encoded using this method, provided "UTF-8" has been used as encoding.

The 1st parameter is the String to encode, the 2nd the encoding to be used, e.g. "UTF-8".

java.lang.Stringencode( java.lang.String)

Encodes a String in a way similar to the JavaScript "encodeURIcomponent" function, using "UTF-8" for character encoding.

JavaScript "decodeURIcomponent" can decode Strings that have been encoded using this method.

java.util.MapjsonToMap( java.lang.String)Converts a JSON string to a map with string keys/value pairs.
java.lang.Stringunescape( java.lang.String, java.lang.String)

Decodes a String in a way similar to the JavaScript "decodeURIcomponent" function.

In order to avoid encoding hell, it's better to just use ${cms:decode(String)} on a JSP to transfer data that has been encoded using "encodeURIcomponent".

This method can decode Strings that have been encoded in JavaScript with "encodeURIcomponent", provided "UTF-8" is used as encoding.

The 1st parameter is the String to decode, the 2nd the encoding the string was encoded with, e.g. "UTF-8".

java.lang.Stringdecode( java.lang.String)

Decodes a String in a way similar to the JavaScript "decodeURIcomponent" function, using "UTF-8" for character encoding.

This method can decode Strings that have been encoded in JavaScript with "encodeURIcomponent".

java.lang.StringnavUri( java.lang.Object)

Returns the current request URI.

DEPRECATED On a JSP, use ${cms.requestContext.uri}instead.

java.lang.StringlookupDefault( java.lang.String, java.lang.String, java.lang.String)

Uses the 1st String as key to look up from the map that is passed as the 2nd String, and returns either the element found or the default value from the 3rd String.

The map String must have the form key1:value1|key2:value2 etc.

java.lang.Stringlookup( java.lang.String, java.lang.String)

Uses the 1st String as key to look up from the map that is passed as the 2nd String, and returns either the element found or the empty String.

The map String must have the form key1:value1|key2:value2 etc.

java.lang.StringrepairHtml( java.lang.String)Repairs the given HTML input by adding potentially missing closing tags.
java.lang.StringisSubSitemap( org.opencms.file.CmsResource)Returns whether the given resource is a sub sitemap folder.
java.lang.StringaddLeadingAndTrailingSlash( java.lang.String)Adds leading and trailing slashes to a path, if the path does not already start or end with a slash.
java.lang.StringchangeFileNameSuffixToo( java.lang.String, java.lang.String)

Changes the given filenames suffix from the current suffix to the provided suffix.

The 1st parameter is the filename, the 2nd the new suffix.

booleancomparePaths( java.lang.String, java.lang.String)

Compares two paths, ignoring leading and trailing slashes.

Returns true if the paths are equal (ignoring leading and trailing slashes).

java.lang.StringescapeHtml( java.lang.String)Replaces line breaks to <br/> and HTML control characters like < > & " with their HTML entity representation.

java.lang.StringescapeJavaScript( java.lang.String)

Escapes a String so it may be used in JavaScript String definitions.

This method escapes line breaks (\r\n,\n) quotation marks (".') and slash as well as backspace characters (\,/).

java.lang.StringescapePattern( java.lang.String)

Escapes a String so it may be used as a Perl5 regular expression.

This method replaces the following characters in a String: {}[]()\$^.*+/

java.lang.StringextractHtmlBody( java.lang.String)

Extracts the content of a <body> tag in a HTML page.

This method should be pretty robust and work even if the input HTML does not contains a valid body tag.

java.lang.StringformatResourceName( java.lang.String, int)

Shortens a resource name or path so that it is not longer than the provided maximum length.

In order to reduce the length of the resource name, only complete folder names are removed and replaced with ... successively, starting with the second folder. The first folder is removed only in case the result still does not fit if all subfolders have been removed.

Example: formatResourceName("/myfolder/subfolder/index.html", 21) returns /myfolder/.../index.html.

java.lang.StringgetCommonPrefixPath( java.lang.String, java.lang.String)Returns the common parent path of two paths.
java.util.LocalegetLocaleForName( java.lang.String)

Returns a java.util.Locale calculated from the suffix of the given String, or null if no locale suffix is found.

The locale returned will include the optional country code if this was part of the suffix.

java.lang.StringgetLocaleSuffixForName( java.lang.String)

Returns the locale suffix from the given String, or null if no locale suffix is found.

Examples:

  • rabbit_en_EN.html -> Locale[en_EN]
  • rabbit_en_EN      -> Locale[en_EN]
  • rabbit_en.html    -> Locale[en]
  • rabbit_en         -> Locale[en]
  • rabbit_en.        -> Locale[en]
  • rabbit_enr        -> null
  • rabbit_en.tar.gz  -> null

java.util.ListgetPathComponents( java.lang.String)Splits a path into its non-empty path components. If the path is the root path, an empty list will be returned.
java.lang.StringgetRelativeSubPath( java.lang.String, java.lang.String)

Converts the given path to a path relative to a base folder, but only if it actually is a sub-path of the latter, otherwise null is returned.

The 1st parameter is the path, the 2nd paramerter is the base folder.

booleanisEmptyOrWhitespaceOnly( java.lang.String)Returns true if the provided String is either null or contains only white spaces.
booleanisPrefixPath( java.lang.String, java.lang.String)

Checks if the first path is a prefix of the second path..

This method is different compared to String#startsWith, because it considers /foo/bar to be a prefix path of /foo/bar/baz, but not of /foo/bar42.

booleanisValidJavaClassName( java.lang.String)Checks if the given class name is a valid Java class name.
booleanvalidateRegex( java.lang.String, java.lang.String)Validates a value (1st parameter) against a regular expression (2nd parameter).
 


Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-3 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.