Posted by on Feb 22, 2016 in #Office365Dev | 3 comments

With the new application model for Office comes a brand new way of extending Office with your own functionality – using the tools and dev stacks that we already know and love.

This blog post demonstrates a few different ways to interact with the Office context. Adding different types of content, reading selected data from the document and displaying it. In addition, Different styles and components from the Office UI Fabric library are used throughout this Office add-in.
The objective is to get familiar with some of the possiblities that we have when building Word add-ins.

The blog post is divided into multiple steps and should be followed in a chronological order. These are the included steps:

1.1 Create the project
1.2 Edit the manifest
1.3 Launch the project
2.1 Clean up the project
2.2 Add Office UI Fabric
2.3 Add the base
3.1 Add plain text to the document
3.2 Add HTML to the document
3.3 Add a matrix to the document
3.4 Add an Office Table to the document
3.5 Add Office Open XML to the document
4.1 Add the dialog
4.2 Get selected data as plain text
4.3 Get selected data as HTML

Short of time and just want the final sample? Clone this repository (https://github.com/simonjaeger/OfficeDev-HOL.git) and open the solution file: Word-Add-in\Source\Word-Add-in.sln.

Prerequisites

Visual Studio 2015: https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx
Office Developer Tools: https://www.visualstudio.com/en-us/features/office-tools-vs.aspx
Office 2013 (Service Pack 1) or Office 2016

Step 1.1: Create the project

The first thing that we need to do is to create the project itself. Make sure that you have installed all of the required prerequisites before launching Visual Studio 2015.

1. Click File, New and finally the Project button.
2. In Templates, select Visual C#, Office/SharePoint and then Office Add-ins. This will list the Office add-in templates, choose Office Add-in.
3. Name your project “Word-Add-in” and click the OK button to continue.

4. Next up Visual Studio 2015 will need a bit more information about what you are going to create – in order to set up the required files. Your next step is to decide which type of Office add-in that you want to create. Depending on what you pick, your Office add-in will run in different Office applications and contexts.

For this blog post, we will create a task pane add-in – this means that our Office add-in will run in a view beside the Office context (e.g. a document, spreadsheet, slide). Select Task pane and click on Next.

5. Finally we need to choose the host applications. This means that we are defining the Office applications that our Office (task pane) add-in can run within. Select Word and deselect everything else to create a “Word-only” add-in. Click Finish to complete the wizard.

6. Using the information you specified in the wizard, Visual Studio 2015 will configure your project. Have a look in the Solution Explorer and find your two new projects in the Word-Add-in solution.

Word-Add-in: This is your manifest project, containing the XML manifest file. This is basically a representation of the information you just specified while creating your Office add-in project.

Word-Add-inWeb: This is your web project for the Office add-in. This contains all of the different source files that makes up your Word add-in. We will make quite a few adjustments to this structure as we continue.

You’ve now created the basic structure for a taskpane add-in running in Word.

Step 1.2: Edit the manifest

We need to make sure that we understand the manifest file. This file is essential for your add-in; it tells Office where everything is hosted (locally throughout this blog post) and where it can be launched. So let’s open it and edit the manifest file.

1. In the manifest project Word-Add-in, double-click the Word-Add-inManifest file. This will open the manifest editor.

2. In the General tab section, find and edit the Display name and Provider name to anything you’d like.
3. Scroll down and pay attention to the Source location property. This points to a specific file in your web project (Word-Add-inWeb). When launching your Word add-in, this page will be the first thing that gets loaded and displayed.

Step 1.3: Launch the project

Before we launch our Word add-in we should validate that our start actions are proper.

1. Select the manifest project; Word-Add-in in the Solution Explorer.

2. In the Properties window, set Start Action to Office Desktop Client.
3. Set Start Document to [New Word Document].
4. Set Web Project to your web project; Word-Add-inWeb.

5. To launch the project, open the Debug menu at the top of Visual Studio 2015 and click on the Start Debugging button. You can also click the Start button in your toolbar or use the {F5} keyboard shortcut.

6. Once your Word add-in has launched, you can explore the functionality that comes right out of the box with the Visual Studio 2015 template.

7. Finally, stop debugging by opening the Debug menu at the top of Visual Studio 2015 and click on the Stop Debugging button. You can also click the Stop button in your toolbar.

Step 2.1: Clean up the project

While the default styling that comes along with the Visual Studio 2015 template for Office add-ins does its job – leveraging the features of the Office UI Fabric can be fantastic. It’s a UI toolkit made specifically for building Office and Office 365 experiences, so it will certainly help us out here.

The Office UI Fabric library comes with everything from styling, components to animations. The majority of the library can be references via a CDN. The heavier parts needs to be downloaded and added to the project itself. We will go through both of these approaches.

Our first task is to clean up the project, and remove the default styling and setup.

1. Remove the Content and Images folders from the web project. You can do this by right-clicking these folders in the Solution Explorer and choosing the Delete option.

2. In your Solution Explorer, find the Home.html file – which is the startup page for your Word add-in. Remove everything inside the body tags.
3. In Home.html remove the CSS reference to “../../Content/Office.css” – we have removed this file and will be using Office UI Fabric instead. This should leave you with this:

4. In App.js, remove the initialize() function defined on the app object, as this will not be used:

5. In Home.js, remove the getDataFromSelection() function and the call to app.initialize(). We are remaking the structure of the Word add-in, these will no longer be used. You should end up with this:

6. In App.css, remove everything, leaving you with an empty file.

Step 2.2: Add Office UI Fabric

1. In Home.html, add two CSS references to the CDN for Office UI Fabric inside the head tags. Add them before the CSS reference to “../App.css”.

2. Some components in the Office UI Fabric library require some additional JavaScript to function. In our case, we will use a Dropdown component that needs this. Download the JavaScript file for this component (Jquery.Dropdown.js) at https://raw.githubusercontent.com/OfficeDev/Office-UI-Fabric/master/src/components/Dropdown/Jquery.Dropdown.js or get it by browsing the files included in this blog post.
3. Add the Jquery.Dropdown.js file to your Scripts folder in the Solution Explorer. You can do this by right-clicking the Scripts folder and choosing Add Existing Item….

4. In Home.html, reference the Jquery.Dropdown.js file by adding the following line inside the head tags. Be sure to add it after the reference to “../../Scripts/jquery-1.9.1.js”.

5. In Home.js, add the following line inside the document.ready function of your page.

This will use the functionality within the Jquery.Dropdown.js file and initialize any Dropdown components that we add to the view.

6. Your Home.html file should now look like this:

Your Home.js file should look like this:

Step 2.3: Add the base (CSS + HTML)

1. In App.css, add the following basic CSS (this should be entire file). We will do much of the styling through already defined classes in the Office UI Fabric. But some basic layouting will do us great!

2. In Home.js, add an event handler (below the initialization of the Office UI Fabric components, in the document.ready function) for the click event of the button:

3. In Home.js, add the following function to add HTML to the document:

4. Launch your Word add-in and test your work by clicking the Add HTML button. When the button is clicked, the function will be executed; adding a piece of HTML into the document.

Step 3.3: Add a matrix to the document

1. In Home.html, locate the “Step: Add matrix” section (commented) and add the following HTML piece inside the div (section) tags. This is an Office UI Fabric styled button.

2. In Home.js, add an event handler (below the initialization of the Office UI Fabric components, in the ready function) for the click event of the button:

3. In Home.js, add the following function to add a matrix to the document:

4. Launch your Word add-in and test your work by clicking the Add matrix button. When the button is clicked, the function will be executed; adding a matrix as a table into the document.

Step 3.4: Add an Office Table to the document

1. In Home.html, locate the “Add Office Table” section (commented) and add the following HTML piece inside the div (section) tags. This is an Office UI Fabric styled button.

2. In Home.js, add an event handler (below the initialization of the Office UI Fabric components, in the ready function) for the click event of the button:

3. In Home.js, add the following function to add an Office Table object to the document:

4. Launch your Word add-in and test your work by clicking the Add Office Table button. When the button is clicked, the function will be executed; adding an Office Table object as a table into the document.

An TableData object (https://msdn.microsoft.com/en-us/library/office/fp161002.aspx) may seem identical to a matrix at first. In fact, they are a bit different when dealing with these two approaches in JavaScript. The TableData object splits the header and rows into different properties (making it easier to identify these two sections), whereas a matrix is simply a primitive array.

Step 3.5: Add Office Open XML (OOXML) to the document

1. In Home.html, locate the “Step: Add OOXML” section (commented) and add the following HTML piece inside the div (section) tags. This is an Office UI Fabric styled Dropdown (using the Jquery.Dropdown.js file) and button.

2. In Home.js, add an event handler (below the initialization of the Office UI Fabric components, in the ready function) for the click event of the button:

3. In Home.js, add the following function to add OOXML (read from the selected file) to the document:

4. Browse the files included in this blog post or head over to https://github.com/OfficeDev/Word-Add-in-Load-and-write-Open-XML/tree/master/C%23/LoadingAndWritingOOXMLWeb/OOXMLSamples. Get ahold of the listed OOXML files. You can open these files in any text editor and explore the OOXML data.
* Chart.xml
* SimpleImage.xml
* TableStyled.xml
* TableWithDirectFormat.xml
* TextBoxWordArt.xml
* TextWithStyle.xml
5. Create a new folder in your web project and name it OOXML in the Solution Explorer. Add these files into this folder by right-clicking it and choosing Add Existing Item….

6. Launch your Word add-in and test your work by clicking the Add OOXML button. When the button is clicked, the function will be executed; adding an OOXML piece (read from the selected file) into the document.

Step 4.1: Add the dialog

1. In Home.html, locate the “Step: Selected data dialog” comment and add the following HTML piece below it. This is an Office UI Fabric styled dialog.

2. Launch your Word add-in and test your work. You should find a dialog covering up most of your display area.

3. In Home.js, add two event handlers (below the initialization of the Office UI Fabric components, in the ready function) for the dialog. This will allow us to close it.

4. In Home.js, add the following functions to show and close the dialog:

5. Launch your Word add-in and test your work. You should be able to close the dialog using any of the two buttons.
6. In Home.css, add the following CSS piece to hide the dialog when your Word add-in has launched.

Step 4.2: Get selected data as plain text

1. In Home.html, locate the “Step: Get selected data (plain text)” section (commented) and add the following HTML piece inside the div (section) tags. This is an Office UI Fabric styled button.

2. In Home.js, add an event handler (below the initialization of the Office UI Fabric components, in the ready function) for the click event of the button:

3. In Home.js, add the following functions to get the selected data as plain text and then display it:

4. Launch your Word add-in and test your work by clicking the Get selected data (plain text) button. When the button is clicked, the function will be executed; getting the selected data as plain text and displaying it using the dialog.

Step 4.3: Get selected data as HTML

1. In Home.html, locate the “Step: Get selected data (HTML)” section (commented) and add the following HTML piece inside the div (section) tags. This is an Office UI Fabric styled button.

2. In Home.js, add an event handler (below the initialization of the Office UI Fabric components, in the ready function) for the click event of the button:

3. In Home.js, add the following functions to get the selected data as plain text and then display it:

4. Launch your Word add-in and test your work by clicking the Get selected data (HTML) button. When the button is clicked, the function will be executed; getting the selected data as HTML and displaying it using the dialog.

Wrap up

View the source code files included in this blog post for a final reference of how your code should be structured (if needed). You should now have grasped an understanding of a few possibilities of interacting with the Office context (a document in this case). In addition, you have also seen some of the styles and components included in the Office UI Fabric.

-Simon Jaeger