• Getting Started
  • Source Adapters
  • Source Adapter Ruby APIs
  • Source Adapter JS APIs
  • Plugins
  • Push Sync
  • Administration
  • Deployment
  • Advanced Topics
  • Clients
  • Hosted Services
  • Vendor Adapters
Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

RhoConnect.js API Reference

RhoConnect.js API is implemented as public fields of a global RhoConnect object. Those are methods and ERRORS hash.

If you have properties in the class, list and define them here.

login

Returns a jQuery promise object.

Authenticates the RhoConnect application on the server. On success, the done handler is called. On failure, the fail handler is called with the following arguments:

  • errCode - The error code value from RhoConnect.ERRORS.
  • errorMessage - More detailed error message if available.

The syntax and parameters are as follows.

RhoConnect.login(username, password, doDataReset)
username The user name to authenticate with.
password The password to authenticate with.
doDataReset (optional) Boolean. If true, do a database reset before login. Default value is false.

Example

function loginRhoConnect(username, password) {
    persistence.store.rhoconnect.config(persistence);
    return $.Deferred(function(dfr){
        // login with username, password, and a DB reset
        RhoConnect.login(username, password,
                new RhoConnect.SyncNotification(), true /*do db init*/).done(function(){
            // Init DB for the user on success
            initRhoconnect(username, false).done(function(){
                dfr.resolve();
            }).fail(function(errCode, err){
                alert('DB init error: ' +errCode);
                dfr.reject(errCode, err);
            });
        }).fail(function(errCode, err){
            //alert('RhoConnect login error: ' +errCode);
            dfr.reject(errCode, err);
        });
    }).promise();
}

init

Performs rhoconnect.js and data API initialization.

Returns a jQuery promise object. On success, the done handler is called. On failure, the fail handler is called with the following arguments:

  • errCode - The error code value from RhoConnect.ERRORS.
  • errorMessage - More detailed error message if available.

The syntax and parameters are as follows.

RhoConnect.init(modelDefinitions, dataApiType, syncProgressCallback)
modelDefinitions Model definitions array. See Getting Started for a sample.
dataApiType (optional) - A string value: 'extjs', 'persistencejs', or 'custom' or null.

'extjs' - Do initialize ExtJS/SenchaTouch data API to use as application data storage.
'persistencejs' - Do initialize Persistence.js data API to use as application data storage.
'custom' or null - Don't initialize any data API, perform data API initialization in custom code.
syncProgressCallback (optional) Progress update callback function to use. Receives the argument notificationBody, which is a hash with the following fields.
sourceName The name of model just synchronized.
totalCount The total *objects* count for the *model*.
processedCount The number of *objects* that have been processed so far for a *model* may be *0* if all objects have already been processed.
status Is undefined while *inProgress* value is *true*. When finished it is a string value:
"ok" - Synchronization of exact model has been performed without errors.
"error" - Errors happened during synchronization process.
errorCode Code of synchronization error. Is undefined if no errors happened. Look at RhoConnect.ERRORS description for details.
errorMessage Synchronization error message. Is undefined if no errors happened.

Example

// RhoConnect.js initialization
function initRhoconnect(username, doReset) {
    return RhoConnect.init(modelDefinitions, 'persistencejs', doReset);
}

modelDefinitions is a hash, such as:

var modelDefinitions = [
        {
            name: 'User',
            fields: [
                {name: 'username',      type: 'string'},
                {name: 'email',         type: 'string'},
                {name: 'first_name',    type: 'string'},
                {name: 'last_name',     type: 'string'},
                {name: 'title',         type: 'string'},
                {name: 'company',       type: 'string'},
                {name: 'created_at',    type: 'string'},
                {name: 'updated_at',    type: 'string'}
            ]
       },
//...

logout

Disconnects the RhoConnect application from the server.

Returns a jQuery promise object. On success, the done handler is called. On failure, the fail handler is called with the following arguments:

  • errCode - The error code value from RhoConnect.ERRORS.
  • errorMessage - More detailed error message if available.

The syntax is as follows.

RhoConnect.logout()

isLoggedIn

Returns true if the application is logged in on the server.

RhoConnect.isLoggedIn()

syncAllSources

Synchronizes that application data with the RhoConnect server.

Returns a jQuery promise object. On success, the done handler is called. On failure, the fail handler is called with the following arguments:

  • errCode - The error code value from RhoConnect.ERRORS.
  • errorMessage - More detailed error message if available.

The syntax is as follows.

RhoConnect.syncAllSources()

Example

function sync(){
    RhoConnect.syncAllSources().done(function(){
        alert('sync successful');
    }).fail(function(errCode, err){
        alert('Data sync error: ' +errCode);
    });
}

dataAccessObjects

Returns the hash of data access objects which are data API specific. The returned hash contains:

  • key - model name.
  • value - An instance of one of the following objects.
  • Ext.data.Store - for ‘extjs’ type of data API
  • model - for ‘persistencejs’ type of data API

The syntax is as follows.

RhoConnect.dataAccessObjects()

Example

function pull_data(model) {
    // passed a model name, returns hash of data access objects.
    var store = RhoConnect.dataAccessObjects()[model];

    current_model = model;
    persistence.loadFromRhoConnect(function() {
        storeLoaded();
    });

setModelNotification

Set the handler for the exact model synchronization notification.

RhoConnect.setModelNotification(modelName, callback, removeAfterFire)
modelName Name of the model to listen for notifications.
callback Handler function. Receives the only argument of notificationBody, which is a hash with the following fields.
sourceName The name of the model just synchronized.
totalCount The total number of objects for the model.
processedCount The number of objects that have been processed so far for a model. 0 if all the objects have already been processed.
status Is undefined while inProgress is True. When finished, it is a string value.
"ok" if the synchronization of the exact model has been performed without errors.
"error" if errors happened during the synchronization process.
errorCode Code of synchronization error. Undefined if no errors happened. Look at the RhoConnect.ERRORS description for details.
errorMessage Synchronization error message. Undefined if no errors happened.
removeAfterFire Clear notification subscription after notification event if true. The same if handler function returns true.

clearModelNotification

Resets the handler for the model synchronization notification.

RhoConnect.clearModelNotification(modelName)
modelName Name of the model to reset the handler.

setAllNotification

Sets the handler for all models synchronization notifications.

RhoConnect.setAllNotification(callback, removeAfterFire)
callback Handler function. Receives the only argument of notificationBody, which is a hash with the following fields.
inProgress Boolean value. True if synchronization is still in progress, undefined if synchronization is finished.
status Undefined while the inProgress value is true. When synchronization is finished, it is a string value.
"complete" - Synchronization of all models have been performed without errors.
"error" - Errors happened during synchronization process.
errorCode Code of the synchronization error. Undefined if no errors happened. Look at RhoConnect.ERRORS description for details.
errorMessage Synchronization error message. Undefined if no errors happened.
removeAfterFire Clear notification subscription after notification event if true. The same if handler function returns true.

clearAllNotification

Reset handler for all models synchronization notifications.

RhoConnect.clearAllNotification()

setObjectsNotification

Set handler for all object change notifications.

RhoConnect.setObjectsNotification(callback, removeAfterFire)
callback Handler function. Receives the only argument of notificationBody, which is a hash with fields.
updated Array of hashes for updated objects. Every hash object has form of {objectId: objId, sourceId: srcId}, where:
objectId - The id of the updated object.
modelName - The name of the object model.
created Array of hashes for created objects. Every hash object has form of {objectId: objId, sourceId: srcId}, where:
objectId - The id of the updated object.
modelName - The name of the object model.
deleted Array of hashes for deleted objects. Every hash object has form of {objectId: objId, sourceId: srcId}, where:
objectId - The id of the updated object.
modelName - The name of the object model.
removeAfterFire Clear notification subscription after notification event if true. The same if handler function returns true.

clearObjectsNotification

Reset the handler for all object change notifications.

RhoConnect.clearObjectsNotification()

addObjectNotify

Subscribe an object for changes notification.

RhoConnect.addObjectNotify(modelName, objectId)
modelName The name of the object model.
objectId The id of the object.

clearObjectsNotify

Unsubscribe all objects from changes notification.

RhoConnect.clearObjectsNotify()

RhoConnect.ERRORS

RhoConnect.ERRORS are defined as:

  • ERR_NONE: ‘No error’
  • ERR_NETWORK: ‘Network error’
  • ERR_REMOTESERVER: ‘Remote server access error’
  • ERR_RUNTIME: ‘Runtime error’
  • ERR_UNEXPECTEDSERVERRESPONSE: ‘Unexpected server response’
  • ERR_DIFFDOMAINSINSYNCSRC: ‘Different synchronization domain error’
  • ERR_NOSERVERRESPONSE: ‘No server response’
  • ERR_CLIENTISNOTLOGGEDIN: ‘Client not logged in’
  • ERR_CUSTOMSYNCSERVER: ‘Custom sync server’
  • ERR_UNATHORIZED: ‘Unauthorized access’
  • ERR_CANCELBYUSER: ‘Canceled by user’
  • ERR_SYNCVERSION: ‘Synchronization version error’
  • ERR_GEOLOCATION: ‘Geolocation error’
Back to Top