Pages, Components, Abstract Pages, and Templates

Pages, components, abstract pages, and templates define how the HST (Hippo Site Toolkit) assembles HMVC pages. As described in Sitemap Configuration, a matched sitemap item typically references an hst:component node under hst:pages using the hst:componentconfigurationid property. Each hst:component node can contain child hst:component nodes, allowing you to build pages as composite structures. This page explains the configuration model using a series of examples, increasing in complexity to cover all relevant concepts.

Example 1: Basic Configuration

/hst:hst:
  /hst:configurations:
    /example:
      /hst:sitemap:
        /about.html:
          hst:componentconfigurationid: hst:pages/textpage
          hst:relativecontentpath: common/about
      /hst:pages:
        jcr:primaryType: hst:pages
        /textpage:
          jcr:primaryType: hst:component
          /header:
            jcr:primaryType: hst:component
            /main:
              jcr:primaryType: hst:component
              /leftmenu:
                jcr:primaryType: hst:component
              /content:
                jcr:primaryType: hst:component
              /right:
                jcr:primaryType: hst:component

Explanation

This configuration defines a single sitemap item, about.html. When a request matches this item, the HST renders the page using the textpage component defined under hst:pages. The structure under textpage specifies the page composition.

The hst:relativecontentpath property points to the canonical content for the request. The model for rendering the page is based on this content, but the model can also access the entire repository, including search and, if the Relevance Module is enabled, visitor data. For details on accessing the canonical content, see HstRequestContext#getContentBean().

This example does not yet show how to configure views (hst:template) and controllers (hst:componentclassname). The next example adds these elements.

Example 2: Configuration with Views and Controllers

/example:
  /hst:pages:
    /textpage:
      hst:template: textpage.layout
      /header:
        hst:template: textpage.header
        hst:componentclassname: org.example.components.Header
        /main:
          hst:template: textpage.main
          /leftmenu:
            hst:template: textpage.main.leftmenu
            hst:componentclassname: org.example.components.LeftMenu
          /content:
            hst:template: textpage.main.content
            hst:componentclassname: org.example.components.Content
          /right:
            hst:template: textpage.main.right
 /hst:templates:
   /textpage.layout:
     hst:renderpath: jsp/textpage/layout.jsp
   /textpage.header:
     hst:renderpath: jsp/textpage/header.jsp
   /textpage.main:
     hst:renderpath: jsp/textpage/main.jsp
   /textpage.main.leftmenu:
     hst:renderpath: jsp/textpage/main/leftmenu.jsp
   /textpage.main.content:
     hst:renderpath: jsp/textpage/main/content.jsp
   /textpage.main.right:
     hst:renderpath: jsp/textpage/main/right.jsp

Explanation

Each hst:component node can define:

  1. A view (hst:template)
  2. Optionally, a controller (hst:componentclassname)

Controllers
Component nodes used only for structural layout often do not specify hst:componentclassname. In these cases, the HST uses a default controller. By default, this is org.hippoecm.hst.core.component.GenericHstComponent, but you can override this default. For details, see Configure a Default HstComponent classname. If you specify hst:componentclassname, use a fully qualified class name for a class that implements org.hippoecm.hst.core.component.HstComponent. For controller development details, see Component Development.

Views
Each hst:component node specifies a template using the hst:template property. This property points to a node under hst:templates. Each template node defines a hst:renderpath property, which can reference:

  1. A Freemarker template in Web Files
  2. A JSP in the web application resources
  3. A Freemarker template in the web application resources
  4. A Freemarker script in the template node itself, using the hst:script property
  5. A Freemarker template on the classpath

Options 1 and 4 allow runtime modification of views in production, as changes are reloaded automatically. For more information, see HST Freemarker Support.

From these examples, note:

  • Multiple sitemap items can reference the same page under hst:pages.
  • Multiple components can reference the same template.

If you need to create additional pages, such as newspage and newsoverview, which share most of their structure with textpage, you can use component referencing to avoid duplication.

Example 3: Component Referencing

/example:
  /hst:pages:
    /base:
      hst:template: base.layout
      /header:
        hst:template: base.header
        hst:componentclassname: org.example.components.Header
      /main:
        hst:template: base.main
        /leftmenu:
          hst:template: base.main.leftmenu
          hst:componentclassname: org.example.components.LeftMenu
        /right:
          hst:template: base.main.right
    /textpage:
      hst:referencecomponent: hst:pages/base
      /content:
        hst:template: textpage.main.content
        hst:componentclassname: org.example.components.Content
    /newspage:
      hst:referencecomponent: hst:pages/base
      /content:
        hst:template: newspage.main.content
        hst:componentclassname: org.example.components.Content
    /newsoverview:
      hst:referencecomponent: hst:pages/base
      /content:
        hst:template: newsoverview.main.content
        hst:componentclassname: org.example.components.NewsOverview

Explanation

This configuration defines three pages: textpage, newspage, and newsoverview. Each references the shared base page using:

- hst:referencecomponent = hst:pages/base

The base page provides the common layout, including the header, main/leftmenu, and main/right components. Each concrete page defines its own content component. For details on how referenced components are merged, see HstComponent Configuration.

Example 4: Abstract Pages

If a page such as base is only intended for reuse and should not be referenced directly by sitemap items, move it to hst:abstractpages for clarity. The configuration then becomes:

/example:
  /hst:abstractpages:
    jcr:primaryType: hst:pages
    /base:
      hst:template: base.layout
      /header:
        hst:template: base.header
        hst:componentclassname: org.example.components.Header
      /main:
        hst:template: base.main
        /leftmenu:
          hst:template: base.main.leftmenu
          hst:componentclassname: org.example.components.LeftMenu
        /right:
          hst:template: base.main.right
  /hst:pages:
    /textpage:
      hst:referencecomponent: hst:abstractpages/base
        /content:
          hst:template: textpage.main.content
          hst:componentclassname: org.example.components.Content
    /newspage:
      hst:referencecomponent: hst:abstractpages/base
      /content:
        hst:template: newspage.main.content
        hst:componentclassname: org.example.components.Content
    /newsoverview;
      hst:referencecomponent: hst:abstractpages/base
      /content:
        hst:template: newsoverview.main.content
        hst:componentclassname: org.example.components.NewsOverview

Explanation

The base page is now under hst:abstractpages. All referencing pages update their hst:referencecomponent property:

hst:referencecomponent = hst:abstractpages/base

Sitemap items must not use hst:componentconfigurationid to reference a page under hst:abstractpages. If this occurs, the HST logs a warning and ignores the configuration.

Important:
Never reference an abstract page directly from a sitemap item.

At this point, you have seen how to structure pages, abstract pages, and templates. The next section covers components and their reuse.

Example 5: Using hst:components for Modular Configuration

/example:
  /hst:abstractpages:
    jcr:primaryType: hst:pages
    /base
      hst:template: base.layout
      /header
        hst:referencecomponent: hst:components/header
      /main
        hst:template: base.main
        /leftmenu
          hst:referencecomponent: hst:components/leftmenu
        /right
          hst:template: base.main.right
  /hst:pages:
    jcr:primaryType: hst:pages
    /textpage
      hst:referencecomponent: hst:abstractpages/base
      /content
        hst:referencecomponent: hst:components/content
    /newspage
      hst:referencecomponent: hst:abstractpages/base
      /content
        hst:referencecomponent: hst:components/content
        hst:template: newspage.main.content                !!!
    /newsoverview
      hst:referencecomponent: hst:abstractpages/base
      /content
        hst:referencecomponent: hst:components/newsoverview
  /hst:components:
    jcr:primaryType: hst:components
    /header
      hst:template: base.header
      hst:componentclassname: org.example.components.Header
    /leftmenu
      hst:template: base.main.leftmenu
      hst:componentclassname: org.example.components.LeftMenu
    /content
      hst:template: textpage.main.content
      hst:componentclassname: org.example.components.Content
    /newsoverview
      hst:template: newsoverview.main.content
      hst:componentclassname: org.example.components.NewsOverview

Explanation

Compared to Example 4:

  1. All components with an explicit controller (hst:componentclassname) are moved under hst:components.
  2. The hst:abstractpages and hst:pages nodes reference these components using hst:referencecomponent.

Key points:

  • Multiple inheritance is supported. For example, hst:pages/textpage references hst:abstractpages/base, which can reference or include other components.
  • You can override properties of inherited components by defining them explicitly. In the configuration above, the newspage/content node references hst:components/content but overrides the template with newspage.main.content (see the line marked with !!!).

This modular approach improves reusability and maintainability of your HST configuration. Use hst:components for components with explicit controllers, and reference them from your page structures as needed.

Share Feedback
Page: /build/hst-configuration/core-configuration/pages-components-abstractpages-and-templates
Section: Build
Category *