yodata-client-js

Yodata JavaScript Client

Use this JavaScript library to access the Yodata.io API with your brower or node.js based applications. All API calls accept and return JSON objects.

Requirements

At the moment, the only requirement to use this library is jQuery (tested with v1.11.1).

Setup

Browser Based

1. Manually copy the yodata.client.js file to your website file structure.
2. Create a script tag that reference the proper location of the file. This script tag should be below the script tag for the jQuery library.
3. Download the yodata.client.ui.js file from the yodata-client-ui-js project and follow the instructions to configure the login button.
4. The YDClient object can be accessed through the client UI library's api property.

Node.js

1. At the root directory of your node application, install the package at the command line by typing npm i yodata-client-js, or add the "yodata-client-js": "*" to the dependencies node your package.json file and run npm install.

Examples

Browser Based

//Make sure you have your login button configured in your HTML with the necessary app client ID and scopes. 
var ydClientUi = null;

$(document).ready(function() {
    ydClientUi = new YDClientUi();
    ydClientUi.onAuthStateChanged(function() {
        if(ydClientUi.isAuthenticated()) {
            //logged in state, make API calls to populate UI.

            ydClientUi.api.userProfile(function(err, results) {
                if (err || !results) {
                    ydClientUi.logout();
                } else {
                    $('#welcomeMessage').html('Welcome <strong>' + results.profile.name + '</strong>');
                    reloadTasks();
                }
            });
        } else {
            //logged out state. Hide UI elements that require login
        }
    });
}

function reloadTasks() {
    var options = {
        limit: 100,
        sort: {createdAt: -1}
    }

    ydClientUi.api.find('yodata.task', options , function(err, results) {
        if (err) {
            //an error occurred
        } else {
            //Render the task list in the UI
        }
    });
}

Node.js

var YDClient = require('yodata-client-js');
.
.
.
//load the auth token from your database, memory, cookies or query string and pass it to the constructor.
var client = new YDClient({ authToken: 'an auth token that was returned by the client side ui library.'});

var options = {
    limit: 100,
    sort: {createdAt: -1}
}

client.find('yodata.task', options , function(err, results) {
    if (err) {
        //an error occurred
    } else {
        //do something with the array of tasks
    }
});

YDClient methods

The callback functions for each of the following methods should accept both an error and a result object:

function(err, results) {
	if (err) {
        //handle the error
    } else {
        //do something with your results
    }
}

YDClient.insert (modelId, doc, callback)

Saves a new document for the currently logged in user. The results for this call will be the complete, inserted document with the new objectId, createdAt and modifiedAt dates.

YDClient.save (modelId, doc, callback)

Updates an existing document for the currently logged in user. You must load the entire document from either a find or findById call first, update the poperties you'd like to change, then pass the entire document back to the update method. The results for this call will be the complete, updated document.

YDClient.remove (modelId, objectId, callback)

Deletes exactly one document, with the given objectId, for the current user. If no error is returned, the command completed successfully.

YDClient.findById (modelId, objectId, callback)

Returns exactly one document, with the given objectId, for the current user. The results will be a single object, if found. An error will be returned if the objectId could not be located for the current user.

YDClient.find (modelId, options, callback)

Returns an array of documents. The following options are available.

option	description	default
criteria	Using the mongoDB syntax to perform a find	none
limit	The maximum number of records to return	10
offset	The number of records to skip.	0
sort	The sort order for your results. Use the mongoDb syntax for sorting	{ createdAt: -1 }
fields	A comma separated list of fields to return in the results. 'firstName,lastName'
Here's an example of how to sort by a lastName field, in reverse alphabetical order, returning the second set of 100 documents.

var options = {
    sort: { lastName: -1 },
    limit: 100,
    skip: 100
}

YDClient.find('yodata.task', options, function(err, results) {
    if (err) {
        //handle the error
    } else {
        //do something with your results
    }
}

YDClient.distinct(modelId, options, callback)

Accepts the same options as the find function, but returns unique values in the result set. For example, if you use the fields option with a value of lastName the result set would be a list of unique last names.

YDClient.count(modelId, options, callback)

Pass the criteria option to return the count of records that match the criteria.

YDClient.aggregate(modelId, options, callback)

Use the pipeline option to pass an array of mongoDB aggregation stages. The following is an example of how you could query the yodata.tasks collection to return a sorted list of tags and their count:

var options = {
    pipeline: [{$unwind: '$tags'}, { $group: { _id: '$tags', count: { $sum: 1 } }}, { $sort: {_id: 1}}]
}

ydClientUi.api.aggregate('yodata.task', options, function(err, tagList) {
   //display the list of tags and their counts...
});

YDClient.userProfile(callback)

Returns the user profile of the user associated with the current authentication token.

YDClient.uploadFile(formData, callback)

Allows you to upload a binary file using a multi-part form data post. The result in the callback function is a special file object, which you can use to reference the file in collections.

YDClient.generateDownloadUrlForPrivateFileById(fileId, callback)

Public files have a publicFileUrl property, which would allow you to access the file directly using an img tag (if it's an image) or a link. For private files a two step process is used to generate a download token, which can be used to download the file from the download URL. For security reasons the URL that's returned by this function is only valid for 10 minutes.