Multiple Page Mappings in Single SiteMap Item

Use case

Assume you want to have a common folder in the cms, that can contain mixed document types, for example documents of type simpledocument or  advanceddocument. For example something like:

/content:
  /documents:
    /myproject:
      /common:
        /about-us:
          jcr:primaryType: myproject:simpledocument
        /address:
          jcr:primaryType: myproject:simpledocument
        /contact-us:
          jcr:primaryType: myproject:advanceddocument

Typically you might want to render an advanceddocument completely different than a simpledocument. For example the simpledocument has a left, middle and right component, and the advanceddocument only has a middle component. In other words, you want both document types to be rendered by a complete different hst:componentconfiguration. 

You can work around this problem by grouping the different document types in artificial folders below common, for example common/simple and common/advanced. However, there are more elegant solutions:

1. Using a SitemapItem Handler on a sitemap item, or
2. Configure multiple explicit component configuration ids per document type on a single sitemap item.

The second option is explained below.

You can configure multiple explicit component configuration per document type in a single sitemap item. For example, you can configure your hst:sitemapitem as follows:

/hst:sitemap:
  jcr:primaryType: hst:sitemap
  /common:
     jcr:primaryType: hst:sitemapitem
     /**.html:
       jcr:primaryType: hst:sitemapitem
       hst:relativecontentpath: common/$[1]
       hst:componentconfigurationid: hst:pages/defaultpage
       hst:componentconfigurationmappingnames = ['myproject:simpledocument', 'myproject:advanceddocument']
       hst:componentconfigurationmappingvalues = ['hst:pages/simplepage', 'hst:pages/advancedpage']

In the example above, the hst:componentconfigurationmappingnames and hst:componentconfigurationmappingvalues are multi-valued properties and must be of the same size if they are configured. The first item of the names maps to the first item of the values, and so on for the the second item, third item, etc.

Now, say, the relativecontentpath with ${1} substituted by the part in the URL, points to a document of type myproject:advanceddocument, the page will be rendered as a hst:pages/advancedpage. If the relativecontentpath points to a document of type myproject:simpledocument, the page will be rendered as a hst:pages/simplepage. If the document belonging to the relativecontentpath does not point to a document of type myproject:simpledocument nor of type myproject:advanceddocument, then the page will be rendered with the default hst:componentconfigurationid, which is in the case above hst:pages/defaultpage.

Now this makes it possible to store any document of any type directly in the folder common and render it completely differently. You do not need to make multiple nested sitemap items any more and no placeholder folders anymore that contain only documents of one type.