Promises Pattern

This is a type of pattern that can be used for asynchronous programming
This is an alternative to the nested callbacks pattern because deeply nested callbacks can be difficult to read and understand.
The promises pattern only works with code for bindings in Excel spreadsheets and Word documents
Instead of passing a callback function and waiting for the function to return before execution continues, the promises programming pattern immediately returns a promise object that represents its intended result.
However, unlike true synchronous programming, under the covers the fulfillment of the promised result is actually deferred until the Office Add-ins runtime environment can complete the request. An onError handler is provided to cover situations when the request can't be fulfilled.


the Office.select method to support the promises pattern for working with existing binding objects.
The promise object returned to the Office.select method supports only the following four methods:
Binding.getDataAsync
Binding.setDataAsync
Binding.addHandlerAsync
Binding.removeHandlerAsync.


The promises pattern for working with bindings takes this form:
Office.select(_selectorExpression, onError)._BindingObjectAsyncMethod


selectorExpression - takes the form "bindings#bindingId", where bindingId is the name ( id) of a binding that you created previously in the document or spreadsheet (using one of the "addFrom" methods of the Bindings collection:
addFromNamedItemAsync, addFromPromptAsync, or addFromSelectionAsync).
For example, the selector expression bindings#cities specifies that you want to access the binding with an id of 'cities'.


onError - is an error handling function which takes a single parameter of type AsyncResult that can be used to access an


Error object, if the select method fails to access the specified binding.
The following example shows a basic error handler function that can be passed to the onError parameter.


function onError(result){ 
    var err = result.error;
    write(err.name + ": " + err.message);
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

Replace the BindingObjectAsyncMethod placeholder with a call to any of the four supported Binding object methods.


Calls to these methods don't support additional promises. You must call them using the nested callback function pattern.


After a Binding object promise is fulfilled, it can be reused in the chained method call as if it were a binding (the add-in runtime won't asynchronously retry fulfilling the promise).


If the Binding object promise can't be fulfilled, the add-in runtime will try again to access the binding object the next time one of its asynchronous methods is invoked.


The following code example uses the select method to retrieve a binding with the id " cities" from the Bindings collection, and then calls the addHandlerAsync method to add an event handler for the dataChanged event of the binding.


function addBindingDataChangedEventHandler() { 
    Office.select("bindings#cities", function onError(){/* error handling code */}).addHandlerAsync

(Office.EventType.BindingDataChanged,
    function (eventArgs) {
        doSomethingWithBinding(eventArgs.binding);
    });
}

The Binding object promise returned by the Office.select method provides access to only the four methods of the Binding object.
If you need to access any of the other members of the Binding object, instead you must use the Document.bindings property and


Bindings.getByIdAsync or Bindings.getAllAsync methods to retrieve the Binding object.
For example, if you need to access any of the Binding object's properties (the document, id, or type properties), or need to access the properties of the MatrixBinding or TableBinding objects, you must use the getByIdAsync or getAllAsync methods to retrieve a Binding object



© 2019 Better Solutions Limited. All Rights Reserved. © 2019 Better Solutions Limited TopPrevNext