Content Project Library
Contents
This library has been introduced in XP 7.3.0. |
This library contains functions for management of Content Projects.
Usage
Add the following dependency to your build.gradle
file:
dependencies {
include "com.enonic.xp:lib-project:${xpVersion}"
}
In your JavaScript controller, add a require
statement:
const projectLib = require('/lib/xp/project');
Functions
addPermissions
Adds permissions to an existing Content Project. To modify permissions, user must have Owner
permissions for the project, or either system.admin
or cms.admin
role.
You can read about project permissions in the dedicated Content Projects section |
Parameters
Name | Kind | Details |
---|---|---|
id |
string |
Unique project id to identify the project. |
permissions |
Object.<string, string[]> |
Project permissions to add. 1 to 5 properties where key is role id and value is an array of principals. |
Returns
Object : All current project permissions.
Example
var projectLib = require('/lib/xp/project');
var currentPermissions = projectLib.addPermissions({
id: 'my-project',
permissions: {
owner: ['user:mystore:user1', 'user:mystore:user2'],
editor: ['user:mystore:user3']
}
});
{
'id': 'my-project',
'permissions': {
'owner': [
'user:mystore:user1',
'user:mystore:user2'
],
'editor': [
'user:mystore:user3'
]
}
}
create
Creates a new Content Project. Only system.admin
and cms.admin
roles have permissions to create new projects.
Parameters
Name |
Type |
Attributes |
Description |
|||||||||
id |
string |
Unique project id (alpha-numeric characters and hyphens allowed). |
||||||||||
displayName |
string |
Project display name. |
||||||||||
parent |
string |
<optional> |
Parent project id. If provided, the new project will be a Content Layer that automatically inherits changes from the parent project. |
|||||||||
description |
string |
<optional> |
Project description. |
|||||||||
language |
string |
<optional> |
Default project language. |
|||||||||
siteConfig |
Object.<string, Object>[] |
<optional> |
Applications (with optional configurations) to be assigned to the project
|
|||||||||
permissions |
Object.<string, string[]> |
<optional> |
Project permissions. 1 to 5 properties where key is role id and value is an array of principals.
|
|||||||||
readAccess |
Object.<string, boolean> |
Read access settings.
|
Returns
Object : Project object.
Example
var projectLib = require('/lib/xp/project');
try {
var project = projectLib.create({
id: 'my-project',
displayName: 'My Content Project',
readAccess: {
public: true
}
});
} catch (e) {
log.error('Failed to create a project: ' + e);
}
{
'id': 'my-project',
'displayName': 'My Content Project',
'permissions': [],
'readAccess': {
'public': true
}
}
var projectLib = require('/lib/xp/project');
var project = projectLib.create({
id: 'my-project',
displayName: 'My Content Project',
description: 'Some exciting content is stored here',
language: 'no',
permissions: {
owner: ['user:mystore:user1'],
editor: ['user:mystore:user2'],
author: ['user:mystore:user3'],
contributor: ['user:mystore:user4'],
viewer: ['user:mystore:user5']
},
siteConfig: [{
applicationKey: 'app1',
config: {
a: 'b'
}
} ,{
applicationKey: 'app2',
config: {
a: true,
b: 3.4
}
}],
readAccess: {
public: false
}
});
{
'id': 'my-project',
'displayName': 'My Content Project',
'description': 'Some exciting content is stored here',
'language': 'no',
'siteConfig': [
{
'applicationKey': 'app1',
'config': {
'a': 'b'
}
},
{
'applicationKey': 'app2',
'config': {
'a': true,
'b': 3.4
}
}
],
'permissions': {
'owner': [
'user:mystore:user1'
],
'editor': [
'user:mystore:user2'
],
'author': [
'user:mystore:user3'
],
'contributor': [
'user:mystore:user4'
],
'viewer': [
'user:mystore:user5'
]
},
'readAccess': {
'public': false
}
}
delete
Deletes an existing Content Project and the project repository along with all the data inside. To delete a project, user must have either system.admin
or cms.admin
role.
Parameters
Name | Kind | Details |
---|---|---|
id |
string |
Unique project id to identify the project. |
Returns
boolean : true
if the project is successfully deleted.
Example
var projectLib = require('/lib/xp/project');
var result = projectLib.delete({
id: 'my-project'
});
true
get
Returns an existing Content Project. To get a project, user must have permissions for this project, or either system.admin
or cms.admin
role.
Parameters
Name | Kind | Details |
---|---|---|
id |
string |
Unique project id to identify the project. |
Returns
Object : Content Project object or null
if not found.
Example
var projectLib = require('/lib/xp/project');
var project = projectLib.get({
id: 'my-project'
});
{
'id': 'my-project',
'displayName': 'My Content Project',
'permissions': {
'owner': [
'user:mystore:user1'
],
'editor': [
'user:mystore:user2'
]
},
'readAccess': {
'public': true
}
}
list
Returns all Content Projects that user in the current context has permissions for. Users with system.admin
or cms.admin
roles will get the list of all projects.
Returns
Object[] : Array of Content Project objects.
Example
var projectLib = require('/lib/xp/project');
var projects = projectLib.list();
[{
'id': 'default',
'displayName': 'Default',
'description': 'Default project'
},
{
'id': 'my-project',
'displayName': 'My Content Project',
'permissions': [],
'readAccess': {
'public': true
}
}]
modify
Modifies an existing Content Project. To modify a project, user must have Owner
permissions for this project, or either system.admin
or cms.admin
role.
Parameters
Name | Type | Attributes | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
id |
string |
Unique project id (alpha-numeric characters and hyphens allowed). |
||||||||||
displayName |
string |
<optional> |
Project display name. |
|||||||||
description |
string |
<optional> |
Project description. |
|||||||||
language |
string |
<optional> |
Default project language. |
|||||||||
siteConfig |
Object.<string, Object>[] |
<optional> |
Applications (with optional configurations) to be assigned to the project.
|
Returns
Object : Modified project object.
Example
var projectLib = require('/lib/xp/project');
var project = projectLib.modify({
id: 'my-project',
displayName: 'New project name',
description: 'New project description',
language: 'en',
siteConfig: [{
applicationKey: 'app1',
config: {
a: 'b'
}
} ,{
applicationKey: 'app2',
config: {
a: true,
b: 3.4
}
}],
});
{
'id': 'my-project',
'displayName': 'New project name',
'description': 'New project description',
'language': 'en',
'siteConfig': [
{
'applicationKey': 'app1',
'config': {
'a': 'b'
}
},
{
'applicationKey': 'app2',
'config': {
'a': true,
'b': 3.4
}
}
],
'permissions': {},
'readAccess': {
'public': true
}
}
modifyReadAccess
Toggles public/private READ access for an existing Content Project. This will modify permissions on ALL the content items inside the project repository by adding or removing READ access for system.everyone
. To modify READ access, user must have Owner
permissions for the project, or either system.admin
or cms.admin
role.
Parameters
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
id |
string |
Unique project id (alpha-numeric characters and hyphens allowed). |
||||||
readAccess |
Object.<string, boolean> |
Read access settings.
|
Returns
Object : Current state of public READ access.
Example
var projectLib = require('/lib/xp/project');
var currentPermissions = projectLib.addPermissions({
id: 'my-project',
readAccess: {
public: false
}
});
{
'id': 'my-project',
'readAccess': {
'public': false
}
}
removePermissions
Removes permissions from an existing Content Project. To remove permissions, user must have Owner
permissions for the project, or either system.admin
or cms.admin
role.
Parameters
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
id |
string |
Unique project id (alpha-numeric characters and hyphens allowed). |
|||||||||
permissions |
Object.<string, string[]> |
Project permissions to delete. 1 to 5 properties where key is role id and value is an array of principals.
|
Returns
Object : All current project permissions.
var projectLib = require('/lib/xp/project');
projectLib.addPermissions({
id: 'my-project',
permissions: {
owner: ['user:mystore:user1', 'user:mystore:user2'],
editor: ['user:mystore:user3']
}
});
var currentPermissions = projectLib.removePermissions({
id: 'my-project',
permissions: {
owner: ['user:mystore:user2']
}
});
{
'id': 'my-project',
'permissions': {
'owner': [
'user:mystore:user1'
],
'editor': [
'user:mystore:user3'
]
}
}
getAvailableApplications
Returns available applications of a specified project. The result contains active apps assigned to the project and all of its parents, if any.
Parameters
Name | Kind | Details |
---|---|---|
id |
string |
Unique project id to identify the project. |
Returns
string[] : Application keys.
Example
var projectLib = require('/lib/xp/project');
var project = projectLib.getAvailableApplications({
id: 'my-project'
});
['app1', 'app2']