Using custom objects in the database

With custom objects you can store custom data in MongoDB.

Custom objects are stored in collections with the prefix customobjects. The collections are created automatically when a custom object is generated.

Custom objects are scoped. This means that if a scope is assigned to a user, this user can only see and manipulate objects to which the same scope has been assigned. Other objects are not visible to the user. To users to which all scopes are assigned, all objects are visible and editable.

Some collections may need to contain publicly accessible objects. You can do this by setting a preference that disables the scope checking for a particular customobjects collection. For a collection called my_collection, you can disable the scope filtering with this command:

api.preferences.save_for_realm(false, 'system', '', 'com.nixps.customobjects.my_collection, 'scoped');

You can reactivate the scope filtering by replacing false with true.

Creating objects

An object can be created using custom_objects.create, which takes the name of the collection and the new object as parameters.

Example

obj = api.custom_objects.create('my_collection', {foo: "test", bar: 1});

After this call:

obj is a copy of the object.
_id is the extra key, which is the object ID.

Note:

If a single scope is assigned to the user, the same scope is assigned to the object. Consequently, the object is only visible to users to whom the scope is assigned and to users to whom all scopes are assigned.
If all scopes are assigned to the user, no scope is assigned to the object. Consequently, the object only is visible to users to whom all scopes are assigned.

If all scopes are assigned to the user, the user can assign a scope to the object using custom_objects.set_scope.

Example

api.custom_objects.set_scope('my_collection', objectID, scopeID);

Where:

objectID is the _id field of the object (assigned by the create function).
scopeID is the Mongo ID of the scope.

To remove the scope of the object, pass an empty string as the scopeID.

Retrieving objects

If the Mongo ID of the object is known, the object can be retrieved using custom_objects.get

Example

obj = api.custom_objects.get('my_collection', objectID);

A custom object collection can be queried using custom_objects.list and custom_objects.list_with_options:

api.custom_objects.list('my_collection', ['foo', 'equal to', 'test'], ['foo', 'bar']);

api.custom_objects.list_with_objects('my_collection', ['foo', 'equal to', 'test'], ['bar', 'ascending'], ['foo', 'bar'], {maximum: 5})

Changing objects

There are three ways to change a custom object:

The function custom_objects.update replaces the object with another object:
```
api.custom_objects.update('my_collection', objectID, {x: 1, y: 2});
```
The function custom_objects.set_keys performs a partial update.
Example
To replace the bar' field and to add the xyz field:
```
api.custom_objects.set_keys('my_collection', objectID, {bar: 13, xyz: "abc"});
```
The function custom_objects.remove_keys removes some fields from an object:
```
api.custom_objects.remove_keys('my_collection', objectID, ['foo']);
```

Removing objects

An object can be removed using the custom_objects.delete function:

api.custom_objects.delete('my_collection', objectID)

The function custom_objects.delete_many removes several objects at once:

api.custom_objects.delete_many('my_collection', ['foo', 'equal to', 'test']);