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.