HomeEngagementContentDiscoveryOther Resources

## 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:

  • Familiarize yourself with how to set up a [Development Environment](🔗) with a channel created using the [Reference SPA](🔗) template.

  • Have the [Site Management API](🔗) and [Routes](🔗) reference documentation handy.

  • If you want to use the Site Management API directly (rather than using the _Site development_ app in the UI), [obtain an authorization token](🔗).

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

### Using the UI

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}`):

1280


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:

1279


Then create a new route with the following properties:

  • _Name_: `_default_`

  • _Relative content path_: `pages/${1}`

1280


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

1279


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:

485


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:

1279


### Using the API

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](🔗):


Then use a [PUT request to the routes endpoint](🔗) to create the `_default_` route:

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:

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
### Using the UI
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". Make sure to select the "Index Routes Tutorial" development project in the dialog.
956

Optionally, enter some metadata in the page document. Save.
### Using the API
If, instead of using the _Content_ app, you prefer to interact with the Management APIs directly, use a PUT request to the Folder endpoint to create the "promotions" folder:

Use the following JSON as payload:

Then use a PUT request to the Content Management API's Page endpoint to create the "index" page (You can find the 6 character project ID (e.g. `vMxAw` in the Projects and Site development apps):

Use the following JSON payload:

If your API requests were successful, open the Content app and navigate to the "index" page in the "promotions" folder you created.
## Preview Your Changes
From the _View_ menu, choose your channel to preview the page.
1277

The channel preview will load and if you open the left drawer and look at the _Sitemap_ tab, you'll see the page listed as "promotions".
1277

You can confirm the URL and the page location if you open the _Page_ menu and choose _Info_. Note how the "promotions" URL is mapped to the "index" page.
656

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