zlatkovsky / buildingofficeaddins

Issues & topic-request tracker, and sample-code repository, for "Building Office Add-ins using Office.js"

Building Office Add-ins using Office.js

The everygreen book

This repo is a sample-code and issue-tracking companion to the book "Building Office Add-ins using Office.js" -- an "evergreen" e-book published and purchasable through LeanPub.com.

From the book description:

This book is a guide to Office.js APIs, which are used to build the web-technology-based Office Add-ins. Is describes the principles and design patterns shared by the new 2016+ wave of APIs for Excel, Word, and OneNote -- written by someone who, as member of the Office Extensibility Platform team at Microsoft, had helped design them.

 

This repo's purpose is to:

#1: Allow me to share the larger code samples and associated assets (e.g., documents with sample data, geared specifically for the scenario).

#2: Provides readers with a way to log and track content issues (and be informed once they are fixed). Issues can be:

• Simple content issues: A misspelling, an incomplete phrase, a sentence that no longer makes sense.
• Requests for additional detail in existing topics.
• Requests for brand new topics. I might already be planning to write something about it eventually, but this will let you subscribe to finding out when the content is made available; and will also help me gauge topic interest.
• Issues with sample code or related assets: code is unclear; the design is sub optimal; something needs a comment; or perhaps an existing comment needs to be clarified or removed.
• Anything else?

#3: Keep track of the Release notes.

 

If you have questions about specific APIs, please use StackOverflow.

This repo is meant for aggregating book issues -- but the book's purpose is not to cover every single API, but rather to cover the common concepts. If you have a question about a specific API, please use StackOverflow, tagging your question office-js.

In fact, even if your question is about a core concept, I still encourage you to ask it on StackOverflow first, as you'll almost certainly get a quicker response there (and if the response is from me, it might well make it into the book eventually!). This repo is for tracking the issues and topics, but addressing questions is best done through StackOverflow.

If you want to contact me, please feel free to reach out at

buildingofficeaddins's Issues

Update TypeScript topics with a slightly different ".catch" pattern (try/catch within)

$('#run').click(() => {
    Excel.run(async (context) => {
        try {
            console.log('Your code goes here');
            await context.sync();
        }
        catch (error) {
            OfficeHelpers.Utilities.log(error);
        }
    });
});

Also tweak guidance to always do final sync.

Suggestion -- 4.2.2 Variables & TypeScript

Maybe a screenshot? Would help to explain/show the below:

Parameter type declarations. This is supremely useful, as it allows
you to split long procedures into multiple subroutines, and yet not
lose IntelliSense and compile-time error-checking. For example,
you can declare a function as
function updateValues(range: Excel.Range) { ... }
and be able to see all of the range properties/methods/etc. within the
body of the function, as opposed to seeing a dishearteningly-empty
IntelliSense list.

Suggestion -- 4.2.2 Variables & TypeScript

var taxRate = retrieveTaxRate();

wrt the above, bcos previously u recommend always using let instead of var, should this example also use “let”?

Fix minor issue with appendix section ordering

Before before... page 174

Common mistakes: add example of invoking function in .then instead of creating a callback for invoking it

Add links to GitHub sample code downloads

Issue

Add links from Chapter 5 to the GitHub samples, for population-analysis, gradebook, and stock-fetcher samples.

Add info about Yeoman generator (& TS & browser-sync)

https://github.com/OfficeDev/generator-office/blob/master/readme.md

Add "use strict" to Misc section of JS Primer

Req sets: add info about defined OM

In environments that don't support tables: var tables = context.document.body.tables; the above tables var is defined. It just errors on load.

Stocks Example

The REST query to yahoo does is not working out-of-the-box. Changed the URL as follows to get it to work. FYI.

    var data = 'q=' +
        encodeURIComponent(
            'select * from yahoo.finance.quote ' +
            'where symbol in (' + quotedCommaSeparatedNames + ')'
        ) +
        "&env=store%3A%2F%2Fdatatables.org" +
        "%2Falltableswithkeys&format=json";

Concrete Excel example: 4 ways to compute sum of range

try {
    await Excel.run(async (context) => {
        var array = [
            [0, 1, 1, 1],
            [0, 0, 1, 0],
            [0, 0, 1, 0],
        ];

        // Method 1 (write formula and read back)
        // const sheet = context.workbook.worksheets.getActiveWorksheet();
        // const range = sheet.getRange("A1").getResizedRange(array.length - 1, array[0].length - 1)
        // range.values = array;
        // const sumRange = sheet.getRange("F2");
        // sumRange.formulas = [["=SUM(A1:D5)"]]
        // sumRange.load("values")
        // await context.sync();
        // OfficeHelpers.UI.notify("Sum", sumRange.values[0][0].toString())

        // Method 2 (use Excel as calculation engine)
        // const sheet = context.workbook.worksheets.getActiveWorksheet();
        // const range = sheet.getRange("A1").getResizedRange(array.length - 1, array[0].length - 1)
        // range.values = array;
        // const sum = context.workbook.functions.sum(range).load("value")
        // await context.sync();
        // OfficeHelpers.UI.notify("Sum", sum.value.toString());

        // Method 3: (calculate in-place via plain JS)
        // let sum = 0;
        // array.forEach(row => {
        //     row.forEach(cell => {
        //         sum = sum + cell;
        //     });
        // })
        // console.log(sum)

        // Method 3B:
        // let sum = 0;
        // array.forEach(row => row.forEach(cell => sum = sum + cell))
        // console.log(sum)
    });
}
catch (error) {
    OfficeHelpers.UI.notify(error);
    OfficeHelpers.Utilities.log(error);
}

Add topic on distributing document along with add-in

• Clearing personal data (image remove-personal-data)
• Auto-opening taskpane
• Passing in setting

Excel.run resuming-to-use-objects guidance

Excel.run(obj, (ctx) => { ... })
Also add warning for not ending up in deadlock

page 168, missing "y" in [possibly-length]

Add note about optional parameters in functions

createArray(row, columns, fillIn?: boolean)

Browser differences (and IE / sandbox)

(And differences between it and others, and between hosted in add-in vs native)

history navigation

Add release notes and issues repo link into the book's intro chapter

Add link to attach-debugger

https://dev.office.com/blogs/attach-debugger-from-the-task-pane

[Content issue]: Incorrect statement in "Implementation Details" section

In this section, you say that when a method or property gets called on a proxy, either an object path is created or an action, but that is not correct. All property access and method call create a new action, which operates on a object and may or may not create another object, which would then get assigned its object path.

Office.js API versioning story

Add an Office.js-tailored JavaScript/TypeScript crash-course

Issue

Add a very quick overview of JS/TS, tailored particularly to the book.

Implementation sample code: third row vs. firstRow

In crash-course topic, add section about by-reference vs by-value

Converting / augmenting VBA/VSTO add-ins, OpenXML

(See also http://stackoverflow.com/questions/42549170/how-to-port-existing-vb-net-office-add-ins-to-work-with-office-for-mac)

[LeanPub issue] Cross-links for missing sections not showing as errors

https://groups.google.com/forum/#!searchin/leanpub/Zlatkovsky%7Csort:relevance/leanpub/82k-4FrbJEU/rVCEPk8tBQAJ

Error codes section

InvalidArgument: https://stackoverflow.com/questions/44137567/merging-excel-cells-using-office-js/44168042?noredirect=1

Must return promise

Merge with property not loaded

Add "resources" section with links to useful URLs

Already have one mostly-ready (pending chapters, resources.md)

Event handlers

[Please describe the issue here]

[Optional] Add a screenshot or a description of text before/after. (Page numbers and section numbers change all the time, and so aren't useful as reference points)

Fix example code from page 99

The correct would be:

function createRainbow() {
	var $rainbow = $("#rainbow");
	$rainbow.css("background", "red");
	setTimeout(function() {
		$rainbow.css("background", "orange");
		setTimeout(function() {
			$rainbow.css("background", "yellow");
			setTimeout(function() {
				$rainbow.css("background", "green");
				setTimeout(function() {
					$rainbow.css("background", "blue");
					setTimeout(function() {
						$rainbow.css("background", "indigo");
						setTimeout(function() {
							$rainbow.css("background", "violet");
						}, 2000);
					}, 2000);
				}, 2000);
			}, 2000);
		}, 2000);
	}, 2000);
}

Obs. 1: Sorry for changing ' to ", it is my linter.
Obs. 2: Maybe it is easier to change just var $rainbow = ... to var object = ..., as the very same error happens in pages 101 and 102, but a good jQuery script is to put $ as a prefix in jQuery variable names.

Need a topic on the different Office namespaces: "Office", "OfficeExtension", "Excel", "Word", etc.

Internet Explorer tips & tricks

(And differences between it and others, and between hosted in add-in vs native)

• history navigation

IntelliSense reference

https://dev.office.com/docs/add-ins/get-started/get-javascript-intellisense-in-visual-studio

Add topic on npm, vs code

[Please describe the issue here]

[Optional] Add a screenshot or a description of text before/after. (Page numbers and section numbers change all the time, and so aren't useful as reference points)

Checking for object existence + OrNullObject pattern

(Most is already written)

Add section on finding point of failure: Trace Messages

Trivial typos: 4.2.2 Variables & TypeScript

Typo:

1. ...it is always a best-practice to use “let“. In fact, if you’re only assigning
   a variable once and never re-assinging it, it is better to use an event
   stronger form of let: “const”....

should be: ..re-assigning it, it is better to use an even....

2. Very occasionally, you might have disagreement with the TypeScript
   compiler over a particular type. This happens primarily in Excel for 2Darray
   properties, such as values or formulas on an Excel.Range vobject.

should be: ...Excel.Range object.

2. Strings can be either be single-quoted or double-quoted, so long as the
   quote types match.

issue: extra "be"

Add topic for the four simple principles of Office.js

Probably put as first section in Chapter 5, though may need to adjust the first section a bit.

Move code samples to Script Lab, possibly slight refactor

[Please describe the issue here]

[Optional] Add a screenshot or a description of text before/after. (Page numbers and section numbers change all the time, and so aren't useful as reference points)

Add topic re. Events

Type in page 101

Armed with this newly-created function for creating Promsies
solve the rainbow scenario much more satisfactorily:

It should be Promises.

TypeScript primer: add note about `let { message, type } = event.data;` syntax

Modify `.catch` code to `catch`

Office versions -- clarify that Office 365 is software + services

Office 365 is the brand name Microsoft uses for a group of software and services subscriptions, which together provide productivity software and related services to subscribers. For consumers, the service allows the use of Microsoft Office apps on Windows and macOS, provides storage space on Microsoft's cloud storage service OneDrive, and grants 60 Skype minutes per month. For business users, Office 365 offers service plans providing e-mail and social networking services through hosted versions of Exchange Server, Skype for Business Server, SharePoint and Office Online, integration with Yammer, as well as access to the Microsoft Office software.

https://en.wikipedia.org/wiki/Office_365

Where possible, use `const` instead of `let` in samples

Using React / Angular to build Office Add-ins

Was wondering if there would be any scope for this as large scale Add-ins need substantial frameworks.

Minor formatting fixes

Add info on using local copy of Office.js, and about the `https://github.com/OfficeDev/office-js` repo

Generalize the section “Loading on methods versus properties”

You have a nice section “Loading on methods versus properties”. But the detailed example and solution give the impression that the problem only arises when the developer calls the same method twice, once before and once after the context.sync. I just discovered, the hard way, that the problem is more general than that. For example, the following code will get the error, even though the method settings.getItem method is only called after the context.sync. I suggest that you emphasize in the section that it doesn’t matter how the objects are loaded, when you use a method, you’re getting a brand new, unloaded, proxy object.

var settings = context.document.settings;
settings.add('startMonth', { month: 'March', year: 1998 });
settings.load('value');
return context.sync().then(function () {
	for (var i = 0; i < settings.items.length; i++) {

			// The next line works, so it’s natural for the developer to think that he’s loaded the individual settings.
			console.log(settings.items[i].value);
	}
	// But this line will fail for reasons given in your book.
   var month = settings.getItem('startMonth').value;
});

GitHub link for DefinitelyTyped changed

On page 41, there is a link to download a JS file (DefinitelyTyped), but apparently the URL for the file changed.

Old link:
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/office-js/index.d.ts

New link:
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/office-js/index.d.ts