Understand the components.json File and Format

The components.json file is used for themed components. A theme must have a components.json file located at /ThemeName/components.json, which specifies the components used in the theme. This is different from the appInfo.json file, which is used when a component is dropped onto a page and there is no entry in the components.json file. With the components.json file, you could have different themes with different values for the component in each theme. However with the appInfo.json file, there is only one value for a component.

The components.json 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 Management 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 Management.

Name	Type	ID
Title	scs-title	scs-title
Paragraph	scs-paragragh	scs-paragragh
Text	scs-title	scs-text
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
Dynamic List	scs-dynamiclist	scs-dynamiclist
Recommendation	scs-recommendation	scs-recommendation
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 Management. They don’t include registered remote components.

Name	Type	ID
Conversation	scs-app	Conversation
Documents Manager	scs-app	Documents Manager
Project Library	scs-app	Project Library
Conversation List	scs-app	Conversation List
Start Form	scs-app	Start Form
Task List	scs-app	Task List
Task Details	scs-app	Task Details
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.