RealObjects Nimbudocs Editor 3.0.3929_Beta1

Guide: Async API


Introduction

Since version 2.0 Beta 1, Nimbudocs Editor features a new asynchronous API. Many API methods that were previously synchronous are now asynchronous. This means that these methods do no longer block the browser, which greately improves the user experience. In addition, these methods now return a Promise object which is resolved at a later time once the asynchronous call to the Nimbudocs Editor server is finished.

Migrating to Promises

Integrators should adapt their Nimbudocs Editor integration to this new API immediately! These changes only affect getter methods or methods that had a return value. Not all of these methods are affected though, so please see the API documentation for more information. Async methods are flagged with the ASYNC tag and you will see that they now return a Promise. Furthermore these methods have been renamed to "fetch*" (like "fetchDocument").

For more information about Promises in general please see https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise.

The following example show how the async methods are now used compared to older versions of Nimbudocs Editor.

Getting the document

// old
var doc = editor.getDocument();
doSomething(doc);

// new
editor.fetchDocument().then(function(doc) {
    doSomething(doc);
});

The Promise which is returned by the fetchDocument method has a then method which accepts a callback. That callback is called once the Promise is resolved. The argument of the callback is the same as the return value of the old (synchronous) getDocument method.

For async getter methods, the API documentation now contains a "Resolved With" field instead of the "Returns" field. Since these methods always return a Promise object, at this point it is more important to know with which value the Promise will be resolved, hence the "Resolved With" field.

Multiple Promises

When having multiple Promises, you can use the JavaScript Promise API or similar APIs like jQuery to execute a specified callback once all Promises have been resolved.

Multiple Promises

var p1 = editor.fetchNumberOfParagraphs();
var p2 = editor.fetchNumberOfWords();
var p1 = editor.fetchNumberOfCharacters();

// using Nimbudocs Editor (recommended)
NimbudocsEditor.when(p1, p2, p3).then(function(paras, words, chars) {
    doSomething(paras, words, chars);
});

// using JavaScript Promise API
Promise.all([p1, p2, p3]).then(function(result) {
    var paras = result[0];
    var words = result[1];
    var chars = result[2];
    
    doSomething(paras, words, chars);
});

// using jQuery
jQuery.when(p1, p2, p3).then(function(paras, words, chars) {
    doSomething(paras, words, chars);
});

It is generally recommended to use the Nimbudocs Editor API in this case. This methods is safe for other types of arguments, including undefined. Arguments that are not Promises will be passed as-is to the "then" handler. If none of the arguments are Promises, the "then" handler is called immediately.

Since the Promises returned by Nimbudocs Editor are thennable, the standard JavaScript Promise API can be used as well. However, please note that the JavaScript Promise API is not supported by Internet Explorer versions below 11.

Rejected/Failed Promises

If a call to an asynchronous API method fails (e.g. due to network issues), you can add a handler to be called:

var p1 = editor.fetchNumberOfParagraphs();

p1.then(function(success) {
    doSomethingOnSuccess(success);
}, function(fail) {
    doSomethingOnFail(fail);
});