×

Please give details of the problem

Docs

Find

JavaScript Methods for Collections


To access a collection from a web interface, you can use JavaScript methods. In this section, the available methods are described including examples.

Adding an Object

To add an object to a collection, you can use the saveCallback method.

1
id_collection.saveCallback(object,callbackSuccess,callbackFailure)

This method expects the following parameters:

  • The object to save into the collection
  • A callback to call in case of success
  • A callback to call in case of a failure

JavaScript uses the collection ID to identify the collection, Freemarker uses the collection name instead (see Freemarker Functions for Collections).

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
function add_ok(result) {
alert("ok " + JSON.stringify(result));
}

function add_ko(result) {
alert("ko " + JSON.stringify(result));
}

var my_object = {};
my_object.first_name = "Mike";
my_object.last_name = "Tyson";
my_object.phone_number = "";

col_clients.saveCallback(my_object,add_ok,add_ko);

The code adds a new object to the collection. If the action is successful, the success callback (add_ok) is called. The result parameter of the callback is the saved object, as seen by the MongoDB engine.

You can of course customize your callbackSuccess and callbackFailure functions as you like.

Listing Objects

1
id_collection.listCallback(pattern,options,callbackSuccess,callbackFailure)

This method expects the following parameters:

  • The pattern used to find matching objects. If you want to list all objects of a collection, use {} as a pattern.
  • Some options passed using a JSON object The options parameter has several properties:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    var options = {};
    
    options.fields = ["first_name","last_name"];// retrieve objects with only first_name and last_name fields. Default is [] to get all fields
    options.mode = "TEST"; // retrieve data from the collection of the specified execution mode. The default value ist the current execution mode of the web interface
    options.nb = 5; // max nb of items to list. Default is 100. Max is 1000.
    options.first = 2; // starting index to list objects. Default is 0
    options.orderby = ["last_name","first_name"]; //order by last_name and first_name. 
    options.order = ["asc","desc"]; //must match `orderby` field : order by last_name asc and first_name desc.
    options.asynchronous = false; //if you need synchronous requests, must be set as false. Default is true
    
  • A callback to call in case of success.

  • A callback to call in case of a failure.

Example 1:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
function list_ok(result) {
    alert("ok=" + JSON.stringify(result));
}

function list_ko(result) {
    alert("ko=" + JSON.stringify(result));
}

var my_pattern = {};
col_clients.listCallback(my_pattern,{},list_ok,list_ko);

All objects are returned, for example:

1
ok=[{"first_name":"Mike","last_name":"Tyson"},{"first_name":"John","last_name":"Smith"},{"first_name":"John","last_name":"Doe"}]

Example 2:

1
2
3
4
var my_pattern = {};
my_pattern.first_name = "John";

col_clients.listCallback(my_pattern,{},list_ok,list_ko);

All objects whose first_name field is "John" are returned, for example:

1
ok=[{"first_name":"John","last_name":"Smith"},{"first_name":"John","last_name":"Doe"}]

Updating Objects

1
id_collection.updateCallback(pattern,object,callbackSuccess,callbackFailure)

Updates the first object matching pattern with the object document.

1
id_collection.updateMultiCallback(pattern,object,callbackSuccess,callbackFailure)

Updates all objects matching pattern with the object document. Be very careful when using this method, as you can update a lot of documents at once.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
function update_ok(result) {
alert("ok " + JSON.stringify(result));
}

function update_ko(result) {
alert("ko " + JSON.stringify(result));
}

var my_pattern = {};
my_pattern.first_name = "John";
my_pattern.last_name= "Smith";

var my_object = {};
my_object.first_name = "John";
my_object.last_name = "Smith";
my_object.phone_number = "111-222-333";

col_clients.updateMultiCallback(my_pattern ,my_object ,update_ok,update_ko);

When executing the script, you get back the information about the number of updated objects matching the pattern.

Updating Specific Fields in Objects

To update only specific fields without passing the complete object, you can use the pattern {$set:object}

Example:

Update only the phone_number field for objects with first_name = "John"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
function update_ok(result) {
alert("ok " + JSON.stringify(result));
}

function update_ko(result) {
alert("ko " + JSON.stringify(result));
}

var my_pattern = {};
my_pattern.first_name = "John";

var my_object = {};
my_object.phone_number = "444-555";

col_clients.updateMultiCallback(my_pattern,{$set:my_object},update_ok,update_ko);

When executing the script, you get back the information about the number of updated objects matching the pattern.

Deleting Objects

1
id_collection.removeCallback(pattern,callbackSuccess,callbackFailure)

Deletes all objects matching pattern.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
function delete_ok(result) {
alert("ok " + JSON.stringify(result));
}

function delete_ko(result) {
alert("ko " + JSON.stringify(result));
}

var my_pattern= {};
my_pattern.first_name = "John";
my_pattern.last_name = "Smith";

col_clients.removeCallback(my_pattern,delete_ok,delete_ko);

Performing an Aggregation

1
id_collection.aggregateCallback(my_pipelines,my_options,callbackSuccess,callbackFailure);

Example:
In the following example, the collection has the following fields and contents:

Fields: [first_name,last_name,state,nb_of_cars,nb_of_motors]

Contents:

If you want to display the number of cars per state, you have to build an aggregate expression and use a $group pipeline. The grouping key should be the state. It is passed through the _id object. You use the $sum function to calculate the total number of cars per state.

1
{"$group":{"_id":{"State":"$state"},"Total":{"$sum":"$nb_of_cars"}}}

$group,_id, and $sum are reserved words. $state and $nb_of_cars are the names of the fields in the collection.

To define which fields you want to project and show in the final result, you use the $project pipeline:

1
{"$project":{"STATE":"$_id.State","TOTAL_CARS":"$Total"}}

As shown above, State must be prefixed by $_id as it is part of the grouping key.

The final code is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
function callbackSuccess(result) {
alert("OK " + JSON.stringify(result));
}
function callbackFailure(result) {
alert("KO " + JSON.stringify(result));
}

var my_pipelines = [{
"$group" : {
"_id" : {
"State" : "$state"
},
"Total" : {
"$sum" : "$nb_of_cars"
}
}
}, {
"$project" : {
"STATE" : "$_id.State",
"TOTAL_CARS" : "$Total"
}
}
];

id_collection.aggregateCallback(my_pipelines,{},callbackSuccess,callbackFailure);

This is the callbackSuccess result:

1
[{"STATE":"Arizona","TOTAL_CARS":4},{"STATE":"Florida","TOTAL_CARS":2}, {"STATE":"Alaska","TOTAL_CARS":5}]

Other pipeline examples:

Filter on the Alaska state

1
{"$match":{"state":"Alaska"}}

Filter on items where the state field is defined:

1
{"$match": {"state":{$exists :true}}}