Skip to main content

Adding Manifest definitions in code-first JSS apps

Abstract

Add items to the Manifest with Manifest API instance methods

When scaffolding components, if you have not modified the script to remove the functionality, JSS creates Manifest definitions for your new components automatically. However, if you simply create component files, you can add them to the Manifest items using Manifest API instance methods. You can also use Manifest API instance methods to register new route types or other types of items.

You use these methods in manifest definition files located in the sitecore/definitions/ directory. The file name must follow the convention *.sitecore.[js|ts], where the asterisk stands for a component name, such as SearchBox.sitecore.js , or an item type, such as placeholders.sitecore.js.

Manifest API instance methods

The Manifest API provides the following instance methods for registering :

  • addComponent(...components: component[]) - registers a JSS app component definition.

  • addContent(...contents: content[]).

  • addRoute(...routes: route[]) - adds an app route data definition.

  • addRouteType(...routeTypes: template[]) - adds a Sitecore template type for a route.

  • addTemplate(...templates: template[]).

  • addPlaceholder(...templates: template[]) - adds a placeholder definition to the manifest.

Manifest objects

When using Manifest API instance methods to add manifest definitions, your definitions must match the following schemas:

Tip

Using an editor that understands JS typings (such as VS Code) accesses type information within the editor including helpful annotations.

component

{
  id: string:optional,
  name: string:required,
  displayName: string:optional,
  fields: fields:optional,
  params: params:optional,
  placeholders: placeholders:optional, // placeholders exposed by rendering
  allowedPlaceholders: array[string]:optional, // placeholders component is allowed in (normally inferred by route data)
  displayFieldEditorButton: boolean:optional = true,
  fieldEditorFields: array[string]:optional = all fields, // field names
  customExperienceButtons: array[string]:optional, // names or IDs
  insertOptions: array[string]:optional, // template names or IDs
  graphQLQuery: string:optional, // see GraphQL integrated documentation
  // note: while these use the same structure as a route, they do not use placeholders and are not mapped as routes. 
  // This enables adding child items to the datasource.
  children: array[route] 
}

Note

The displayFieldEditorButton and fieldEditorFields properties allow you to control the behavior of the Field Editor button that is automatically added to the component in the Sitecore Experience Editor. This button allows editing all the component data in a pop-up form interface. By default, all components display the button, and all component fields are editable. You do not have to supply these properties if this is the desired behavior.

content

Content data uses the same schema as route data, except that the placeholders property is generally not used as it would have no effect.

field

For the type property, we recommend you use one of the available CommonFieldTypes values.

{
  name: string:required,
  type: string|CommonFieldTypes:required,
  displayName: string:optional,
  required: bool:optional,   // whether the field must have a value entered
  validationPattern: string:optional, // regular expression (C#) to determine value validity
  validationMessage: string:optional, // message shown when validationPattern fails
  standardValue: string:optional, // the default value this field gets when a content editor creates a new item using it
  section: string:optional, // Sitecore template section name
  source: string:optional,  // Sitecore template field source (field-type specific)
  sortOrder: int:optional,  // Template field sort order. Defaults to order defined in JSON.
  storage: string:optional,  // Sitecore field storage: versioned (default), unversioned, shared (DO NOT CHANGE AFTER IMPORTED)
  id: string:optional
}

CommonFieldTypes

{
  SingleLineText: 'Single-Line Text',
  MultiLineText: 'Multi-Line Text',
  RichText: 'Rich Text',
  ContentList: 'Treelist',
  ItemLink: 'Droptree',
  GeneralLink: 'General Link',
  Image: 'Image',
  File: 'File',
  Number: 'Number',
  Checkbox: 'Checkbox',
  Date: 'Date',
  DateTime: 'Datetime',
}

Note

For custom Sitecore field types or other types not in the CommonFieldTypes enumeration, the string of their field type name in Sitecore (that is, Single-Line Text) can be passed. Editors that support type annotations, like VS Code, provide auto-completion on this enum.

param

{
  name: string:required
}

placeholder

{
  name: string:required,
  displayName: string:optional
}

placeholders

{
  placeholderName: array[component]:optional,
  // additional placeholder key/values can be added
}

route

{
  id: string:optional,
  name: string:required,
  displayName: string:optional,
  template: string:optional, // note: this is optional in yaml/json as its defaulted before adding to manifest
  fields: fields:optional,
  children: array[route]:optional,
  placeholders: placeholders:optional,
  insertOptions: array[string]:optional,
}

template

{
  name: string:required,
  displayName: string:optional,
  inherits: array[string]:optional, // names of JSS template(s) to inherit from, OR Sitecore item GUIDs for non-JSS templates
  fields: array[field]:optional,
  icon: string:optional, // e.g. People/16x16/alarmclock.png
  defaultWorkflow: string:optional // e.g. /sitecore/system/Workflows/Sample Workflow
}

fields

{
  fieldName: object[fieldName] = field:required
  // additional field key/values can be added, see the following
}

params

{
  paramName: array[string]:required,
  // additional param key/values can be added
  // note: all param values are provided to the component as strings,
  // even if the defined value is a number/boolean value.
}

imageFieldValue

The image field value is used when a field is an image type. It has additional properties compared to a normal field.

{
  id: string:optional,
  src: string:required,         // src of image. Should be under /sitecore/media on the JSS app.
  alt: string:required,
  displayName: string:optional, // media item display name
  title: string:optional,       // media item field
  keywords: string:optional,    // media item field
  description: string:optional, // media item field
  width: int:optional,
  height: int:optional,
  class: string:optional        // rendered image CSS class

}

linkFieldValue

The link field value is used when a field is a link type. It has additional properties compared to a normal field.

{
  href: string:required,
  text: string:optional,        // link body text
  class: string:optional,       // rendered <a> css class
  target: string:optional,      // target attribute e.g. _blank
  title: string:optional        // title attribute of <a>
}

multilistFieldValue

You can define Sitecore multi-list fields by specifying the item definitions that are selected in the multi-list (as an array), or by using ID references to pull in items defined in a shared content area (or explicit GUIDs to refer to non-app items in Sitecore)

// definition using an array of content items (routes without placeholders)
[route]:required

// complete example including the top level fields (YAML):
fields:
  multilistFieldName:
  - name: Option1
    fields:
      title:
        value: Hello
  - name: Option2
  # ...

// or define it using ID references to shared content items (also YAML):
fields:
  multilistFieldName:
  - id: option-1
  - id: option-2
  # ...

Handling date field values

Date fields' values in the manifest are formatted using ISO 8601 formatted strings, for example, 2012-04-23T18:25:43.511Z.

Note

This is a JavaScript date format and is different from how Sitecore stores date field values internally. Sitecore-formatted dates do not work.

Examples of manifest definitions

When you create JSS applications, the apps already have some manifest definitions. The most common manifest definitions are for registering placeholders and components with Sitecore during app import, but you can also use manifest definitions for other use cases, such as adding fields to routes.

Placeholders

Defining placeholders explicitly in the manifest is optional. Any placeholder name referred to by a route is automatically known by the manifest. However, explicitly registering a placeholder lets you set a placeholder display name for it so that content editors can see something friendlier than appname-content-leftside-upsidedown-2.

An explicit placeholder definition is a line in the /sitecore/definitions/placeholders.sitecore.js file. The .sitecore in the name is mandatory.

For example:

import { addPlaceholder } from '@sitecore-jss/sitecore-jss-manifest';

export default (manifest) => {
  addPlaceholder(manifest, 
    { name: 'appname-main', displayName: 'Main' },
    { name: 'appname-content', displayName: 'Content' });
};

Components

You must define each front-end component added to a route so that JSS can register the component within Sitecore and provide the appropriate infrastructure to give it the necessary content.

Component definitions are conventionally stored in /sitecore/definitions/components/<ComponentName>.sitecore.{js|ts}. For example:

/*
NOTE: if you use an editor, such as VS Code, that reads typing data from imported libraries, you will receive code completion hints for the manifest definitions.
*/
import { addComponent } from '@sitecore-jss/sitecore-jss-manifest';

export default (manifest) => {
  addComponent(manifest, {
    // this name must match the name that is used to add the component to routes,
    // and the name used when the component JS implementation is registered to the componentFactory
    name: 'ConnectedPage',
    // you can use a friendly name for the component to be nice to your authors
    displayName: 'Connected Page',
    // define the content fields, and their data types, that are needed for the component
    fields: [
      { name: 'title', type: manifest.fieldTypes.singleLineText },
      { name: 'text', type: manifest.fieldTypes.richText },
      { name: 'logoImage', type: manifest.fieldTypes.image },
    ],
  });
};

The .sitecore in the name is mandatory.

When you create components with the CLI command jss scaffold <ComponentName>, the scaffolding script, if available in your sample application, generates the component and the manifest definition for you.