Create a route type with fields in JSS code-first development

Current version: 19.x

By default, all the imported fields in a JSS app are placed in what Sitecore calls data sources. These are data items that are referenced in the layout of the route item. The route item itself does not contain any of its own fields by default.

To add fields to an item, you must do it on a data template.

JSS allows you to define fields for custom route types. The custom route types are imported as new data templates in Sitecore.

Tip

If you are not using the code-first development workflow, you can use fields from route data templates created in Sitecore.

Some of the situations when you might want to add fields directly on the route are:

  • You are using fields outside components placed in Placeholder components, such as header metadata or data in other statically-placed components.

  • You have content or data you want to use in several components in a route, rather than just in a single component.

  • You are adding default layout to a route template on its standard values (currently this must be done in Sitecore itself).

  • Advanced data modeling scenarios.

Note

The JSS import process always generates a route template for each app. This template is the default route template but is also automatically set as a base template for any route types defined in the app manifest.

To create a route type with fields directly on the route and use it for your routes:

  1. In the manifest generator file where you define/add your routes, for example, sitecore/definitions/routes.sitecore.js, use the addRouteType function to add a route type with a name and fields:

    RequestResponse
    manifest.addRouteType({
    name: 'MyRoute',
    fields: [
        { name: 'metaTitle', displayName: 'Meta Title', type: manifest.fieldTypes.singleLineText },
        { name: 'titleText', displayName: 'Body Title', type: manifest.fieldTypes.singleLineText },
        { name: 'body', displayName: 'Body Text', type: manifest.fieldTypes.richText }
    ]
    });
    Note

    Define fields in the same way as in a component.

  2. In a route data file, for example, data/routes/about/en.json, mock the route data for a route and set the template property to the new custom route type using the name value for the custom route type:

    RequestResponse
    {
      "name": "route",
      "template": "MyRoute",
      "displayName": "Route",
      "fields": {
        "metaTitle": "My Route",
        "titleText": "My Route",
        "body": "Lorem ipsum dolor sit"
      },
      "placeholders": {
          // ...
      }
  3. If you are pulling route data from files, you might want to apply the new route type dynamically to any routes, especially if all your routes utilize the same type. You can inspect examples of how to do that for your chosen framework in the file sitecore/definitions/routes.sitecore.[js|ts].

The next time you import your application in Sitecore, the import process will create the data template for the new route type and any newly created routes will utilize the data template.

Important

Data template templates for existing routes are not changed during the import process. You must either manually delete them or change their template in Sitecore, or utilize full wipe mode during development.

Do you have some feedback for us?

If you have suggestions for improving this article,