Use _index_ Sitemap Items
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.