Async Callbacks

Introduced in 2012 August for Office 2013 under the name of "Apps for Office"
This uses a Common Shared API across all the Office applications.
All the methods in this Common API use asynchronous programming and their names end with "Async".
When an "Async" method is called, it executes immediately and any subsequent script execution can continue.
The optional callback function you pass to an "Async" method executes as soon as the data or requested operation is ready.
dev.office.com/docs/add-ins/develop/asynchronous-programming-in-office-add-ins


General API Object model

Each host application (Word, Excel, Excel Web App, PowerPoint, Project, Outlook and Outlook Web App) can use a subset of the capabilities included in the API. For example, roughly 40 percent of the object model pertains solely to mail apps that can only be used in Outlook and the Outlook Web App.
Another portion of the object model allows interaction with Custom XML Parts, which is only available in Word 2013.


All the asynchronous functions have the same naming convention and the same basic signature.
Every asynchronous function name ends in "Async," for example, Document.getSelectedDataAsync.
The signature for all asynchronous functions adheres to the following basic pattern:
When an "Async" method is called, it executes immediately and any subsequent script execution can continue.
When the "Async" method returns, the callback resumes execution on the thread, and the add-in can the access data, do something with it, and display the result
The optional callback function you pass to an "Async" method executes as soon as the data or requested operation is ready.
This generally occurs promptly, but there can be a slight delay before it returns.


MSDN - Getting Started Articles

https://msdn.microsoft.com/EN-US/magazine/jj891051.aspx
https://msdn.microsoft.com/EN-US/magazine/jj991976.aspx
https://msdn.microsoft.com/EN-US/magazine/dn166930.aspx


ASynchronous Callback Functions

The callback function needs to be passed as the callback argument.
An anonymous function can be written and passed directly or you can use a named function and pass in the function name.
This function must have a single argument that can be used to obtain an AsyncResult object.


Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, 
    function (result) {
        write('Selected data: ' + result.value);
    }
});
function write(message){
    document.getElementById('message').innerText += message;
}

Asynchronous Programming Patterns

The Office API supports both these types of asynchronous programming:
1) Nested Callbacks - you can use nested callbacks from all the Async methods.
2) Promises Pattern - provides an alternative to nested callbacks when you want to avoid deeply nested callbacks


The promises pattern only works with code for bindings in Excel workbooks and Word documents.
dev.office.com/docs/add-ins/develop/bind-to-regions-in-a-document-or-spreadsheet



Document.getSelectedDataAsync

Office.context.document.setSelectedDataAsync( 
   Object _data [, Object _options] [, function _callback])

_data - This is the value that you want to set.
_options - This is a collection of key/value pairs separated by a colon.
_callback - This is invoked once the asynchronous operation is complete.


Office.context.document.getSelectedDataAsync( 
   Office.CoercionType _coerciontype [, Object _options] [, function _callback])

_coerciontype - The type of data that you want to get.
_options - This is a collection of key/value pairs seperated by a colon.
_callback - This is invoked once the asynchronous operation is complete.


List of Async Methods

see page


AsyncResult

see page


CoercionType

see page


Options

see page



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