Context Library

Contents

Context Library

This library contains functions to get, query and manipulate nodes.

Usage

Add the following into your build.gradle file:

dependencies {
  include 'com.enonic.xp:lib-node:${xpVersion}
}

In your JavaScript controller, add a require statement:

const contextLib = require('/lib/xp/node');

You are now free to use the library functionality.

Functions

connect

Creates a connection to a repository with a given branch and authentication info.

Parameters

Name Kind Details

params

Source

object with paramters

Returns

RepoConnection : A new connection to the repository

Example

A sample function that will return a RepoConnection:
var connect = function () {
    return nodeLib.connect({
        repoId: testRepoId,
        branch: 'master'
    });
};

multiRepoConnect

Creates a connection to several repositories with a given branch and authentication info.

Parameters

Name Kind Details

sources

Array.Source

array of repository source objects

Returns

MultiRepoConnection : A new connection object for all connected repositories.

Example

Connect to repo 'myRepo', branch 'master'.
var searchConnection = nodeLib.multiRepoConnect({
    sources: [
        {
            repoId: 'my-repo',
            branch: 'myBranch',
            principals: ["role:system.admin"]
        },
        {
            repoId: 'my-other-repo',
            branch: 'master',
            principals: ["role:system.admin"]
        }
    ]
});

Objects

MultiRepoConnection

A MultiRepoConnection makes it possible to search across multiple repositories. The object has only one method: query.

query

This command queries nodes in a multi-repo connection.

Parameters

An object with the following keys and their value:

Name Kind Details

start

number

Optional start index used for paging - default: 0

count

number

Optional number of content to fetch, used for paging - default: 10

query

string

Query expression

filters

object

Optional query filters

sort

string

Optional sorting expression - default: '_score DESC'

aggregations

string

Optional aggregations expression

explain

boolean

If set to true, score calculation explanation will be included in result.

Returns

object : Result of query

Example

Query multi-repo connection
var result = multiRepoConnection.query({
    start: 0,
    count: 2,
    query: "startTime > instant('2016-10-11T14:38:54.454Z')",
    filters: {
        boolean: {
            must: {
                exists: {
                    field: "modifiedTime"
                }
            },
            mustNot: {
                hasValue: {
                    field: "myField",
                    values: [
                        "cheese",
                        "fish",
                        "onion"
                    ]
                }
            }
        },
        notExists: {
            field: "unwantedField"
        },
        ids: {
            values: ["id1", "id2"]
        }
    }
});
Sample response
{
    total: 12902,
    count: 2,
    hits: [
        {
            id: "b186d24f-ac38-42ca-a6db-1c1bda6c6c26",
            score: 1.2300000190734863,
            repoId: "my-repo",
            branch: "master"
        },
        {
            id: "350ba4a6-589c-498b-8af0-f183850e1120",
            score: 1.399999976158142,
            repoId: "com.enonic.cms.default",
            branch: "draft"
        }
    ]
}

RepoConnection

A single repo connections with lots of methods to work on the repo:

All the examples below are using a repo connection to execute the functions. The repo connection can be created like this:

Connecting to a repo.
var repo = nodeLib.connect({
    repoId: "com.enonic.cms.default",
    branch: "master"
});

commit

Commits the active version of nodes.

Parameters

Name Kind Details

keys

string | Array.<string>

Node keys to commit. Each argument could be an id, a path or an array of the two. Prefer the usage of ID rather than paths.

message

string

Optional commit message

Returns

object : Commit object(s)

Example

Committing a node.
var result1 = repo.commit({keys: 'nodeId'});
Sample response
{
    "id": "aa1f76bf-4bb9-41be-b166-03561c1555b2",
    "message": "",
    "committer": "user:system:anonymous",
    "timestamp": "2019-01-24T15:16:36.260799Z"
}
Committing nodes.
var result2 = repo.commit({
    keys: ['nodeId', 'nodeId2'],
    message: 'Commit message'
});
Sample response
{
    {
        id: "aa1f76bf-4bb9-41be-b166-03561c1555b2",
        message: "Commit message",
        committer: "user:system:anonymous",
        timestamp: "2019-01-24T15:19:30.818029Z"
    },
    {
        id: "5c15b187-e3ab-4d87-88b2-ffb84bd1c7bb",
        message: "Commit message",
        committer: "user:system:anonymous",
        timestamp: "2019-01-24T15:19:30.818029Z"
    }
}

create

Creating a node. To create a content where the name is not important and there could be multiple instances under the same parent content, skip the name parameter and specify a displayName.

Parameters

An object with the following keys and their value:

Name Type Attributes Details

_name

string

<optional>

Name of content.

_parentPath

string

<optional>

Path to place content under.

_indexConfig

object

<optional>

How the document should be indexed. A default value "byType" will be set if no value specified.

_permissions

object

<optional>

The access control list for the node. By default the creator will have full access

_inheritsPermissions

boolean

<optional>

 true if the permissions should be inherited from the node parent. Default is false.

_manualOrderValue

number

<optional>

 Value used to order document when ordering by parent and child-order is set to manual

_childOrder

string

<optional>

Default ordering of children when doing getChildren if no order is given in query

Returns

object : Created object

Example

Create a node on a repo connection:
var result1 = repo.create({
    _name: "nerd",
    displayName: "Carpenter and IT expert",
    likes: "Plywood",
    numberOfUselessGadgets: 123
});
Sample response
{
    _id: "3eb6b282-94d1-4587-b85d-92e41cc1eee5",
    _name: "nerd",
    _path: "/nerd",
    _childOrder: "_ts DESC",
    _indexConfig: {
        default: {
            decideByType: false,
            enabled: true,
            nGram: false,
            fulltext: false,
            includeInAllText: false,
            path: false,
            indexValueProcessors: [],
            languages: []
        },
        configs: [
            {
                path: "displayName",
                config: {
                    decideByType: false,
                    enabled: true,
                    nGram: true,
                    fulltext: true,
                    includeInAllText: true,
                    path: false,
                    indexValueProcessors: [],
                    languages: []
                }
            }
        ]
    },
    _inheritsPermissions: false,
    _permissions: [
        {
            principal: "user:system:anonymous",
            allow: [
                "READ"
            ],
            deny: []
        },
        {
            principal: "role:admin",
            allow: [
                "READ",
                "CREATE",
                "MODIFY",
                "DELETE",
                "PUBLISH",
                "READ_PERMISSIONS",
                "WRITE_PERMISSIONS"
            ],
            deny: []
        }
    ],
    _state: "DEFAULT",
    _nodeType: "default",
    _versionKey: "30070ec1-0426-4153-b3a7-f78574c6978a",
    _ts: "2019-04-30T11:40:45.371Z",
    displayName: "Carpenter and IT expert",
    likes: "Plywood",
    numberOfUselessGadgets: 123
    }
}

delete

Deleting a node or nodes.

Parameters

Name Kind Details

keys

string | Array.<string>

Node keys to commit. Each argument could be an id, a path or an array of the two. Prefer the usage of ID rather than paths.

Returns

Array.<string> : The list of keys that were actually deleted.

Example

Deleting nodes
var result = repo.delete('nodeId', '/node2-path', 'missingNodeId');
Sample response
[
    "7b175b63-b012-4f20-b31d-b8f78420d7f1",
    "69f225a1-e775-4845-89f0-29b808a9a659"
]

diff

Resolves the differences for a node between current and given branch.

Parameters

An object with the following keys and their value:

Name Type Attributes Details

key

string

Path or id to resolve diff for

target

string

Branch to differentiate with

includeChildren

boolean

optional

If set to true, differences are resolved for all children.

Returns

object : An array with differences in the status for each node in the tree that has differences between the branches.

Example

Comparing draft and master branch
var result = repo.diff({
                     key: '/my-name',
                     target: 'draft',
                     includeChildren: true
                 });
Sample response
{
    diff: [
        {
            id: "c8121875-a9b7-42e4-acf2-75cb52687ddb", (1)
            status: "NEWER"
        }
    ]
}
1 There are 2 children, but only one has been changed

findChildren

Fetch the children of a node.

Parameters

An object with the following keys and their value:

Name Type Attributes Details

parentKey

string

Path or ID of parent to get children of

start

number

optional

start index used for paging - default: 0

count

number

optional

number of content to fetch, used for paging - default: 10

childOrder

string

optional

How to order the children - default is value stored on parent

countOnly

boolean

optional

Optimize for count children only - default is false

recursive

boolean

optional

Do recursive fetching of all children of children - default is false

Returns

object : An object with stats about the result and an array with all IDs of the children.

Example

Comparing draft and master branch
var result = repo.findChildren({
                     parentKey: "/my-name"
                 });
Sample response
{
    "total": 2,
    "count": 10,
    "hits": [
        {
            "id": "c8121875-a9b7-42e4-acf2-75cb52687ddb"
        },
        {
            "id": "636a616b-c8e4-480c-afa9-be88a737cf52"
        }
    ]
}

findVersions

Fetch the versions of a node.

Parameters

An object with the following keys and their value:

Name Type Attributes Details

parentKey

string

Path or ID of parent to get children of

start

number

optional

start index used for paging - default: 0

count

number

optional

number of content to fetch, used for paging - default: 10

Returns

object : An object with stats about the result and an array listing the versions

Example

Comparing draft and master branch
var result = repo.findVersions({
                    key: '/my-name'
                });
Sample response
{
    "total": 2,
    "count": 2,
    "hits": [
        {
            "versionId": "72dcd8c1-9d70-444d-ad7a-508d8c1865a0",
            "nodeId": "ddd1c933-0725-45e8-9a54-a3dd87193f60",
            "nodePath": "/my-name",
            "timestamp": "2019-05-13T15:56:17.018Z"
        },
        {
            "versionId": "04c6b8d7-3c56-458f-80c9-c6ee551fc21d",
            "nodeId": "ddd1c933-0725-45e8-9a54-a3dd87193f60",
            "nodePath": "/my-name",
            "timestamp": "2019-05-13T15:56:16.995Z"
        }
    ]
}

get

Fetches specific nodes by path or ID.

Parameters

Name Kind Details

keys

string | Array.<string>

The keys of the nodes to fetch. Each argument may be an ID, a key or an array of the two.

Returns

Array.<object> : The list of nodes

Example

Fetching nodes
var allFamily = repo.get(family._id, [child1._id, child2._id]);
Sample response
[
    {
        "_id": "8e0b652d-dd9a-401e-897d-14c4314009fc",
        "_name": "family",
        "_path": "/family",
        "_childOrder": "_ts DESC",
        "_indexConfig": {
            "default": {
                "decideByType": false,
                "enabled": true,
                "nGram": false,
                "fulltext": false,
                "includeInAllText": false,
                "path": false,
                "indexValueProcessors": [],
                "languages": []
            },
            "configs": [
                {
                    "path": "displayName",
                    "config": {
                        "decideByType": false,
                        "enabled": true,
                        "nGram": true,
                        "fulltext": true,
                        "includeInAllText": true,
                        "path": false,
                        "indexValueProcessors": [],
                        "languages": []
                    }
                }
            ]
        },
        "_inheritsPermissions": false,
        "_permissions": [
            {
                "principal": "user:system:anonymous",
                "allow": [
                    "READ"
                ],
                "deny": []
            },
            {
                "principal": "role:admin",
                "allow": [
                    "READ",
                    "CREATE",
                    "MODIFY",
                    "DELETE",
                    "PUBLISH",
                    "READ_PERMISSIONS",
                    "WRITE_PERMISSIONS"
                ],
                "deny": []
            }
        ],
        "_state": "DEFAULT",
        "_nodeType": "default",
        "_versionKey": "73ffd95d-4ec1-40b4-8c54-f2d7a23f6ab8",
        "_ts": "2019-05-13T16:23:51.856Z",
        displayName: "Carpenter and IT expert",
        likes: "Plywood",
        numberOfUselessGadgets: 123
    },
    ... (1)
]
1 With 3 input IDs, 3 nodes like this one was in the returned array.

getActiveVersion

Fetches specific nodes by path or ID.

Parameters

An object with the following key and value:

Name Kind Details

key

string

Path or ID of the node

Returns

object : Active content versions per branch

getBinary

Returns a binary stream.

Parameters

An object with the following keys and their value:

Name Kind Details

key

string

Path or ID of the node

binaryReference

string

to the binary

Returns

\* : Stream of the binary

Example

Fetching the binary of a node.
var binaryStream = repo.getBinary({
    key: "/myNode",
    binaryReference: "myBinaryReference"
});

modify

Modifies a node.

Parameters

An object with the following keys and their value:

Name Kind Details

key

string

Path or ID of the node

editor

function

Editor callback function

Returns

object : The modified node

Example

Modifying a node.
var result = repo.modify({
    key: key,
    editor: function (node) {
        node.someData.cars.push('peugeot');
        return node;
    }
});

move

Rename a node or move it do a new path.

Parameters

An object with the following keys and their value:

Name Kind Details

source

string

Path or id of the node to be moved or renamed

target

string

New path or name for the node. If the target ends in slash '/', it specifies the parent path where to be moved. Otherwise it means the new desired path or name for the node.

Returns

boolean : true if the node was successfully moved or renamed, false otherwise.

Examples

Changing the name of a node.
var moved = repo.move({
                source: '/my-name',
                target: 'new-name'
            });
Moving a node to a new location.
var moved = repo.move({
                source: '/my-name',
                target: '/new-parent/'
            });
Move and rename a node in the same operation.
var moved = repo.move({
                source: '/my-name',
                target: '/content/my-site/folder/new-name'
            });

push

Pushes a node to a given branch.

Parameters

An object with the following keys and their value:

Name Kind Details

key

string

Id or path to the nodes

keys

Array.<string>

Array of ids or paths to the nodes

target

string

Branch to push to

includeChildren

boolean

Also push children of given nodes. Default is false.

resolve

boolean

Resolve dependencies before pushing, meaning that references will also be pushed. Default is true.

exclude

Array.<string>

Optional array of ids or paths to nodes not to be pushed. If using this, be aware that nodes need to maintain data integrity (e.g parents must be present in target). If data integrity is not maintained with excluded nodes, they will be pushed anyway.

Returns

object : PushNodeResult

Examples

Pushing nodes from current branch.
var result = repo.push({
    keys: ['a'],
    target: 'otherBranch',
    resolve: false
});
Sample response
{
    "success": [
        "a"
    ],
    "failed": [],
    "deleted": []
}
Pushing content with children where not all children are allowed.
var result = repo.push({
    keys: ['a'],
    target: 'otherBranch',
    resolve: true,
    includeChildren: true
});
Sample response
{
    "success": [
        "a",
        "b",
        "c"
    ],
    "failed": [
        {
            "id": "d",
            "reason": "ACCESS_DENIED"
        }
    ],
    "deleted": []
}
Pushing node with children, but excluding some of them.
var result = repo.push({
    keys: ['/a'],
    target: 'otherBranch',
    resolve: true,
    includeChildren: true,
    exclude: ['/a/b', '/a/c']
});
Sample response
{
    "success": [
        "a",
        "d"
    ],
    "failed": [],
    "deleted": []
}

query

Queries nodes

Parameters

An object with the following keys and their value:

Name Kind Details

start

number

Start index, used for paging. The default is 0.

count

number

Number of conents to fetch

query

string

Query expression

filters

object

Query filters

sort

string

Sorting expression

aggregations

string

Aggregations expression

explain

boolean

If true, return score calculation explanation. The default is false.

Returns

object : stats, hits and if requested, aggregations

Examples

A simple query using a the fulltext function
var result = repo.query({
        query: "fulltext('_name', '_name')"
    });
Sample response
{
    "total": 4,
    "count": 4,
    "hits": [
        {
            "id": "5be12847-cbad-4e61-a36c-e94ffb597afb",
            "score": 0.7071067690849304
        },
        {
            "id": "3928476f-915d-4a6a-97cc-f1c8a905f71a",
            "score": 0.625
        },
        {
            "id": "a2e38aab-6efb-4f20-862c-e23ef24b3fc3",
            "score": 0.5
        },
        {
            "id": "3a842eff-ef49-4781-8c1a-dcfcf515db51",
            "score": 0.5
        }
    ],
    "aggregations": {}
}
Query content using aggregations.
var result = repo.query({
    start: 0,
    count: 2,
    query: "startTime > instant('2016-10-11T14:38:54.454Z')",
    filters: {
        boolean: {
            must: [
                {
                    exists: {
                        field: "modifiedTime"
                    }
                },
                {
                    exists: {
                        field: "other"
                    }
                }
            ],
            mustNot: {
                hasValue: {
                    field: "myField",
                    values: [
                        "cheese",
                        "fish",
                        "onion"
                    ]
                }
            }
        },
        notExists: {
            field: "unwantedField"
        },
        ids: {
            values: ["id1", "id2"]
        }
    },
    sort: "duration DESC",
    aggregations: {
        urls: {
            terms: {
                field: "url",
                order: "_count desc",
                size: 2
            },
            aggregations: {
                duration: {
                    histogram: {
                        field: "duration",
                        interval: 100,
                        minDocCount: 1,
                        extendedBoundMin: 0,
                        extendedBoundMax: 10000,
                        order: "_key desc"
                    }
                },
                durationStats: {
                    stats: {
                        field: "duration"
                    }
                }
            }
        }
    }
});
Sample response
{
    "total": 12902,
    "count": 2,
    "hits": [
        {
            "id": "b186d24f-ac38-42ca-a6db-1c1bda6c6c26",
            "score": 1.2300000190734863
        },
        {
            "id": "350ba4a6-589c-498b-8af0-f183850e1120",
            "score": 1.399999976158142
        }
    ],
    "aggregations": {
        "urls": {
            "buckets": [
                {
                    "key": "/site/draft/superhero/search",
                    "docCount": 6762,
                    "duration": {
                        "buckets": [
                            {
                                "key": "1600",
                                "docCount": 2
                            },
                            {
                                "key": "1400",
                                "docCount": 1
                            },
                            {
                                "key": "1300",
                                "docCount": 5
                            }
                        ]
                    }
                },
                {
                    "key": "/site/draft/superhero",
                    "docCount": 1245,
                    "duration": {
                        "buckets": [
                            {
                                "key": "1600",
                                "docCount": 2
                            },
                            {
                                "key": "1400",
                                "docCount": 1
                            },
                            {
                                "key": "1300",
                                "docCount": 5
                            }
                        ]
                    }
                }
            ]
        }
    }
}

refresh

Refresh the index for the current repoConnection. The index has two parts, search and storage. It is possible to index both or just one of them.

Parameters

Name Kind Details

mode

string

ALL for both indexes, SEARCH for search-index or STORAGE for storage-index. Default is ALL.

Returns

NULL

Examples

Refreshing the full index
repo.refresh();
Refreshing the serach index
repo.refresh('SEARCH');

setActiveVersion

Set the active version of a node.

Parameters

An object with the following keys and their value:

Name Kind Details

key

string

Path or ID of the node

versionID

string

Version to set as active

Returns

boolean : true if deleted, false otherwise

Example

Setting the previous version active
var findVersions = repo.findVersions({
    key: node._id
});

var result = repo.setActiveVersion({
    key: node._id,
    versionId: findVersions.hits[1].versionId
});

setChildOrder

Set the order of the node’s children.

Parameters

An object with the following keys and their value:

Name Kind Details

key

string

Path or ID of the node

childOrder

string

children order

Returns

object : The updated node

Example

Setting the children to be ordered in reverse alphabetical order by name
repo.setChildOrder({
    key: '/name-list',
    childOrder: 'name DESC'
});

setRootPermission

Set the root node permissions and inheritance.

Parameters

An object with the following keys and their value:

Name Kind Details

_permissions

object

The permissions

_inheritPermissions

boolean

true if the permissions should be inherited to children

Returns

object : The updated root-node

Example

Setting example permissions
var result = repo.setRootPermissions({
    _permissions: [
        {
            "principal": "role:system.admin",
            "allow": [
                "READ",
                "CREATE",
                "MODIFY",
                "DELETE",
                "PUBLISH",
                "READ_PERMISSIONS",
                "WRITE_PERMISSIONS"
            ],
            "deny": []
        }
    ],
    _inheritsPermissions: true
});

Source

A source definition of repositories:

Fields

Name Kind Details

repoId

object

Repository ID

branch

object

Branch ID

user

User

Optional user to execute the callback with - Default is the default user

principals

Array.<string>

Additional principals to execute the callback with

User

User object to use for connections:

Fields

Name Kind Details

login

string

user ID of the user

idProvider

string

Optional ID provider containing the user. By default, all the id providers will be used.

Contents