Wrapping Component Contents

Info:
An HST Component can define a wrapper element for its rendered content. This makes it easier to target the component's markup from client-side code, such as JavaScript.

You can set a wrapper element by calling HstResponse#setWrapperElement(Element) in your component logic, or by including the <hst:wrapperElement /> tag in your JSP or Freemarker template. Both approaches produce the same result.

Overview

Wrapping the output of an HST Component in a specific HTML element allows you to select or manipulate the component's markup using client-side technologies. This is useful when you need to apply JavaScript or CSS to a component's rendered content.

Example: Wrapping Rendered Markup

Suppose your component renders the following HTML:

Info:
<h1>Always Look on the Bright Side of Life (from Monty Python)</h1>

<p>Some things in life are bad. They can really make you mad. Other things just make you swear and curse. When you're chewing on life's gristle. Don't grumble, give a whistle. And this'll help things turn out for the best...</p>

To make it easier to reference this content from client-side code, wrap the markup in a container element, such as a <span> with an ID and class:

Info:
<span id="component1" class="wrapper">

<h1>Always Look on the Bright Side of Life (from Monty Python)</h1>

<p>Some things in life are bad. They can really make you mad. Other things just make you swear and curse. When you're chewing on life's gristle. Don't grumble, give a whistle. And this'll help things turn out for the best...</p>

</span>

With this structure, you can use DOM APIs or CSS selectors to target the component's content by its wrapper element.

Automating Wrapper Elements

Manually adding wrapper elements to every JSP or Freemarker template is inefficient. Instead, use the HstResponse API to set the wrapper element programmatically.

The HstResponse interface provides these methods:

import org.w3c.dom.Element;

public void setWrapperElement(Element element);
public Element getWrapperElement();
copy

To wrap a component's rendered markup, call setWrapperElement(Element) in your component logic.

For example, to wrap all component markup in a base component class, add the following to the doBeforeRender() method:

// BaseComponent.java

public void doBeforeRender(HstRequest request, HstResponse response) throws HstComponentException {
    // ...
    // Set a wrapper element for each component
    Element wrapperElem = response.createElement("span");
    wrapperElem.setAttribute("class", "wrapper");
    response.setWrapperElement(wrapperElem);
    // ...
}
copy

If your component extends this base class and calls super.doBeforeRender(...), the rendered output will include the specified wrapper element. You do not need to modify each template individually.

Setting Wrapper Elements in Templates

You can also define a wrapper element directly in your template using the tag library.

JSP Example:

Info:
<hst:element var="wrapperElem" name="span">

<hst:attribute name="id" value="component1" />

<hst:attribute name="class" value="wrapper" />

</hst:element>

<hst:setWrapperElement element="${wrapperElem}" />

Freemarker Example:

Info:
<@hst.element var="wrapperElem" name="span">

<@hst.attribute name="id" value="component1" />

<@hst.attribute name="class" value="wrapper" />

</@hst.element>

<@hst.setWrapperElement elementByBeanPath="wrapperElem" />

Using the tag library in your template has the same effect as calling HstResponse#setWrapperElement(Element) in your component logic. Because the template is processed after doBeforeRender(), setting the wrapper element in the template overrides any wrapper set in the component.

Summary

• Use a wrapper element to make component markup accessible to client-side code.
• Set the wrapper element programmatically in your component or declaratively in your template.
• Setting the wrapper in the template overrides any wrapper set in the component's logic.