Use _index_ Sitemap Items

Info: The _index_ sitemap item feature is available starting from Hippo CMS 11.2.0.

Overview

The _index_ sitemap item allows you to map URLs to a default document or folder. If the default document or folder does not exist, the request falls back to the parent sitemap item's content. This mechanism provides flexible handling of folder and document rendering in your site's URL structure.

When to Use

Use _index_ sitemap items when you need to:

Render a default document (such as an introduction or overview) when a user navigates to a folder URL.
Fall back to rendering a folder listing if the default document is not present.
Support flexible URL mapping that adapts to the presence or absence of specific documents within folders.

Background

With sitemap wildcard matchers, you can map parts of your website's URL space directly to corresponding sections in the content repository. This mapping can target both documents and folders. When a URL maps to a document, the document content is rendered. When a URL maps to a folder, you have options such as rendering a list of documents in the folder or displaying a default document.

The _index_ sitemap item extends this approach. You can add an _index_ child sitemap item to explicit or _default_ sitemap items. When a request matches a sitemap item with an _index_ child, the system attempts to resolve the request to the content path defined in the _index_ sitemap item. If that path does not exist, the request falls back to the content path of the originally matched sitemap item.

For a detailed explanation of how _index_ sitemap items work, see SiteMapItem Matching (section SiteMapItem _index_).

Example

This example uses a project created with the Bloomreach Content Maven archetype and includes the "Simple Content" feature.

By default, 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_ sitemap item maps to folders and renders the contentlist page, which displays a list of documents in the folder and its subfolders. For example, the URL http://localhost:8080/site/content/artists/ maps to the folder content/artists and renders its document list.
The /content/_any_.html sitemap item maps to documents and renders the contentpage, displaying the document's content. For example, http://localhost:8080/site/content/artists/sculptors/rodin.html maps to the document content/artists/sculptors/rodin.

To render a default document (such as introduction) when a folder URL is accessed, update the sitemap to use _index_ sitemap items. If the default document does not exist, the system falls back to rendering the folder's document list.

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

Key changes:

_index_ sitemap items cannot be children of _any_ sitemap items. The second and third URL segments after content are now matched by _default_ sitemap items.
_any_ sitemap items match any remaining URL segments after the first three matched by content/_default_/_default_.
_index_ sitemap items are added as children of content, content/_default_, and content/_default_/_default_.
Each _index_ sitemap item maps to ${parent}/introduction, targeting a document named introduction in the parent folder.

Resulting Behavior

The content, content/_default_, and content/_default_/_default_ sitemap items map to folders. Their _index_ child checks for an introduction document in the mapped folder. If it exists, the system renders it using the contentpage page.
If the folder does not contain an introduction document, the system falls back to the parent sitemap item and renders the folder's document list using the contentlist page.

Example Content Structure

/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 content/artists/introduction exists, its content is rendered using the contentpage page.
The URL http://localhost:8080/site/content/artists/sculptors maps to the folder content/artists/sculptors. Since there is no introduction document in that folder, the system renders a list of documents in the folder using the contentlist page.