Understand the components.json File and Format

A theme must have a components.json file located at /ThemeName/components.json, which specifies the components used in the theme.

This file must contain valid JSON, and the minimum that the file must contain is an empty JSON array [].

The components.json file syntax lists all local components and fully supports categorization of components. (Remote components are registered in the Component Catalog.)

No matter what components are added to the theme-level components.json file (including none), Oracle Content and Experience populates a default set of components available to users. This default set is defined in the source code. The following list shows the components and (seeded) components rendered in inline frames. In addition, any remote components registered at the service level and made available to users in your instance will be available in Site Builder.

The following local components are included with Oracle Content and Experience.

Name Type ID

Title

scs-title

scs-title

Paragraph

scs-paragragh

scs-paragragh

Image

scs-image

scs-image

Gallery

scs-gallery

scs-gallery

Gallery Grid

scs-gallerygrid

scs-gallerygrid

Document

scs-document

scs-document

Button

scs-button

scs-button

Map

scs-map

scs-map

Divider

scs-divider

scs-divider

Spacer

scs-spacer

scs-spacer

YouTube

scs-youtube

scs-youtube

Social Bar

scs-socialbar

scs-socialbar

Video

scs-video

scs-video

Article (custom component)

scs-component

scs-comp-article

Headline (custom component)

scs-component

scs-comp-headline

Image and Text (custom component)

scs-component

scs-comp-image-text

These components, rendered in inline frames, are included with Oracle Content and Experience. They don’t include registered remote components.

Name Type ID

Conversation

scs-app

Conversation

Documents Manager

scs-app

Documents Manager

Folder List

scs-app

Folder List

File List

scs-app

File List

Facebook Like

scs-app

Facebook Like

Facebook Recommend

scs-app

Facebook Recommend

Twitter Follow

scs-app

Twitter Follow

Twitter Share

scs-app

Twitter Share

General Format

The general format of the components.json file follows:

  • Properties for components are specified within each component. Top-level "components" or "apps" properties are deprecated.

  • Each component has a "type" property. Components can only have certain values (all possible values are listed in the table for default components).

  • Each component has an "id" property, which must be unique. This property is used to distinguish between components with the same "type". Previously, apps had the "appName" property. While "appName" still works if the "id" property is not available, the "appName" property is deprecated.

  • Each component has a "name" property that is the display name in the user interface. If fallback values are not specified, for components the value is the name of the corresponding default component, and for remote components the value is the ID.

Here is an example of a components.json file:

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                ...
            },
            {
                ...
            },...
        ]
    },
    {
        "name": "My own category name",
        "list": [ ... ]
    }
]

The general structure is a JSON array of category objects. Each category object has a "name" property and "list" property. The "name" property can be a key that maps to a localized String. If these default categories are not sufficient, you can provide your own category name, which won't be localized. The following table lists available default categories and corresponding keys.

Key Category Name (English)

COMP_CONFIG_CONTENT_CATEGORY_NAME

Content

COMP_CONFIG_CUSTOM_CATEGORY_NAME

Custom

COMP_CONFIG_MEDIA_CATEGORY_NAME

Media

COMP_CONFIG_SOCIAL_CATEGORY_NAME

Social

COMP_CONFIG_TEXT_CATEGORY_NAME

Text

The "list" property in each category object contains an array of component objects. Each component or object must have "type" and "id" properties. Other properties are optional.

  • The "type" property must be equal to one of the types found in the default components. If the "type" does not already exist, the component won't be displayed.

  • The "id" property must be unique across components. If the "id" is found to already exist, the component won't be displayed.

  • The "name" property is the display name for the component in the user interface. This replaces the previous "appName" property for apps (now remote components).

  • All other properties are treated the same as in previous releases.

Add New Components to components.json

You are not allowed to modify the default components. However, you can create a new component based on an existing default component. For example, you could create a new component based on the "scs-title" component, which sets some default text. The minimum required to add a new component is to specify the "type" and "id" properties.

  • The "type" must be equal to one of the types found in the default components. If the "type" does not already exist, the component won't be displayed.

  • The "id" must be unique across components. If the "id" is found to already exist, the component won't be displayed.

Here’s an example of code to add a new Title component. This component will display along with the default title component.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline"
            }
        ]
    }
]

Here’s an example of code to add a new Title component with a display name and default text.

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                "initialData": {
                    "userText": "This is a second title component"
                }
            }
        ]
    }
]

Note that the title component takes all the properties of the default Title component as the base, and applies theme-level modifications on top of it to create the new component.

Backwards Compatibility

The components.json files in the previous format can still be read.

  • Files with top-level "components" or "apps" properties.

  • If the file contains an "apps" property, user-defined remote components under this property are still loaded.

  • If the file contains a top-level "apps" property, then assume any remote components listed beneath have type "scs-app".

  • If the "appName" property is present, set "id" to the "appName" value. The display name will be the same as "name", if specified, or falls back on the "id" value.