How to develop an Office App in real world-part 2

After part 1, we now look into the app side of our Excel solution. I want to point out some basics here to make it easy for developers to create their first Office App (with Excel). Here we go.

Working with the API

To easily access the Excel or Word functions with JavasScript, Microsoft provides an object with an anonymous function and a context (ctx here) as parameter. So, accessing Excel works basically as here:

Use “Word.run” in Word , etc. The context represents a kind of command queue to the Desktop or Online Client. All objects as workbooks, ranges, charts, etc. are proxy objects which only exist in JavaScript.

Important!

As mentioned, in Office Apps on the JavaScript side we work with proxy objects.

On the host side (in the document in your Office client), nothing happens, until we execute the context sync method!

The sync updates the host application. Remember that when developing!

So, for getting data, we need to use for example the load command or run the context method. This can be accomplished as here.

function doSomething() {
  Excel.run(function (ctx) {
    var range = ctx.workbook.worksheets.getActiveWorksheet().getRange("A1:C3").load("values");
    return ctx.sync()
  });
}

Alternatively, we could use this code, which is equal:

    var range = ctx.workbook.worksheets.getActiveWorksheet().getRange("A1:C3")
     ctx.load(range, "values");

Both methods do the same. Most developers prefer the .load method attached to the object, so version one.

Chain Promises

After a sync method, we can add multiple actions as here. return ctx.sync() returns the full promise (after it is created in the function header). It must be returned, since the Excel.run function should get the return value, the modified context.

Anyway, you can add multiple promises as here:

function doMultipleActions() {
    Excel.run(function (ctx) {
        var range = ctx.workbook.worksheets.getActiveWorksheet().getRange("A1:A100").load("values");
        return ctx.sync()
            .then(function () {
                // loop thru the rows
                for (var i = 0; i < range.values.length; i++) {
                    var cell = range.values[i][0];
                    if (cell.trim() != "") {
                        console.log(cell);
                    }
                }
                // do something
                ctx.sync();
            })
        .then(function () { //
            // do something after the function before
            ctx.sync();
        })
        .then(function () { //
            // do something after the function before
            ctx.sync();
        })
        .then(ctx.sync);
        console.log("end.");
        app.showNotification("Done");
    }).catch(function (error) {
        console.log(error);
        app.showNotification("Error", error);
    });
}


Or combine all actions sequentially in the first ctx function.

Helpful: app.showNotification(“message”)

If your want to inform your user about any message, use app.showNotification("Error", error);. This popups the message at the bottom of your app. It can be closed by the “x” icon by the user. Simply and effect full.

Also helpful: JSON.stringify()

We are in Javascript, or? So if we get data as JSON object, we can simply output the values with JSON.stringify(somedata);. This helps especially for debugging or doing a quick visualization.

Working with arrays

Counter wise, working with an array and transforming it into a string works with the .join() method. To get a list as "1,2,3,4,5,6,7,8,9" it would work as here:

var myarr = [];
for (var i = 0; i < 10; i++) {
  myarr.push(i);
}
var mystring = myarr.join(',');

Instead of filling an array yourself, another option is to use the .map(function(item) { }) method if possible, just as tip.

The .split() method is used to decompose one string into an array.

jQuery is helpful as well

jQuery can simplify a lot of tasks, from accessing form elements to operations. For example, call external data services with $.getJSON(url, ‘parameters’).done(function (result) {} ).fail (function (error) {} );. Nice and quick, but remember, in Office Apps every channel is secured by https. Use only https URLs.

No need to restart

When you have your target document open, for example the Excel file, simply leave it this way. Change the JavaScript code, save the file and reload the app and test again!

That’s a benefit of working with an interpreter language and a browser…

More resources

Find more helpful documentation online here:

• Office snippet explorer for Excel
• Excel JavaScript add-in APIs
• End-to-End Walkthrough of Excel JavaScript Add-in Development

I hope this crash course delivers some basic ideas about developing Office Apps with Visual Studio.

Happy coding!