Adding Manifest definitions in code-first JSS apps
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:
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]
}
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',
}
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
.
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. Still, 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-dev-tools';
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-dev-tools';
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.