Settings

Allows you to persist data

Office.context.document.settings.set("mySetting", "mySetting value"); 

The Settings object makes it possible to store data associated with the user or the app. The data is saved in the document file and can be retrieved at any point later. Be aware that settings are saved per document and not per app, so it's only possible to retrieve settings saved in the current document. This is very useful for caching data specific to the app state for the current document. This example shows how to use the Settings.set method to store a key value pair of strings. This setting will be made available during the entire app session.


Settings

addHandlerAsyncM  
getM  
refreshAsyncM  
removeM  
removeHandlerAsyncM  
saveAsyncM  
setM  
SettingsChangedE  

Click Run Code to get a setting
Get a setting previously set in the document

var settingsValue = Office.context.document.settings.get("mySetting"); 
showMessage("mySetting value is: " + settingsValue);

To get a setting previously set or saved by the app, use the Settings.get method.


Click Run Code to save a setting in the document
Save a setting in the document to make it available in future sessions

Office.context.document.settings.saveAsync(function (asyncResult) { 
 if (asyncResult.status == "failed") {
showMessage("Action failed with error: " + asyncResult.error.message);
         }
 else {
 showMessage("Settings saved with status: " + asyncResult.status);
 }
});

Any setting previously saved by an app is loaded when the document is initialized, so during the lifetime of the session you can just use the set and get methods to read and write settings. When you want to persist the settings so that they are available the next time the app is used with the document, use the saveAsync method.


If we were to save, close, then reopen the current document, you'll notice that while the app (which embeds into and travels with the document) automatically relaunches, all of our saved content is now gone.
This makes sense, as we haven't done anything to persist the data. Fortunately, the Office API makes this simple by exposing a Settings property on the document, the contents of which are also embedded and travel with the document.
The Settings object has both a get and set method for storing and retrieving content, which can be a string, number, date, or object (but not a function). However, in addition to using set to store a value, if you want to save the content to the document for later reuse, you must also call the saveAsync method.
To add support for storing the content to our app, we simply created a global variable, which we use to push new items as they are added. We then save that updated content to the settings and finally store it with the document:


  var content; 

    // write the selected item to the content object and save to the document settings
    function saveContentToSettings(result) {
        content.push({ text: result.asyncContext, value: result.value });
        Office.context.document.settings.set("content", content);
        Office.context.document.settings.saveAsync();
    }

Now when we launch the app, we simply check for the presence of this setting, and if populated, reload the entries, or otherwise setting the content variable as an empty array ready for new items to be saved.


// restore content from settings

            content = Office.context.document.settings.get("content"); 
            if (content && content.length) {
                $.each(content, function (i, e) {
                    addToList(e.text, e.value);
                });
            } else {
                content = [];
            }



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