Head Contributions

Overview

In Bloomreach Content, the delivery tier renders web pages using a Hierarchical Model-View-Controller (HMVC) pattern. Each page is built from a hierarchy of independent components, and each component has its own model, view, and controller. The top-level component is responsible for rendering the main HTML structure, including the head and body elements.

Components deeper in the hierarchy may need to add elements to the page's head, such as CSS or JavaScript files required by their templates. You can achieve this using head contributions.

What Is a Head Contribution?

A head contribution is:

A DOM element
Defined in a non-root component's rendering template
Rendered by the root component's rendering template

The root component's template does not have to render head contributions inside the HTML head element. For example, script elements are often placed at the end of the body for performance reasons.

Creating a Head Contribution in a Component

To contribute an element from a component's rendering template, wrap the element in an hst:headContribution tag.

JSP Example

<hst:headContribution>
  <hst:link path="/js/rate.js" var="rateJs"/>
  <script type="text/javascript" src="${rateJs}"></script>
</hst:headContribution>

Freemarker Example

<@hst.headContribution>
  <@hst.link path="/js/rate.js" var="rateJs"/>
  <script type="text/javascript" src="${rateJs}"></script>
</@hst.headContribution>

Rendering Head Contributions in the Root Component

To render all head contributions from child components in the root component's template, use the hst:headContributions tag.

JSP Example

<hst:headContributions/>

Freemarker Example

<@hst.headContributions/>

Head Contribution Options

Head contributions support two optional attributes:

category: Use to group elements by type (such as scripts or stylesheets) so you can render them in specific locations in the root template.
keyHint: Use to prevent duplicate contributions when multiple components add the same element (for example, a script tag for a shared JavaScript library like jQuery).

The following example specifies both a key hint (jquery) and a category (scripts):

JSP Example

<hst:headContribution keyHint="jquery" category="scripts">
  <hst:link path="/js/jquery.js" var="jqueryJs"/>
  <script type="text/javascript" src="${jqueryJs}"></script>
</hst:headContribution>

Freemarker Example

<@hst.headContribution keyHint="jquery" category="scripts">
  <@hst.link path="/js/jquery.js" var="jqueryJs"/>
  <script type="text/javascript" src="${jqueryJs}"></script>
</@hst.headContribution>

Key hints are handled automatically to avoid duplicates. You must explicitly include or exclude categories when rendering head contributions.

The following example shows how to render head contributions by category in a root component template. Here, contributions in the scripts category are rendered inside the body, and all others are rendered in the head.

JSP Example

<html>
  <head>
    <title>Example</title>
    <hst:headContributions categoryExcludes="scripts"/>
  </head>
  <body>
    <hst:include ref="header"/>
    <hst:include ref="content"/>
    <hst:include ref="footer"/>
    <hst:headContributions categoryIncludes="scripts"/>
  </body>
</html>

Freemarker Example

<html>
  <head>
    <title>Example</title>
    <@hst.headContributions categoryExcludes="scripts"/>
  </head>
  <body>
    <hst:include ref="header"/>
    <hst:include ref="content"/>
    <hst:include ref="footer"/>
    <@hst.headContributions categoryIncludes="scripts"/>
  </body>
</html>

You can include or exclude multiple categories in a single tag:

JSP Example

<hst:headContributions categoryExcludes="css, scripts"/>

Freemarker Example

<@hst.headContributions categoryExcludes="css, scripts"/>