Bloomreach

Bloomreach Documentation version

Head Contributions

Introduction

Hippo's delivery tier renders web pages following a  Hierarchical Model-View-Controller pattern: a page consists of a hierarchy of independent components, each having their own model, view and controller. The top component in the hierarchy is responsible for rendering the web page's HTML skeleton, including the head and body elements. However a component further down in the hierarchy might need to add additional elements to the page's head element, for example to load CSS or Javascript files required by its rendering template. This can be achieved through head contributions.

What is a Head Contribution?

A head contribution is:

  • a DOM element,
  • defined inside a non-root component's rendering template,
  • rendered by the root component's rendering template.

Note that the root component's template does not necessarily have to render the head contribution inside the HTML head element (e.g. script elements are commonly placed inside the HTML body element, just before the closing </body> tag, for performance reasons).

Making a Head Contribution in a Component

To make a head contribution inside a component's rendering template, place the element to be contributed inside an hst:headContribution tag:

JSP

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

Freemarker

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

Including Head Contributions in the Top Level Component

To include in the root component's template all head contributions made by components further down in the hierarchy use the hst:headContributions tag:

JSP

<hst:headContributions/>

Freemarker

<@hst.headContributions/>

Options

A head contribution can have two optional attributes:

  • A category to differentiate between types of elements (e.g. scripts, style sheets) so they can be rendered at different locations in the root component's template.
  • A  key hint to avoid collisions if multiple components contribute the same element (e.g. a script tag to load a generic Javascript library such as jQuery).

Below is an example of a head contribution that specifies both a key hint ( jquery) and a category ( scripts).

JSP

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

Freemarker

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

At inclusion time key hints will be transparently handled, but categories must be explicitly included or excluded.

Below is an example of head contributions inclusion by category in a root component's template, where head contributions of the category 'scripts' are rendered inside the body element, and all other head contributions are rendered inside the head element.

JSP

<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

<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>

Multiple categories can be included or excluded in a single head contributions inclusion:

JSP

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

Freemarker

<@hst.headContributions categoryExcludes="css, scripts"/>
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?