VBA->JS: A first look at the Word JS object model using Script Lab

If you’re curious about the Office JS API application object models and want to get acquainted you can do so without any investment other than time. All you need is a Microsoft account and Office 365 / Office 2016 installed on your machine (Windows or Mac) or access to Office Online. Then you can install Script Lab.

You can install Script Lab multiple times if you want to see it in more than one Office application or use it in more than one environment. I have it, for example, in Office 2016 running on Windows 7, on a Mac Book Pro, in Office 2016 running on Windows 10 in Parallels and in Word On-line running as part of Office 365 on a Windows 7 machine with Office 2010 installed locally.

Once Script Lab is installed, go to the Insert tab in the Ribbon, look in the Office Add-ins, and there under My Add-ins select the Script Lab entry. This will put a Script Lab tab in the Ribbon with six buttons.

  • The Code and Run buttons display taskpanes to the right of the document in which you can write code and execute it.
  • The Tutorial button opens an Excel workbook that walks you through using Script Lab.
  • Help opens the Git Hub site for Script Lab in a browser window.
  • Reference Docs opens a browser window to the Office documentation site (currently dev.office.com) for the Office application you’re using.
  • Ask the Community takes you to the office-js tag on Stack Overflow.

Open the Code window. After a moment you should see the Samples section. This offers you starting points for various common tasks in the Office application you’re in. In Word you’ll find topics such as inserting pictures, text, headers, breaks, searching the document, working with paragraphs, content controls, ranges, tables, lists and document properties. You can choose any of these, run the code, modify it and, if you wish, save your work. It’s also possible to import code from other sources in order to work with it in Script Lab.

At the top of the list of samples you’ll see that the first two have the same name, one is labelled as “Typescript”, the other as “Javascript”. From Wikipedia: “TypeScript is an open-source programming language developed and maintained by Microsoft. It is a strict syntactical superset of JavaScript, and adds optional static typing to the language…TypeScript may be used to develop JavaScript applications for client-side or server-side (Node.js) execution. TypeScript is designed for development of large applications and transpile to JavaScript. As TypeScript is a superset of JavaScript, existing JavaScript programs are also valid TypeScript programs.”

The Office JS development team recommends Typescript and uses it. It makes working with asynchronous calls less arduous – but you can choose which to use. The basic Office JS API syntax for the object models isn’t affected by your choice.

Let’s take a look at the Typescript version and start with the code that’s relevant to the object model – things you should recognize from using the COM object model (such as VBA):

   const range = context.document.getSelection();
   range.font.color = "red";

In the first line you’ll see a variable declaration for a Range object. The instantiation is in the same line – something not possible in VBA, but is supported in VB.NET and C#. The current selection (more precisely, its range) in the document is assigned to the Range object. VBA developers should also note the parentheses () after the method getSelection: these are mandatory, as is the semicolon at the end of the line.

The left-hand side of the following line could come right from the COM object model. Experienced Word developers might be surprised to see the color name specified simply as a string – no wd enumerator or complicated RGB function. This is a nice improvement! Indeed, the color property accepts the name as a string, or an RGB specification (from the documentation): “Gets or sets the color for the specified font. You can provide the value in the ‘#RRGGBB’ format or the color name.”

(The color names correspond to colors defined in the W3 CSS specification. For more about the RGB value see 4.2 Numerical color values. For a list of color names see section 4.3. This table is also helpful, as is this one.)

Try it out. Type something in the active document, make a selection, then click the “Run” button using the first option. The selected text should turn red, and the action can be undone using the standard Undo command in the Ribbon.

Back in the editing pane, change "red" to "blue". Now run it again.

Consulting the documentation on the font property you’ll see that bold is also an option. Position the insertion point after "red";, press Enter and type range.font.bold = true; Type it exactly as it appears here, paying attention to capitalization: (Javascript is case-sensitive!) Run the code again.

As you can see, working with the Javascript object model is very similar to working with the COM object model. The capitalization is different and you have to remember the semi-colon at the end of each command. But the basis of what you know you can continue to use.

In the next blog entry I’ll look at the rest of the code in the sample; that is new and different – and takes some getting used to.

Leave a Reply