ringcentral-js-helpers v0.1.0

Installation

SDK can be used in 2 environments:

1. Browser
2. NodeJS

1. Set things up in Browser

1.1. Get the code

Pick the option that works best for you:

• Preferred way to install SDK is to use Bower, all dependencies will be downloaded to bower_components directory:

  bower install ringcentral-helpers --save
  ```Bower

• Donwload everything manually (not recommended):

  • ZIP file with source code
  • ZIP file with source code

1.2.a. Add scripts to HTML page

You can use bundle version (with PUBNUB and ES6 Promise included in main file).

Add this to your HTML:

<script type="text/javascript" src="path-to-scripts/ringcentral-helpers/build/ringcentral-helpers.js"></script>

Use the object:

var helpers = RingCentral.Helpers;

1.2.b. Set things up in Browser (if you use RequireJS in your project)

// Add this to your RequireJS configuration file
require.config({
    paths: {
        'ringcentral-helpers': 'path-to-scripts/ringcentral-helpers/build/ringcentral-helpers',
    }
});

// Then you can use the SDK like any other AMD component
require(['ringcentral-helpers'], function(helpers) {
    // your code here
});

2. Set things up in NodeJS

1. Install the NPM package:

   npm install ringcentral-helpers --save

2. Require the SDK:

   var helpers = require('ringcentral-helpers');

Helpers

Abstract

The SDK provides a variety of different helpers to make it easier to alter, save, load, and delete data objects and otherwise interact with the features of the API. Helpers are plain JavaScript objects that contain functions and useful properties (e.g. constants).

Basic Functionality

All helpers are extensions to the base Helper object and have all of its functions, plus some overrides and extra functionality. See the documentation for each particular helper for information on available options and methods.

Following is a deeper look at the CallHelper object.

Create a URL

helpers.call().createUrl(options, id);

Creates a URL that can be provided to the Platform#apiCall() method. Creation algorithm is based on options:

• {personal: true} - Call log of the currently logged in extension
• {extensionId: '12345'} - Call log of extension with the id 12345 (the logged in user must have admin permissions)

Following are some example calls, along with the URLs that they would return:

helpers.call().createUrl(); // '/account/~/extension/~/call-log'
helpers.call().createUrl({personal: true}); // '/account/~/extension/~/call-log'
helpers.call().createUrl({extensionId: '12345'}); // '/account/~/extension/12345/call-log'
helpers.call().createUrl({extensionId: '12345'}, '67890'); // '/account/~/extension/12345/call-log/67890'

Check if an object exists on the server

helpers.call().isNew(object);

If the object exists on the server, then the isNew method will return false. The object is considered not new if it has both ID and URI properties - this usually means that the object was returned from the server.

helpers.call().isNew({}); // false
helpers.call().isNew({id: '67890'}); // false
helpers.call().isNew({uri: '/account/~/extension/12345/call-log/67890'}); // false
helpers.call().isNew({id: '67890', uri: '/account/~/extension/12345/call-log/67890'}); // true

Filter an array of objects

helpers.call().filter(options);

CallHelper#filter(options) returns a preconfigured function that can be used for the fn argument when calling the filter method (Array.prototype.filter(fn)) on an array of calls. The behavior of the filter may vary depending on the options argument.

// calls in an array of Call Log calls
var callsFilteredByDirection = calls.filter(Call.filter({direction: 'Inbound'}));
var callsFilteredByType = calls.filter(Call.filter({type: 'Voice'}));

Sort an array of objects

helpers.call().comparator(options);

CallHelper#comparator(options) returns a preconfigured function that can be used for the fn argument when calling the sort method (Array.prototype.sort(fn)) on an array of calls. The behavior of the filter may vary depending on the options argument. By default, values are extracted simply as item[options.sortBy] as strings and sorted as strings. Custom options.extractFn and options.compareFn functions may be specified.

// calls in an array of Call Log calls
var callsSortedByStartTime = calls.sort(Call.comparator({sortBy: 'startTime'})); // or any other property
var callsSortedByDuration = calls.sort(Call.comparator({
    compareFn: rcsdk.getList().numberComparator // compare as numbers
})); // or any other property

// filter and sort can be combined
var inboundCallsSortedByStartTime = calls
    .filter(Call.filter({direction: 'Inbound'}))
    .sort(Call.comparator({sortBy: 'startTime'}));

Special methods - Get pre-configured Subscription objects for endpoints

These methods will provide Subscription objects with pre-bound events.

var subscription = helpers.presence().addEventsToSubscription({detailed: true}, '~');

var subscription = helpers.message().addEventsToSubscription();

Once you have a Subscription object, all you need to do next is register it by calling its register method:

subscription.register();

Special methods - Convert ActiveCalls array of Presence into regular Calls

Assume that presence is an object returned by one of Presence endpoints.

var calls = helpers.call().parsePresenceCalls(presence.activeCalls);

Full Example

For this example, AngularJS will be used.

var platform = sdk.platform(),
    Call = helpers.call();

$scope.calls = [];
$scope.nextPageExists = true;
$scope.queryParams = {page: 1, perPage: 'max'}; // page and perPage may be set from template

$scope.requestNextPage = function() { // can be called from template to request next page
    $scope.queryParams.page++;
    loadCalls();
};

function loadCalls() {

    platform.send(Call.loadRequest(null, {
        query: $scope.queryParams,
    })).then(function(response) {

        $scope.calls = response.data.records
            .filter(Call.filter({direction: 'Inbound'}))
            .sort(Call.comparator({sortBy: 'startTime'}));

        $scope.nextPageExists = Call.nextPageExists(response.data); // feed raw data from server to helper function

    }).catch(function(e) {
        alert('Error', e.message);
    });

}

loadCalls();

Model Relations

Abstract

The SDK allows easy establishment of relationships between objects, such as between a Message object and its associated Contact objects, or a Presence object and its associated Extension object. How the relationship is resolved varies across different types of objects. The resolving function is provided by helper objects of a certain type.

Relationship

Models have relationships to other models.

In many cases, model relationships are merely through properties of a model that identify other models. The data for the associated child models is not contained inside the data for the model and would need to be loaded with separate requests to the server. This type of relationship is considered a weak relationship. To use an example, both the Message and Call models have relationships to the Contact model. Associated models should be loaded separately and may be assigned to appropriate properties dynamically on the client based upon some criteria through helpers.

In some cases, models may actually contain other models. In such cases, the data for the associated child models will be contained inside the model's data in the form of a property. The server returns the data for the model and its contained child models within the same API call. As examples of this, the Presence model contains an extension property and the Account model contains an operator property, and these properties are both references to contained models of type IExtensionShort.

Examples

Abstract CallerInfo types and Contacts

var contacts = [{homePhone: '+(1)foo'}, ...], // homePhone may be formatted
    callerInfos = [{phoneNumber: '1foo'}, ...]; // phoneNumber is not formatted

helpers.contact().attachToCallerInfos(callerInfos, contacts);

Each callerInfo object will get the new properties:

1. contact — matching contact
2. contactPhone — entry from contact that matched phoneNumber

Messages / Calls and Contacts

For Messages and Calls, optimized helper functions may be used:

messages = helpers.message().attachContacts(contacts, messages);
calls = helpers.call().attachContacts(contacts, calls);

This will internally fetch a list of callerInfos and attach appropriate contacts to them.

Presence and Extensions

Presence information may be attached to extensions, for example, when the application has loaded a list of extensions and a list of their associated presence. Each extension will be given a new presence property, which will link to the presence object for the extension.

extensions = helpers.presence().attachToExtensions(extensions, presences);