This article covers a Bloomreach Experience Manager version 13. There's an updated version available that covers our most recent release.

HST Example of Context Aware Lightbox for all inline images

For the website you are looking at (  we want on detail pages to

  1. Always by default show a small threecolumn variant, regardless which variant was selected in the CMS

  2. Have the threecolumn variant clickable to get a larger variant

  3. Show a ninecolumn variant when there is no leftmenu (contextual part)

  4. Show a sixteencolumn variant when there is a leftmenu (contextual part)

Note that the contextual part could also be whether a visitor is using a mobile device, has low bandwidth, etc etc.

Set the context whether the ninecolumn or sixteencolumn should be shown when threecolumn is toggled

Assume your LeftMenu component looks like below. There, we store on the HstRequestContext whether there will be shown a left menu on the page or not. Since all #doBeforeRender(..) calls of every HstComponent is done before any renderer (jsp/freemarker) is invoked, this " wideview" attribute is available in every renderer.

public void doBeforeRender(final HstRequest request,
                           final HstResponse response) {
  HstSiteMenu menu =
  // only if there is a sitemenu item expanded we show the menu :
  // if there is no expanded item at all, we want to show the
  // 'wide document' view, and no menu at all. Hence check here whether to
  // set the sitemenu at all on the request
  if(menu.getDeepestExpandedItem() != null ) {
    request.setAttribute("menu", menu);
  } else {
     // this is a bit dirty but we need to 'tell' the main component
     // during the rendering of its jsp it should be a wide listing
     // style. We do this through an attribute on the requestContext
     // which is not very clean
     request.getRequestContext().setAttribute("wideview", true);

Use in JSP an hst:imagevariant to switch between nine or sixteen column image when image is toggled

Since we want to get the value for wideview from the HstRequestContext, we first need to add in the template:





Then we can do the following:


  <c:when test=
          "${requestScope.hstRequest.requestContext.attributes['wideview'] == true}">
    <hst:html hippohtml="${requestScope.document.html}"
        <hst:imagevariant name="mygallery:sixteencolumn"/>
    <hst:html hippohtml="${requestScope.document.html}"
      <hst:imagevariant name="mygallery:ninecolumn"/>


<#if hstRequest.requestContext.attributes['wideview'] == true>
  <@hst.html hippohtml=document.html
    <@hst.imagevariant name="mygallery:sixteencolumn"/>
  <@hst.html hippohtml=document.html
    <@hst.imagevariant name="mygallery:ninecolumn"/>

Also note, that we already set contentRewriter="${lightboxContentRewriter}"

Make sure the 'lightboxContentRewriter' content rewriter is available on every HstComponent

We assume all your HstComponent do a call to MyBaseComponent#doBeforeRender(...). Then, if your base component contains the code below, there will be a lightboxContentRewriter available for every renderer:


public abstract class MyBaseComponent extends BaseHstComponent {
    public static final LightboxContentRewriter lightboxContentRewriter =
                                       new LightboxContentRewriter();
    public void doBeforeRender(HstRequest request, HstResponse response) {
        // always have the custom content rewriter available

Implement your custom LightboxContentRewriter

We need to change the html from the rich text to inject behavior for images (not external ones) when clicked. Assume we have the following requirements

  • By default we always show the threecolumn variant

  • When clicked, the imagevariant from <hst:imagevariant> should be shown (thus mygallery:sixteencolumn or mygallery:ninecolumn in our case)

Again, we could only change the behavior for image tags, leave the link ( a) tags untouched, and at the end of #rewrite(...) call SimpleContentRewriter#rewrite(..). However, we'll also handle link tags in our example below as well. We will change the html as follows:

  • For every image, set the src to the threecolumn variant

  • Add the img alt attribute that contains the toggle variant (nine/sixteen column). In all fairness, using alt attribute is a bit of a trick

  • Add a wrapper div around the image that will be the container of the image.


public class LightboxContentRewriter extends SimpleContentRewriter {
    private final static Logger log =

    private static boolean htmlCleanerInitialized;
    private static HtmlCleaner cleaner;

    private static synchronized void initCleaner() {
        if (!htmlCleanerInitialized) {
            cleaner = new HtmlCleaner();
            CleanerProperties props = cleaner.getProperties();
            htmlCleanerInitialized = true;

    protected static HtmlCleaner getHtmlCleaner() {
        if (!htmlCleanerInitialized) {

        return cleaner;
    public String rewrite(final String html, final Node node,
                          final HstRequestContext requestContext,
                          final Mount targetMount) {

        if (html == null) {
            return null;

        try {
            TagNode rootNode =  getHtmlCleaner().clean(html);

            TagNode [] links = rootNode.getElementsByName("a", true);
            for (TagNode link : links) {
                String documentPath =  link.getAttributeByName("href");
                if (StringUtils.isBlank(documentPath)) {
                if(isExternal(documentPath)) {
                } else {
                    String queryString = StringUtils.substringAfter(
                                                       documentPath, "?");
                    boolean hasQueryString = !StringUtils.isEmpty(
                    if (hasQueryString) {
                        documentPath = StringUtils.substringBefore(
                                                       documentPath, "?");
                    String rewritterHref;
                    HstLink href = getDocumentLink(documentPath,node,
                    if (href != null && href.getPath() != null) {
                        rewritterHref = href.toUrlForm(requestContext,
                        if (hasQueryString) {
                            rewritterHref += "?"+ queryString;
                        // override the href attr
                        setAttribute(link, "href", rewritterHref);
                    } else {
                        log.warn("Skip href because url is null");

            TagNode [] images = rootNode.getElementsByName("img", true);
            ImageVariant threeColVar = new DefaultImageVariant(
                                 "connectgallery:threecolumn", null, true);
            int i = 0;
            for (TagNode image : images) {
                String srcPath =  image.getAttributeByName("src");
                if (StringUtils.isBlank(srcPath)) {
                if(isExternal(srcPath)) {
                } else {
                    HstLink binaryLink = getBinaryLink(srcPath, node,

                    ImageVariant originalVariant = getImageVariant();
                    // get the 3column variant as well : this is by
                    // default shown
                    HstLink threeColVarBinaryLink = getBinaryLink(srcPath,
                                        node, requestContext, targetMount);

                    // set the imageVariant backl to original one again
                    if (binaryLink != null &&
                           binaryLink.getPath() != null) {
                        String rewrittenSrc =
                           binaryLink.toUrlForm(requestContext, true);
                        String rewrittenSrcThreeCol =
                        // remove original one and add new image
                        // override the src attr
                        TagNode imageCopy = makeCopy(image);

                        setAttribute(imageCopy, "src", rewrittenSrcThreeCol);
                        imageCopy.addAttribute("id", "img-id" + i);
                        final String alternativeText =
                        if (alternativeText != null) {
                        setAttribute(imageCopy, "alt", rewrittenSrc);
                            " lightBox");
                    } else {
                        log.warn("Skip href because url is null");

            // everything is rewritten. Now write the "body" element as
            // result
            TagNode [] targetNodes =
                          rootNode.getElementsByName("body", true);
            if (targetNodes.length > 0 ) {
                TagNode bodyNode = targetNodes[0];
                return getHtmlCleaner().getInnerHtml(bodyNode);
            }  else {
                log.warn("Cannot rewrite content for '{}' because there
                           is no 'body' element" + node.getPath());

        } catch (Exception e) {
            throw new RuntimeException(e);
        return null;

    private void setAttribute(TagNode tagNode, String attrName, String attrValue) {
        if (tagNode.hasAttribute(attrName)) {
        tagNode.addAttribute(attrName, attrValue);

    private TagNode makeCopy(TagNode toCopy) {
        TagNode copy = new TagNode(toCopy.getName());
        for (Map.Entry<String,String> attr :
                             toCopy.getAttributes().entrySet()) {
            copy.addAttribute(attr.getKey(), attr.getValue());
        return copy;


Last step : Add some css, javascript and magnifier images

Since all images now are rendered by default as the threecolumn variant, there is a wrapper, there are id attributes, and there is a wrapper div, all that is needed is some css, javascript and two images.


CSS for the lightbox toggling:

/** begin lightbox **/

img.lightBox {
    cursor: pointer;

.img-magnifier {
    width: 60px;
    height: 60px;
    cursor: pointer;
    background-image: url("../images/magnifier-plus.png");

.img-magnifier.minimize {
   background-image: url("../images/magnifier-min.png");

/** end lightbox **/


JS code for the lightbox toggling:

// lightbox    $('.lightBox').each(function() {
        var img = $(this);

        img.parent().append('<span class="img-magnifier" />');
        var magnifier = $('.img-magnifier', img.parent());

        var alignMagnifier = function() {
            var imgPosition = img.position();
            if (magnifier.hasClass('minimize')) {
                magnifier.css('left', imgPosition.left + img.width() -
                magnifier.css('top', + img.height() -
            } else {
                magnifier.css('left', imgPosition.left + img.width() / 2 -
                               magnifier.width() / 2);
                magnifier.css('top', + img.height() / 2 -
                               magnifier.height() / 2);

        var magnify = function() {
            var previousSrc = img.attr('src');
            img.attr('src', img.attr('alt'));
            img.attr('alt', previousSrc);

And last thing, make sure you add the images images/magnifier-plus.png and images/magnifier-min.png

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?