Types of JSS Manifest data

Version: 21.x

To mock content for your application when working disconnected from Sitecore, you can define multiple types of data in JSON or YAML files in the data directory of your JSS application. The data location is a convention you can change.

Actual manifest definitions, which include definitions derived from the data files, are located in /sitecore/definitions/*.sitecore.js. These manifest definition files use helper libraries to crawl the YAML/JSON files and add them to the manifest object. Some manifest items, components, and placeholders are usually defined using the JS API directly.

JSS generates the manifest by reading the YAML or JSON manifest data files from the data folder, then adding them to a JavaScript API that generates the manifest. Therefore, if you want to, you can replace the JSON or YAML files with direct JS API calls.

Tip

If you want to set explicit IDs on data items, you might be interested in how the import process handles item IDs.

Routes

A minimal route definition contains a name (used to construct the route segment). Most routes also define placeholders, defining a set of front-end components and data placed inside JSS Placeholder components of the same name.

In the sample apps, routes are defined in /data/routes/[path-to-route]/[language].{yaml|yml|json}. For example, /data/routes/en.yml is the route data for the / route in English, or /data/routes/about/es-MX.yml is the data for the /about route in Spanish (Mexico).

The structure of a route file

Very advanced capabilities are available in route files, but they can also be quite simple to define. For example, using YAML, you can define the route data file for the about route as follows:

RequestResponse
# /data/routes/about/en.yml

# name: names the route segment. Should match parent folder name.
name: about
# The root of the layout for this route
placeholders:
  # defines the components that belong in the 'main' placeholder
  # defining the appname-main placeholder requires a <Placeholder key="appname-main"> component added to the root app component
  appname-main:
  # Adds a component called 'Heading' to the route in the 'main' placeholder
  - componentName: Heading
    # Component data can be as complex as a reference to another component (see the reference),
    # or as simple as defining field values that the component receives
    fields:
      # To use fields, they must be defined on the component definition (see below)
      # a field consists of a top-level named object and a child value which may be a simple string,
      # or something more complex for fields like images
      titleField:
        value: Page Title
      imageField:
        value:
          src: "/assets/img/logo.png"
          alt: Logo
    # A component can itself expose placeholders (for example, Heading might expose 'appname-heading-content') that contain more components
    # Child placeholders are defined hierarchically under the component that exposes them
    placeholders: 
      appname-heading-content:
      - componentName: ContentComponentSample
        fields:
          # ...

The following sample represents the same route data, in JSON:

RequestResponse
{
  "name": "about",
  "placeholders": {
    "appname-main": [
      {
        "componentName": "Heading",
        "fields": {
          "titleField": {
            "value": "Page Title"
          },
          "imageField": {
            "value": {
              "src": "/assets/img/logo.png",
              "alt": "Logo"
            }
          }
        },
        "placeholders": {
          "content": [
            {
              "componentName": "ContentComponentSample"
            }
          ]
        }
      }
    ]
  }
}

Component content

Component content is a way to share components between routes. A typical scenario for using component content might be sketching out a JSS site with only lorem ipsum text and FPO (for placement only) images and therefore not wanting to maintain many copies of the same component. Or that there are pieces of content shared across multiple routes.

Component content is organized in a similar folder structure to routes (/data/component-content), with the same folder-and-language naming convention. Conventionally, you store component content under a folder named for the component it defines. For example, /data/component-content/<ComponentName>/id/en.yml.

The content of a shared component looks exactly like a component added directly to a route, except that you must specify an id and a name attribute so it can be referred to. The ID value must be unique across the entire JSS application.

RequestResponse
# /data/component-content/Heading/fpo-heading/en.yml

id: fpo-heading
name: FPO Fake Heading
componentName: Heading
fields:
  titleField:
    value: Page Title

Using the shared component on routes is very simple: you add a component to a placeholder. Instead of specifying a componentName and name, you specify only the id:

RequestResponse
# /data/routes/en.yml

name: home
placeholders:
  appname-main:
  - id: fpo-heading

In the previous example, the fpo-heading reference is on the home route. All of its data is expanded into the home route layout.

Another way to reference content that takes effect when you import the site into Sitecore is copying. When you import a reference like fpo-heading, in Sitecore, all usages of that reference are placed in a single content item. It facilitates sharing content (such as copyright).

Note

Do not use references to repeat lorem ipsum content on multicolumn promos, tabs, or carousels because, when imported, the final content is not shared and is not unique.

To reference content when importing the site into Sitecore through copying simply add copy: true to your ID reference:

RequestResponse
# /data/routes/en.yml

name: home
placeholders:
  appname-main:
  - componentName: Tabs
    placeholders:
      appname-tabs:
      - id: fpo-tab
        copy: true
      - id: fpo-tab
        copy: true

With the setup defined here, the two tabs are shared while disconnected. When imported to Sitecore, they become separate items that you can change independently.

Component parameters

There are times when your components must receive values that are not stored as fields on a data source item. In these cases, you can use rendering parameters.

You can expose the rendering parameters object on your component props data:

RequestResponse
{
  name: 'my-route',  
  placeholders: {
    jss-main: [
      {
        componentName: 'my-component',
        params: {
          paramName: 'paramValue'
        }
      }
    ]
  }
}
Note

You can define param values in route data as any JavaScript data type, such as number or Boolean, but all param values are strings when they are received by the components.

In your component code, you can access the params object in the component properties, for example, props.params.paramName.

As part of the manifest generation process, your params data is mapped to component objects you added to the manifest.

Content

It is possible to define content items that are neither routes nor shared component content. Examples include items that contain content for static items or items that are shared options for multi-list fields in content.

Content items work exactly like component content, with two exceptions:

  • Instead of componentName, specify a template.

  • You store definitions for content items in /data/content.

Dictionary data

JSS lets you develop multilingual applications while working disconnected. A common requirement in multilingual applications is to have a dictionary that translates non-content text elements such as form labels or global elements.

JSS sample applications define their dictionaries under /data/dictionary - a single file per language, such as en.yaml or es-MX.json, is added with a simple mapping between dictionary key and value:

RequestResponse
# /data/dictionary/es-MX.yaml

Login: Iniciar sesión
Close: Cerca
LoginFailed: Nombre de usuario y / o contraseña inválido.

Do you have some feedback for us?

If you have suggestions for improving this article,