yodata-client-js

Yodata JavaScript Client

Use this JavaScript client to enable your browser based application to access the Yodata platform. 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

1. Copy the yodata.client.js and yodata.client.ui.js files to your website file structure.
2. Create script tags that reference the proper location of these files. These script tags should be below the script tag for the jQuery library.
3. Log into Yodata.io and create a new application.
4. Select the models you'd like to use within your application, and the type of access you need for each model (view/edit).
5. Create the following div somewhere in your html: <div class="yd-login-button" data-client-id="your yodata application's client ID" data-scopes="your required scopes">

Examples

Read only access to just the yodata.task model:

<div class="yd-login-button" data-client-id="1234567890ABCDEF" data-scopes="view:yodata.task">

Read/Write access to just the yodata.task model:

<div class="yd-login-button" data-client-id="1234567890ABCDEF" data-scopes="edit:yodata.task">

Read access to the yodata.task model and write access to the yodata.person model:

<div class="yd-login-button" data-client-id="1234567890ABCDEF" data-scopes="view:yodata.task,edit:yodata.person">

1. Either on the page, in a script block, or in a separate JavaScript file add the following code:

var ydClient = null;

$(document).ready(function() {
    ydClientUi = new YDClientUi();
});

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.