Index Routes

Introduction

Goal

Configure index routes to render default documents when URLs match a route mapped to a folder.

Background

The special index matcher enables a flexible routes design that can map part of the URL space of a website directly to a part of the content structure in the repository. Explicit routes and _default_ routes can have an _index_ child route which maps to a document or folder. Whenever a request matches a route with an _index_ child route, an attempt is made to map the request to the content path configured for the _index_ route. If that content path does not exist, the request is mapped to the content path configured for the originally matched sitemap item.

In this short tutorial, you will replace the Reference SPA's out-of-the-box _any_ route for pages with a multi-level route using _default_ and _index_ matchers to map URLs that match folders to default documents called "index" in those folders.

Prerequisites

Before starting:

To make the site configuration changes in this tutorial, we recommend using the Site development app in the Bloomreach UI or use the Postman Collection to make the Site Management API requests. However, you can use any other method or tool you like such as curl or httpies.

Preparation

Create a new channel using the Reference SPA channel template and call it 'tutorial'.

Create a development project called 'Index Routes Tutorial' and add the 'tutorial' channel to it.

Configure Index Routes

Navigate to the Site development app, choose your development project, and open the Routes tab.

Select the _any_ route. This single wildcard matcher maps URLs to their matching repository path under the 'pages' folder (using the relative content path pages/${1}):

12801280

To be able to use _index_ matchers, you'll need to replace the single _any_ matcher with multiple levels of _default_ matchers with corresponding _index_ child matchers.

Delete the _any_ route:

12791279

Then create a new route with the following properties:

  • Name: _default_
  • Relative content path: pages/${1}
12801280

From the new _default_ route's context menu, choose Add route to add a child route:

12791279

Enter the following properties for the child route:

  • Name: _default_
  • Relative content path: ${parent}/${2}

Then add a child route to the child route with the following properties:

  • Name: _default_
  • Relative content path: ${parent}/${3}

You should now have a small tree structure that looks like this:

485485

To each _default_ route in the tree, add a child route with the following properties:

  • Name: _index_
  • Relative content path: ${parent}/index

The complete route structure should now look like this:

12791279

If, instead of using the Site development app, you prefer to interact with the Site Management API directly, delete the _any_ route using the DELETE request to the routes endpoint:

DELETE https://[account_name].bloomreach.io/management/site/v1/channels/tutorial-[branch_id]/routes/_any_

Then use a PUT request to the routes endpoint to create the _default_ route:

PUT https://[account_name].bloomreach.io/cms/management/site/v1/channels/tutorial-[branch_id]/routes/_default_

Make sure to include your authorization token in the x-auth-token header!

Note that, since you are creating a new route, the X-Resource-Version header should not be included in the request (if you use Postman, uncheck it on the Headers tab).

Use the following JSON as payload:

{
  "name": "_default_",
  "layout": null,
  "pageTitle": null,
  "relativeContentPath": "pages/${1}",
  "referenceId": null,
  "parameters": {},
  "documentRequired": false,
  "doctypePages": {},
  "items": [
    {
      "name": "_default_",
      "layout": null,
      "pageTitle": null,
      "relativeContentPath": "${parent}/${2}",
      "referenceId": null,
      "parameters": {},
      "documentRequired": false,
      "doctypePages": {},
      "items": [
        {
          "name": "_default_",
          "layout": null,
          "pageTitle": null,
          "relativeContentPath": "${parent}/${3}",
          "referenceId": null,
          "parameters": {},
          "documentRequired": false,
          "doctypePages": {},
          "items": [
            {
              "name": "_index_",
              "layout": null,
              "pageTitle": null,
              "relativeContentPath": "${parent}/index",
              "referenceId": null,
              "parameters": {},
              "documentRequired": false,
              "doctypePages": {},
              "items": []
            }
          ]
        },
        {
          "name": "_index_",
          "layout": null,
          "pageTitle": null,
          "relativeContentPath": "${parent}/index",
          "referenceId": null,
          "parameters": {},
          "documentRequired": false,
          "doctypePages": {},
          "items": []
        }
      ]
    },
    {
      "name": "_index_",
      "layout": null,
      "pageTitle": null,
      "relativeContentPath": "${parent}/index",
      "referenceId": null,
      "documentRequired": false,
      "parameters": {},
      "doctypePages": {},
      "items": []
    }
  ]
}

👍

Tip:

If you need to be able to match URLs with a path with more than 3 segments, add additional levels of _default_ and _index_ routes to the route structure.

Create Folders and Index Documents

Open the Content app and navigate to the "pages" folder for your channel.

Create a subfolder called "promotions".

Inside the "promotions" folder, create a page document called "index".

❗️

Beware:

Make sure to add the "index" document to the "Core" project and not to your tutorial development project. A bug in Bloomreach Content currently prevents index matches from working properly with documents that are created in a development project context.

Optionally, enter some metadata in the page document. Save and publish.

Preview Your Changes

From the View menu, choose your channel to preview the page.

12771277

The preview will load the "Core" and if you open the left drawer and look at the Sitemap tab, you'll see the page listed as "index" under "promotions". This is the original _any_ route at work.

12791279

👍

Tip:

Optionally, add some components to the page's (still empty) main container to make the page more recognizable.

You can also confirm the URL and the page location if you open the Page menu and choose Info.

654654

Now use the For project selector to select your development project. You should see the "index" page under "promotions" disappear from the sitemap and see a 404 error page in the preview. This is because the URL of the page no longer exists.

In the Sitemap, select the "promotions" page. In the preview you should now see the default (index) page content.

12771277

Again, you can confirm the URL and the page location if you open the Page menu and choose Info.

656656