Application wide settings in Office Apps – It's elementary, my dear Watson!

  • Article

In my earlier post, we talked about saving our Office App settings and other properties using the Settings object exposed by the Office Document. This approach, while certainly very useful, has certain limitations and disadvantages.

  1. The settings and properties are saved per document. This means that if we want to have a setting applied to all the instances of our app open on the user’s machine, user has to individually enable it on all the open documents.
  2. In this approach, settings are saved as part of the document itself. This increases the size of the document.
  3. While document size may not be a matter of concern, if the document is under some kind of Content Management System, changing the document contents checks out the document and also is not consistent with user’s expectation of nothing changing in the document unless explicitly done by the user.

So how do we create application wide settings which do not change the document? The answer, my friend, is staring at us from the Visual Studio window.

image

Since our Office App is a web page running in an IFrame, we can take advantage of all the features of HTML5 – namely Local Storage. So what is HTML5 Storage?As per the excellent site, <diveintohtml5.info>,

“Simply put, it’s a way for web pages to store named key/value pairs locally, within the client web browser. Like cookies, this data persists even after you navigate away from the web site, close your browser tab, exit your browser, or what have you. Unlike cookies, this data is never transmitted to the remote web server (unless you go out of your way to send it manually).”

Show me the code!

Let us see how HTML5 Storage can help us store our application settings. We are creating a simple app which has accepts user input and inserts it into Word document. User has an option to always make the text bold while inserting by checking a check box. This setting will be persisted across all the documents and even when the app is closed and re-launched.

image

You can check whether your Office App support a particular HTML5 feature by using the excellent Modernizr JavaScript library. We use this library to check Local Storage feature like this:

 //Check whether HTML5 storage is supported 
 if (Modernizr.localstorage) { 
 //Store your setting in HTML5 storage 
 localStorage["bold"] = this.checked; 
 }

That’s it! Your app is saving application wide settings and data which you can retrieve any time you need.

Putting it all together -

HTML -

 <!DOCTYPE html>
 <html> 
 < head> 
 <meta charset="UTF-8" /> 
 <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> 
 <title>LocalStorage</title>
 <link rel="stylesheet" type="text/css" href="../Content/Office.css" /> 
 <link rel="stylesheet" type="text/css" href="../Content/App.css" />
 <script src="../Scripts/jquery-1.6.2.js"></script> 
 <script src="../Scripts/Office/MicrosoftAjax.js"></script> 
 <script src="../Scripts/Office/Office.js"></script> 
 <script src="../Scripts/modernizr.custom.14548.js"></script> 
 <!-- Add your JavaScript to the following file --> 
 <script src="../Scripts/LocalStorage.js"></script> 
 < /head> 
 < body> 
 <div id="Content"> 
 Type something in the text box and hit 'Insert'<br/> 
 <input id="txtInput" type="text" style='margin-top: 10px;width:210px' /><br/> 
 <input id="btnInsert" type="button" value="Insert" /><br/><br/><br/> 
 <a href="#" id="aSettings">Settings</a> 
 <div id="settings"> 
 <input id="chkBoldText" type="checkbox" autofocus="autofocus" />Always Bold my text 
 </div> 
 </div> 
 < /body> 
 < /html>

JavaScript -

 Office.initialize = function (reason) { 
 $(document).ready(function () { 
 $("#settings").hide(); 
 if (localStorage["bold"] != null) { 
 if (localStorage["bold"] == 'true') { 
 $("#chkBoldText").prop("checked", true); 
 } 
 else { 
 $("#chkBoldText").prop("checked", false); 
 } 
 } 
 $("#aSettings").click(function () { 
 $("#settings").toggle(); 
 }); 
 $("#chkBoldText").click(function () { 
 if (Modernizr.localstorage) { 
 localStorage["bold"] = this.checked; 
 } 
 }); 
 $("#btnInsert").click(function () { 
 var dataToInsert = $("#txtInput").val(); 
 if (localStorage["bold"] != null) { 
 if (localStorage["bold"] == 'true') { 
 dataToInsert = '<b>' + dataToInsert + '</b>'; 
 } 
 } 
 Office.context.document.setSelectedDataAsync(dataToInsert, { coercionType: "html" }); 
 }); 
 }); 
 };

You can read more about HTML5 Storage here.