OpenCms Documentation

Value wrappers

 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 11.0.0 Valid for OpenCms: 11.0.0

Writing a formatter you access content values, properties and element settings. The values of element settings and properties are by default available as String, the values of content elements as CmsJspContentValueAccessWrapper. But you might know that you deal with a more specific kind of value, e.g., a link to a VFS resource, an image, a boolean value, ....

Since OpenCms 11, you can directly transform the properties, element settings and content values into the thing they really are. This is handled by so called value wrappers and the topic explains how to use them.

More over, for resources a specific wrapper is provided and returned by EL expressions. It let's you get the correct link, check the type of the resource, and many more things the plain resource object would not support.

The benefit of value wrappers by example

A very simple formatter that conditionally outputs an image might look as follows:

<%-- Import taglibs etc. --%>

<cms:formatter var="content">
<div>
  <%-- some HTML --%>

  <%-- conditionally output an image --%>
  <c:if test="${cms.element.settings.showImage eq 'true'}">
    <img src="<cms:link>${content.value.Image}</cms:link>" width="400" />
  </c:if>

  <%-- some more HTML --%>
</div>
</cms:formatter>

The interesting parts where value transformers make your code nicer are:

  1. the check if the element setting showImage is true (line 8),
  2. the part where the image link is rendered (line 9).

For the setting, that is probably visible as a check box in the settings dialog, it would be nice to access it as boolean value, since we know it is a boolean value. For the image, it would be nice to access it as image bean, since we know it is an image and we might want to scale it or add correct width and height attributes, or even produce a whole source set of images from the provided one. Our initial formatter will return the URL to the unscaled image and the browser will have to resize the image to width of 400 pixels.

With value wrappers, we can get the information typed as we like. Here's an adjusted version of the formatter using the wrappers:

<%-- Import taglibs etc. --%>

<cms:formatter var="content">
<div>
  <%-- some HTML --%>

  <%-- conditionally output an image --%>
  <c:if test="${cms.element.setting.showImage.toBoolean}">
    <img ${content.value.Image.toImage.scaleWidth[400].imgSrc} />
  </c:if>

  <%-- some more HTML --%>
</div>
</cms:formatter>

In the improved formatter, we use value wrappers:

  1. We access the element setting via cms.element.setting (setting without 's' in the end - in comparism to the first formatter) and make it a boolean value by toBoolean.
  2. We access the image as image bean by using content.value.Image.toImage and directly scale it and output the src, width and height attribute of the <img> tag by calling imgSrc. Hence, the correctly scaled image is served by the browser.

Overview on the available value wrappers

To get a complete overview on the transformation methods of value wrappers lookup the JavaDoc for

    • A_CmsJspValueWrapper - the base class of all wrappers except the CmsJspResourceWrapper.
    • CmsJspObjectValueWrapper - the wrapper returned by ${cms.wrap[{object to wrap}]}where {object to wrap} is the object you want to wrap, e.g., you could write ${cms.wrap[param.pagesize].toLong} to wrap the String value of the parameter pagesize and the convert it to a Long.
      The expression ${cms.wrap[{object to wrap}]} will always return a CmsJspObjectValueWrapper unless fed with an object that already has one of the other wrapper types (then it will return the object unchanged), or if it is of type CmsResource (then it will return an object of type CmsJspResourceWrapper.
    • CmsJspContentAccessValueWrapper - the wrapper for values of XML contents, e.g., by ${content.value.{my value}} in a formatter where {my value} is the name of the schema element you want to get the value from.
    • CmsJspElementSettingValueWrapper - the wrapper returned by ${cms.element.setting.{setting name} where {setting name} is the name of your specific setting.
    • CmsJspResourceWrapper - the wrapper for resources. It is a context-aware extension of CmsResource and provides additional methods, e.g., to get the site path or the link URL directly, check if the resource is an image ....

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.