Bloomreach

Bloomreach Documentation version

Developer Docs / Backend Development / Delivery Tier / URLs / Use _index_ Sitemap Items

Use _index_ Sitemap Items

This feature is available since Hippo CMS 11.2.0.

Introduction

Goal

Use _index_ sitemap items to map URLs to an optional default document or folder, with fallback to the content of the parent sitemap item if the default document or folder does not exist.

Background

Using sitemap wildcard matchers, developers can design part of the URL space of their website to map directly to a part of the content structure in the repository. Such a design will map to documents as well as folders. When mapping to a document, typically the document content should be rendered. When mapping to a folder, there are multiple options such as rendering a list of documents in that folder or rendering a default document. When rendering default content, it may even be required to fall back to rendering a list of documents in case the default document or folder does not exist in the mapped relative content.

The special _index_ sitemap item enables a flexible sitemap design that can handle such scenarios. Explicit sitemap items and _default_ sitemap items can have an _index_ child sitemap item which maps to a document or folder. Whenever a request matches a sitemap item with an _index_ child item, an attempt is made to map the request to the content path configured for the _index_ sitemap item. If that content path does not exist, the request is mapped to the content path configured for the originally matched sitemap item.

This page provides an example of how the _index_ sitemap item can be used.

The exact working of _index_ sitemap items is explained in SiteMapItem Matching (section SiteMapItem _index_).

Example

The example below is based on a default implementation project created using the Bloomreach Experience Manager Maven archetype, with the "Simple Content" feature added.

Out of the box, the "Simple Content" feature provides the following sitemap structure:

/hst:myproject/hst:configurations/myproject/hst:sitemap:
  /content:
    hst:componentconfigurationid: hst:pages/contentlist
    hst:relativecontentpath: content
    /_any_:
      hst:componentconfigurationid: hst:pages/contentlist
      hst:relativecontentpath: ${parent}/${1}
    /_any_.html:
      hst:componentconfigurationid: hst:pages/contentpage
      hst:relativecontentpath: ${parent}/${1}

The /content/_any_ item is intended to map to folders and renders a contentlist page (showing a list of documents in that folder and its subfolders). For example, this sitemap item matches the URL http://localhost:8080/site/content/artists/ which maps to the folder content/artists and renders a list of documents in that folder and its subfolders.

The /content/_any_.html item is intended to map to documents and renders a contentpage (showing the document's contents). For example, this sitemap item matches the URL http://localhost:8080/site/content/artists/sculptors/rodin.html which maps to the document content/artists/sculptors/rodin and renders that document.

In the example below the sitemap design is adapted to render a default document in a folder when a URL is mapped to that folder. For example, at the URL http://localhost:8080/site/content/artists/, the content of the document content/artists/introduction is rendered.

In this use case, the sitemap needs to be able to handle a scenario in which no default document (introduction in the example) exists in the mapped folder (content/artists in the example). The _index_ sitemap item's fallback mechanism does exactly that.

Consider the following refactored sitemap structure:

/hst:myproject/hst:configurations/myproject/hst:sitemap:
  /content:
    hst:componentconfigurationid: hst:pages/contentlist
    hst:relativecontentpath: news
    /_default_:
      hst:componentconfigurationid: hst:pages/contentlist
      hst:relativecontentpath: ${parent}/${1}
      /_default_:
        hst:componentconfigurationid: hst:pages/contentlist
        hst:relativecontentpath: ${parent}/${2}
        /_any_:
          hst:componentconfigurationid: hst:pages/contentlist
          hst:relativecontentpath: ${parent}/${3}
        /_any_.html:
          hst:componentconfigurationid: hst:pages/contentpage
          hst:relativecontentpath: ${parent}/${3}
        /_index_:
          hst:componentconfigurationid: hst:pages/contentpage
          hst:relativecontentpath: ${parent}/introduction
      /_default_.html:
        hst:componentconfigurationid: hst:pages/contentpage
        hst:relativecontentpath: ${parent}/${2}
      /_index_:
        hst:componentconfigurationid: hst:pages/contentpage
        hst:relativecontentpath: ${parent}/introduction
    /_default_.html:
      hst:componentconfigurationid: hst:pages/contentpage
      hst:relativecontentpath: ${parent}/${1}
    /_index_:
      hst:componentconfigurationid: hst:pages/contentpage
      hst:relativecontentpath: ${parent}/introduction

Note the following changes:

  • Because _index_ sitemap items can't be children of _any_ sitemap items, the second and third URL segments (following content) are now matched by _default_ sitemap items.
  • _any_ sitemap items match the remaining URL segments after the first three that are matched by content/_default_/_default_.
  • _index_ sitemap items have been added as children of content, content/_default_, and content/_default_/_default_.
  • Each _index_ sitemap item maps to the content path ${parent}/introduction (a document names introduction in the folder mapped by the parent sitemap item).

This design provides the following functionality:

  • The content, content/_default_, and content/_default_/_default_ sitemap items are intended to map to folders only, but their _index_ child item checks if an introduction document exists in the mapped folder and if so, renders the contents of introduction using the contentpage page.
  • If the mapped folder does not contain an introduction document, the sitemap falls back to the originally matched sitemap item and renders a list of documents in the mapped folder using the contentlist page.

For example, consider the following content tree:

/content/documents/myproject:
  /content:
    jcr:primaryType: hippostd:folder
    /artists:
      jcr:primaryType: hippostd:folder
      /introduction:
        jcr:primaryType: hippo:handle
      /sculptors:
        jcr:primaryType: hippostd:folder
        /rodin:
          jcr:primaryType: hippo:handle
        /brancusi:
          jcr:primaryType: hippo:handle
    /introduction:
      jcr:primaryType: hippo:handle

The URL http://localhost:8080/site/content/artists/ maps to the folder content/artists. Because a document content/artists/introduction exists, its contents will be rendered using the contentpage page.

The URL http://localhost:8080/site/content/artists/sculptors maps to the folder content/artists/sculptors. Because no introduction document is present in that folder, a list of documents in the folder will be rendered using the contentlist page.

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?