OpenCms documentation
OpenCms documentation

Value wrappers

Writing a formatter means, for the most part, accessing content values, accessing properties, and accessing element settings. The values of element settings and properties are by default available as strings, whilst the values of content elements by default are available as content value access wrappers of type CmsJspContentValueAccessWrapper.

The content value access wrapper bean allows to transform properties, element settings, and content values into their specific internal Schema types, for example, into primitive types like booleans and numbers, or into complex types like org.opencms.jsp.util.CmsJspImageBean.

A 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 can make your code nicer in a next step, 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 an 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 a width of 400 pixels.

With value wrappers, we can get the information typed. 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, value wrappers are used:

  1. access the element setting via cms.element.setting (setting without 's' in the end in comparison to the first formatter) and make it a boolean value by means of toBoolean expression.
  2. 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 delivered to the browser.

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, or to check if the resource is an image, and so on.