refreshAsync method

Settings.refreshAsync method (JavaScript API for Office)

Office Add-ins

Reads all settings persisted in the document and refreshes the content or task pane add-in's copy of those settings held in memory.

Last modified: September 22, 2015

Hosts:

Access, Excel, PowerPoint, Word

Available in Requirement set

Settings

Last changed in

1.1

See all support details

Office.context.document.settings.refreshAsync(callback);

callback

Type: object

A function that is invoked when the callback returns, whose only parameter is of type AsyncResult.

When the function you passed to the callback parameter executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

In the callback function passed to the refreshAsync method, you can use the properties of the AsyncResult object to return the following information.

Property

Use to...

AsyncResult.value

Access a Settings object with the refreshed values.

AsyncResult.status

Determine the success or failure of the operation.

AsyncResult.error

Access an Error object that provides error information if the operation failed.

AsyncResult.asyncContext

Access your user-defined object or value, if you passed one as the asyncContext parameter.

This method is useful in Word and PowerPoint coauthoring scenarios when multiple instances of the same add-in are working against the same document. Because each add-in is working against an in-memory copy of the settings loaded from the document at the time the user opened it, the settings values used by each user can get out of sync. This can happen whenever an instance of the add-in calls the Settings.saveAsync method to persist all of that user's settings to the document. Calling the refreshAsync method from the event handler for the settingsChanged event of the add-in will refresh the settings values for all users.

The refreshAsync method can be called from add-ins created for Excel, but since it doesn't support coauthoring there is no reason to do so.

function refreshSettings() {
    Office.context.document.settings.refreshAsync(function (asyncResult) {
        write('Settings refreshed with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

A checkmark (√) in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Office for Windows desktop

Office Online
(in browser)

Office for iPad

Access

Excel

PowerPoint

Word

Available in requirement sets

Settings

Minimum permission level

Restricted

Add-in types

Content, task pane

Library

Office.js

Namespace

Office

Version

Changes

1.1

Added support for PowerPoint Online.

1.1

Added support for Excel, PowerPoint, and Word in Office for iPad.

1.1

Added support for custom settings in content add-ins for Access.

1.0

Introduced

Show:
© 2016 Microsoft