Render Different Image Variants

Overview

This page describes how to render a different image variant from the one stored in rich text content. This approach allows you to select the most appropriate image variant at runtime, based on the context in which the content is displayed.

When to Use

Rendering different image variants is useful when you need to display the same document across multiple channels or devices, each requiring a different image size or resolution. Common scenarios include:

• Displaying a small image variant on mobile devices, a medium variant on tablets, and the original variant on desktop websites.
• Showing a smaller image when a left menu is present, and a wider image when it is not.
• Serving a low-resolution image when the request comes from a wireless device or under low bandwidth conditions.

Editors select a default image variant in the CMS. As a developer, you can override this selection at render time, choosing a variant that matches the current context.

Prerequisites

• You have defined an imageset with multiple variants.
• Your document contains a rich text field referencing images from this imageset.
• You are using either JSP or Freemarker templates for rendering.

Implementation

Assume you have the following imageset definition:

[hippogogreengallery:imageset] > hippogallery:imageset, hippogallery:relaxed
  orderable
  + hippogogreengallery:copyright (hippogogreen:copyright)

By default, the imageset includes these variants:

-hippogallery:thumbnail
-hippogogreengallery:mobilethumbnail
-hippogallery:original
-hippogogreengallery:largethumbnail
-hippogogreengallery:smallthumbnail

When rendering a HippoBean that contains a rich text field, you can specify which image variant to render, regardless of the variant stored in the HTML. Use the following examples to override the image variant in your template. In these examples, getHtml() returns a HippoHtml bean for the document.

Render a Specific Image Variant

To always render the mobilethumbnail variant, use the following:

JSP

<hst:html hippohtml="${requestScope.document.html}">
  <hst:imagevariant name="hippogogreengallery:mobilethumbnail"/>
</hst:html>
copy

Freemarker

<@hst.html hippohtml=document.html>
  <@hst.imagevariant name="hippogogreengallery:mobilethumbnail"/>
</@hst.html>
copy

Render Different Variants Based on Device

To select the image variant based on device type (for example, mobile, tablet, or desktop), use the following approach. Assume the device type is stored in the device variable.

JSP

<hst:html hippohtml="${requestScope.document.html}">
  <c:choose>
    <c:when test="${requestScope.device eq 'mobile'}">
      <hst:imagevariant name="hippogogreengallery:mobilethumbnail"/>
    </c:when>
    <c:when test="${requestScope.device eq 'tablet'}">
      <hst:imagevariant name="hippogogreengallery:largethumbnail"/>
    </c:when>
    <c:otherwise>
      <hst:imagevariant name="hippogallery:original"/>
    </c:otherwise>
  </c:choose>
</hst:html>
copy

Freemarker

<@hst.html hippohtml=document.html>
  <#if device == 'mobile'>
    <@hst.imagevariant name="hippogogreengallery:mobilethumbnail"/>
  <#elseif device == 'tablet'>
    <@hst.imagevariant name="hippogogreengallery:largethumbnail"/>
  <#else>
    <@hst.imagevariant name="hippogallery:original"/>
  </#if>
</@hst.html>
copy

Additional hst:imagevariant Attributes

The hst:imagevariant tag supports the following attributes:

• fallback: If set to true, the renderer falls back to the original variant if the specified variant does not exist. The default is false.
• replaces: A comma-separated list of variants in the rich text to be replaced by the specified image variant. Variants not listed remain unchanged.

Replace Only Specific Variants

To replace only the hippogallery:thumbnail and hippogallery:original variants, use the following code:

JSP

<hst:html hippohtml="${requestScope.document.html}">
  <hst:imagevariant name="hippogogreengallery:mobilethumbnail"
    replaces="hippogallery:thumbnail,hippogallery:original"/>
</hst:html>
copy

Freemarker

<@hst.html hippohtml=document.html>
  <@hst.imagevariant name="hippogogreengallery:mobilethumbnail"
    replaces="hippogallery:thumbnail,hippogallery:original"/>
</@hst.html>
copy

Verification

After implementing the template changes, verify that the correct image variant renders for each context (device type, menu presence, or bandwidth condition). Check that only the intended variants are replaced when using the replaces attribute.

Related Topics

• Rich Text Field Rewriting
• Imageset Definition
• Template Development