Dynamic schema library
Contents
API for fetching and manipulating dynamic schemas.
In XP 8 all resource strings passed to and returned from this library are YAML. XML resources are no longer accepted — createSchema, createComponent, createStyles, updateSite, and the update* counterparts all parse YAML only. Examples below use the XP 8 kind: form. |
Functions of this library require the Schema Admin role. It means that user role in the current context may lack sufficient permissions, for example when executed from inside a service - in this case you must explicitly execute the function in the context of system.schema.admin role. |
Usage
Add the following to your build.gradle file:
dependencies {
include xplibs.schema
}
Add the import statement to your code:
import schemaLib from '/lib/xp/schema';
You are now ready to use the API.
Functions
getSchema
Fetches a schema from an application.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Schema) Property object of the fetched schema, or null if the schema does not exist.
Example
import {getSchema} from '/lib/xp/schema';
const result = getSchema({
name: 'myapp:mytype',
type: 'CONTENT_TYPE'
});
const expected = {
name: "myapp:mytype",
title: "Tag",
titleI18nKey: "",
createdTime: "2021-09-25T10:00:00Z",
creator: "user:system:anonymous",
modifiedTime: "2021-09-25T10:00:00Z",
"resource" : <!-- resource string value -->,
type: "CONTENT_TYPE",
icon: {
data: {},
mimeType: "image/png",
modifiedTime: "2016-01-01T12:00:00Z"
},
form: [
{
formItemType: "Input",
name: "tag",
label: "Tag, unlimited occurrences",
maximize: true,
inputType: "Tag",
occurrences: {
maximum: 0,
minimum: 0
},
config: {}
}
],
config: {}
};
listSchemas
Fetches schemas of a particular type from an application.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object[] : (Schema[]) Property object of the fetched schemas.
Example
import {listSchemas} from '/lib/xp/schema';
const result = listSchemas({
application: 'myapp',
type: 'CONTENT_TYPE'
});
const expected = {
name: 'myapp:type1',
title: 'My type display name',
description: 'My type description',
modifiedTime: '2010-01-01T10:00:00Z',
resource: 'kind: "ContentType"\ntitle: "My type display name"\nform: []\n',
type: 'CONTENT_TYPE',
form: [
{
formItemType: 'Layout',
name: 'myLayout',
label: 'My layout',
items: [
{
formItemType: 'ItemSet',
name: 'mySet',
occurrences: {
maximum: 1,
minimum: 1
},
items: [
{
formItemType: 'Input',
name: 'myInput',
label: 'Input',
maximize: true,
inputType: 'TextLine',
occurrences: {
maximum: 1,
minimum: 0
},
config: {}
}
]
}
]
}
],
config: {}
},
{
name: 'myapp:type2',
title: 'My type display name 2',
description: 'My type description 2',
modifiedTime: '2012-01-01T10:00:00Z',
resource: 'kind: "ContentType"\ntitle: "My type display name 2"\nform: []\n',
type: 'CONTENT_TYPE',
form: [],
config: {}
};
createSchema
Creates a dynamic schema in a virtual application.
Parameters
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Schema) Property object of the created dynamic schema.
Example
import {createSchema} from '/lib/xp/schema';
const resource = `kind: "ContentType"
title: "Tag"
superType: "base:structured"
form:
- type: "Tag"
name: "tag"
label: "Tag, unlimited occurrences"
occurrences:
min: 0
max: 0
`;
const result = createSchema({
name: 'myapp:mytype',
type: 'CONTENT_TYPE',
resource
});
const expected = {
name: "myapp:mytype",
title: "Tag",
titleI18nKey: "",
createdTime: "2021-09-25T10:00:00Z",
creator: "user:system:anonymous",
modifiedTime: "2021-09-25T10:00:00Z",
"resource" : <!-- resource string value -->,
type: "CONTENT_TYPE",
icon: {
data: {},
mimeType: "image/png",
modifiedTime: "2016-01-01T12:00:00Z"
},
form: [
{
formItemType: "Input",
name: "tag",
label: "Tag, unlimited occurrences",
maximize: true,
inputType: "Tag",
occurrences: {
maximum: 0,
minimum: 0
},
config: {}
}
],
config: {}
};
updateSchema
Updates a dynamic schema in a virtual application.
Parameters
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Schema) Property object for the modified dynamic schema.
Example
import {updateSchema} from '/lib/xp/schema';
const resource = `kind: "Mixin"
title: "Virtual Mixin"
description: "Mixin description"
form:
- type: "TextLine"
name: "text2"
label: "Text 2"
- include: "myapplication:inline"
`;
const result = updateSchema({
name: 'myapp:mytype',
type: 'MIXIN',
resource
});
const expected = {
name: 'myapp:mytype',
title: 'Virtual Mixin',
titleI18nKey: '',
description: 'Mixin description',
descriptionI18nKey: '',
createdTime: '2021-09-25T10:00:00Z',
modifiedTime: '2021-09-25T10:00:00Z',
resource: <!-- resource string value -->,
type: 'MIXIN',
form: [
{
formItemType: 'Input',
name: 'text2',
label: 'Text 2',
maximize: true,
inputType: 'TextLine',
occurrences: {
maximum: 1,
minimum: 0
},
config: {}
},
{
formItemType: 'InlineMixin',
name: 'myapplication:inline'
}
]
};
deleteSchema
Removes a schema from a virtual application.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
boolean : true if deletion was successful.
Example
import {deleteSchema} from '/lib/xp/schema';
const result = deleteSchema({
name: 'myapp:mytype',
type: 'MIXIN'
});
if (result) {
log.info('Deleted mixin: [myapp:mytype]');
} else {
log.info('Mixin deletion failed: [myapp:mytype]');
}
getComponent
Fetches a component from an application.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Component) Property object of the fetched component.
Example
import {getComponent} from '/lib/xp/schema';
const result = getComponent({
key: 'myapp:mypage',
type: 'PAGE'
});
const expected = {
key: 'myapp:mypage',
title: 'News page',
description: 'My news page',
descriptionI18nKey: 'key.description',
componentPath: 'myapp:/cms/pages/mypage',
modifiedTime: '2021-02-25T10:44:33.170079900Z',
resource: 'kind: "Page"\ntitle: "News page"\nform: []\nregions:\n- "region-one"\n',
type: 'PAGE',
form: [
{
formItemType: 'Input',
name: 'width',
label: 'width',
maximize: true,
inputType: 'Double',
occurrences: {
maximum: 1,
minimum: 0
},
config: {}
}
],
config: {},
regions: [
'region-one'
]
};
listComponents
Fetches components of a particular type from an application.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object[] : (Component[]) Array of Property objects of the fetched components.
Example
import {listComponents} from '/lib/xp/schema';
const result = listComponents({
application: 'myapp',
type: 'PART'
});
const expected = [
{
key: 'myapp:part1',
title: 'News part',
description: 'My news part',
descriptionI18nKey: 'key.description',
componentPath: 'myapp:/cms/parts/part1',
modifiedTime: '2021-02-25T10:44:33.170079900Z',
resource: 'kind: "Part"\ntitle: "News part"\nform: []\n',
type: 'PART',
form: [
{
formItemType: 'Input',
name: 'width',
label: 'width',
maximize: true,
inputType: 'Double',
occurrences: {
maximum: 1,
minimum: 0
},
config: {}
}
],
config: {}
},
{
key: 'myapp:part2',
title: 'Other part',
componentPath: 'myapp:/cms/parts/part2',
modifiedTime: '2022-02-25T10:44:33.170079900Z',
resource: 'kind: "Part"\ntitle: "Other part"\nform: []\n',
type: 'PART',
form: [],
config: {}
}
];
createComponent
Creates a dynamic component in a virtual application.
Parameters
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Component) Property object of the created dynamic component.
Example
import {createComponent} from '/lib/xp/schema';
const resource = `kind: "Part"
title: "Virtual Part"
description: "My Part Description"
form:
- type: "Double"
name: "width"
label: "Column width"
occurrences:
min: 0
max: 1
- include: "myapplication:link-urls"
`;
const result = createComponent({
key: 'myapp:mypart',
type: 'PART',
resource
});
const expected = {
key: 'myapp:mypart',
title: 'Virtual Part',
titleI18nKey: 'key.display-name',
description: 'My Part Description',
descriptionI18nKey: 'key.description',
componentPath: 'myapp:/cms/parts/mypart',
modifiedTime: '2021-09-25T10:00:00Z',
resource: <!-- resource string value -->,
type: 'PART',
form: [
{
formItemType: 'Input',
name: 'width',
label: 'Column width',
helpText: 'key.help-text',
maximize: true,
inputType: 'Double',
occurrences: {
maximum: 1,
minimum: 0
},
config: {}
},
{
formItemType: 'InlineMixin',
name: 'myapplication:link-urls'
}
],
config: {
input: [{
value: '', '@name': 'width', '@type': 'Double'
}]
}
};
updateComponent
Updates a dynamic component in a virtual application.
Parameters
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Component) Property object of the modified dynamic component.
Example
import {updateComponent} from '/lib/xp/schema';
const resource = `kind: "Layout"
title: "Virtual Layout"
description: "My Layout Description"
form:
- type: "Double"
name: "pause"
label: "Pause parameter"
occurrences:
min: 0
max: 1
- type: "ItemSet"
name: "myFormItemSet"
label: "My form item set"
occurrences:
min: 0
max: 1
items:
- type: "TextLine"
name: "myTextLine"
label: "My text line"
occurrences:
min: 1
max: 1
- type: "TextLine"
name: "myCustomInput"
label: "My custom input"
occurrences:
min: 0
max: 1
regions:
- "header"
- "main"
- "footer"
`;
const result = updateComponent({
key: 'myapp:mylayout',
type: 'LAYOUT',
resource
});
const expected = {
key: 'myapp:mylayout',
title: 'Virtual Layout',
titleI18nKey: 'key.display-name',
description: 'My Layout Description',
descriptionI18nKey: 'key.description',
componentPath: 'myapp:/cms/layouts/mylayout',
modifiedTime: '2021-09-25T10:00:00Z',
resource: <!-- resource string value -->,
type: 'LAYOUT',
form: [
{
formItemType: 'Input',
name: 'pause',
label: 'Pause parameter',
helpText: 'key1.help-text',
maximize: true,
inputType: 'Double',
occurrences: {
maximum: 1,
minimum: 0
},
config: {}
},
{
formItemType: 'ItemSet',
name: 'myFormItemSet',
label: 'My form item set',
occurrences: {
maximum: 1,
minimum: 0
},
items: [
{
formItemType: 'Input',
name: 'myTextLine',
label: 'My text line',
maximize: true,
inputType: 'TextLine',
occurrences: {
maximum: 1,
minimum: 1
},
config: {}
},
{
formItemType: 'Input',
name: 'myCustomInput',
label: 'My custom input',
maximize: true,
inputType: 'TextLine',
occurrences: {
maximum: 1,
minimum: 0
},
config: {}
}
]
}
],
config: {},
regions: [
'header',
'main',
'footer'
]
};
deleteComponent
Deletes a dynamic component from a virtual application.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
boolean : true if deletion was successful.
Example
import {deleteComponent} from '/lib/xp/schema';
const result = deleteComponent({
key: 'myapp:mylayout',
type: 'LAYOUT'
});
if (result) {
log.info('Deleted layout: [myapp:mylayout]');
} else {
log.info('Layout deletion failed: [myapp:mylayout]');
}
getStyles
Fetches styles (f.ex. image styles) from an application.
Parameters
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Styles) Property object of the fetched styles, or null if the application has no styles descriptor.
Example
import {getStyles} from '/lib/xp/schema';
const result = getStyles({
application: 'myapp'
});
const expected = {
application: 'myapp',
modifiedTime: '2021-02-25T10:44:33.170079900Z',
resource: 'kind: "Style"\nstyles: []\n',
elements: [
{
label: 'Style display name',
name: 'mystyle'
}
]
};
createStyles
Creates styles in a virtual application.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Styles) Property object of the created dynamic styles.
Example
import {createStyles} from '/lib/xp/schema';
const resource = `kind: "Style"
styles:
- name: "warning"
type: "Style"
label: "Warning"
editor:
css: |
.warning { /* CSS selectors */ }
- name: "editor-width-auto"
type: "Image"
label: "Override \${width}"
editor:
css: |
.editor-width-auto { /* CSS selectors */ }
- name: "editor-style-cinema"
type: "Image"
label: "Cinema"
aspectRatio: "21:9"
filter: "pixelate(10)"
editor:
css: |
.editor-style-cinema { /* CSS selectors */ }
`;
const result = createStyles({
application: 'myapp',
resource
});
const expected = {
application: 'myapp',
modifiedTime: '2021-09-25T10:00:00Z',
resource: <!-- resource string value -->,
elements: [
{
label: 'Warning',
name: 'warning'
},
{
label: 'Override ${width}',
name: 'editor-width-auto'
},
{
label: 'Cinema',
name: 'editor-style-cinema'
}
]
};
updateStyles
Updates styles in a virtual application.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Styles) Property object with the modified styles.
Example
import {updateStyles} from '/lib/xp/schema';
const resource = `kind: "Style"
styles:
- name: "warning"
type: "Style"
label: "Warning"
editor:
css: |
.warning { /* CSS selectors */ }
- name: "editor-width-auto"
type: "Image"
label: "Override \${width}"
editor:
css: |
.editor-width-auto { /* CSS selectors */ }
- name: "editor-style-cinema"
type: "Image"
label: "Cinema"
aspectRatio: "21:9"
filter: "pixelate(10)"
editor:
css: |
.editor-style-cinema { /* CSS selectors */ }
`;
const result = updateStyles({
application: 'myapp',
resource
});
const expected = {
application: 'myapp',
modifiedTime: '2021-09-25T10:00:00Z',
resource: <!-- resource string value -->,
elements: [
{
label: 'Warning',
name: 'warning'
},
{
label: 'Override ${width}',
name: 'editor-width-auto'
},
{
label: 'Cinema',
name: 'editor-style-cinema'
}
]
};
deleteStyles
Deletes styles from a virtual application.
Parameters
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
boolean : true if deletion was successful.
Example
import {deleteStyles} from '/lib/xp/schema';
const result = deleteStyles({
application: 'myapp'
});
if (result) {
log.info('Styles were deleted: [myapp]');
} else {
log.info('Styles deletion failed: [myapp]');
}
getSite
Fetches a site descriptor from an application.
Parameters
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Site) Property object of the fetched site descriptor, or null if the application has no CMS descriptor.
Example
import {getSite} from '/lib/xp/schema';
const result = getSite({
application: 'myapp'
});
const expected = {
application: 'myapp',
resource: <!-- resource string value -->,
modifiedTime: '2021-02-25T10:44:33.170079900Z',
form: [
{
formItemType: 'Input',
name: 'input',
label: 'Input',
maximize: true,
inputType: 'Double',
occurrences: {
maximum: 1,
minimum: 0
},
config: {}
}
],
mixinMappings: [
{
name: 'myapplication:my',
optional: false
}
]
};
updateSite
Updates dynamic site descriptor in a virtual application.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Site) Property object of the modified site descriptor.
Example
import {updateSite} from '/lib/xp/schema';
const resource = `kind: "CMS"
mixins:
- name: "myapp1:menu-item"
optional: false
- name: "myapp2:my-meta-mixin"
optional: false
form:
- type: "TextLine"
name: "some-name"
label: "Textline"
occurrences:
min: 0
max: 1
`;
const result = updateSite({
application: 'myapp',
resource
});
Despite its name, updateSite writes the CMS descriptor (cms/cms.yaml) which holds the site form and mixin references. The site descriptor (cms/site.yaml) — which carries processors, mappings, and apis — is not modifiable through this library; manage it as part of the application source. |
const expected = {
application: 'myapp',
modifiedTime: '2021-09-25T10:00:00Z',
resource: <!-- resource string value -->,
form: [
{
formItemType: 'Input',
name: 'some-name',
label: 'Textline',
customText: '',
maximize: true,
inputType: 'TextLine',
occurrences: {
maximum: 1,
minimum: 0
},
config: {}
}
],
mixinMappings: [
{
name: 'myapp1:menu-item',
optional: false,
allowContentTypes: ''
},
{
name: 'myapp2:my-meta-mixin',
optional: false,
allowContentTypes: ''
}
]
};
Type Definitions
Schema
(abstract for ContentType, FormFragment and Mixin)
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
name |
string |
Component name |
|
title |
string |
Title |
|
titleI18nKey |
string |
Title i18n key |
|
description |
string |
Schema description |
|
descriptionI18nKey |
string |
Schema description i18n key |
|
createdTime |
string |
Created zulu time |
|
creator |
string |
Creator principal key |
|
modifiedTime |
string |
Modified zulu time |
|
modifier |
string |
Modifier principal key |
|
resource |
string |
Schema resource value |
|
type |
string |
Schema type ( |
|
form |
object[] |
Schema form |
|
icon |
Schema icon |
ContentType
(extends Schema)
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
config |
object |
Content type config |
Mixin
(extends Schema)
Each mixin attaches optional metadata to a content item.
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
config |
object |
Mixin config |
Component
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
key |
string |
Component key |
|
title |
string |
Title |
|
titleI18nKey |
string |
Title i18n key |
|
description |
string |
Component description |
|
descriptionI18nKey |
string |
Component description i18n key |
|
componentPath |
string |
Component path |
|
modifiedTime |
string |
Modified zulu time |
|
resource |
string |
Component resource value |
|
type |
string |
Component type( |
|
form |
object[] |
Component form |
|
config |
object |
Component config |
Layout
(extends Component)
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
regions |
string[] |
Layout regions |
Site
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
application |
string |
Application key |
|
modifiedTime |
string |
Site zulu modified time |
|
resource |
string |
Site CMS descriptor YAML resource value |
|
form |
object[] |
Site descriptor form |
|
mixinMappings |
Mixin mappings |
Styles
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
application |
string |
Application key |
|
modifiedTime |
string |
Styles zulu modified time |
|
resource |
string |
Styles YAML resource value |
|
elements |
style elements |
MixinMapping
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
name |
string |
Mixin name |
|
optional |
boolean |
|
|
allowContentTypes |
string |
Allowed content type pattern |
StyleElement
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
name |
string |
Style element name |
|
label |
string |
Style element label |
Icon
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
data |
object |
icon stream data |
|
mimeType |
string |
icon mime type |
|
modifiedTime |
string |
icon modified time |