Building data and formatting features into MS Office applications using Office Add-Ins can be a crucial productivity boost to an organization. Now Microsoft has given us the ability to build Add-Ins faster and easier using the SharePoint Framework (SPFx).

What are Office Add-ins?

You will find them in the ribbon of Office apps. Below is the Add-ins pane found in the ribbon in Word. The default installation of Word includes the Wikipedia Add-in, a great example of an add-in, that you can see in your client installed Word:

Add-ins pane
ADD-INS: Add-ins can be accessed, installed, and managed from this tab in the Office application ribbon.

The history of building extensions to Office apps is long, extending back to leveraging Visual Studio Tools for Office: the venerable VSTO. With VSTO the only option has been to build and deploy server-side code with its attendant risk and longer deployment lead times. Also, it works only on Windows. The great advantage of building Add-Ins in the newer JavaScript and HTML model is that the Add-Ins work on all platforms and Office Online. Deployment is a fraction of the effort it once was.

Initially building MS Word Add-Ins using the Yeoman generator and the modern toolchain was not a part of the SharePoint Framework, but to any developer who has looked at both, they bear a striking resemblance to each other in many ways. To merge these dev workflows seems natural, efficient, and pleasing. 

Already Integrated to SharePoint

What do Add-Ins gain from being integrated into the SharePoint Framework? Mainly, the data connection to SharePoint. If your Add-In does not need a SharePoint connection, you can stick with using the standard Office generator in the Yeoman generator. But the connection to data in SharePoint is valuable. But wait, there’s more! SharePoint is a hosting platform as well with authentication built-in, so you can host your Add-In from SharePoint. With the introduction of building Add-Ins in SPFx, the step of hosting, and connection to SharePoint are now built into the Yeoman Generator!

Walk Through

Let’s build one. It is still a work in progress, a beta version. The Yeoman Generator will currently only build an Add-In for Outlook, and it is only available in the preview version of the generator, so we will invoke the beta version using “- – plusbeta” after the yo @microsoft/sharepoint command be sure to add –plusbeta as in the image below.

Yeoman Generator
Scaffold the application with Yeoman Generator

For the following generator steps, provide these answers:

  • SharePoint Online only (does not work on on-prem)
  • “Yes” to Do you want the allow the tenant admin to be able to deploy to all sites.
  • “No” to Will the components in the solution require permissions.
  • “WebPart” as the type. It is not strictly a SharePoint webpart, and likely another word will become available. For now, this is the option to choose.
  • No JavaScript framework, for the demo
Generator Image
Answer the generator’s questions.

When the project is finished scaffolding, open in VS Code, in the project, files will be a folder named “officeAddin” that usually doesn’t appear in an SPFx WebPart project. This is inserted when “—plusbeta” is added to the initial generator command. In this folder will be the manifest .xml file that is recognized as crucial in “yo office” scaffolded projects. This manifest is the pivotal point of configuration that connects your add-in to the internal operation of Word or Excel or PowerPoint or Outlook.

Manifest Window
The generated project as viewed in VS Code, when the –plusbeta parameter is added. Note the officeAddin folder and manifest inside.

Add type definitions by running the following:
npm install @types/office-js –save-dev
The webpart render code is still that which is generated for the default SharePoint webpart, so we will add some code to check for the Office context. Edit the webpart .ts file in the webparts folder. Add the following after the public render(): line:

Context Window
Add conditional code to determine the existence of the Office context.

Edit the title, subtitle and description lines to have placeholders for the output so that an Outlook message will display if our Add-in displays successfully in Outlook:

Span Classes

Deployment

At this point, deploying to SharePoint is a significant departure from the current Office Add-in deployment model. It is as easy as bundling and uploading to the app catalog in the same manner as deploying an SPFx webpart. Run gulp bundle –ship and gulp package-solution –ship, and then locate the .sppkg file in the SharePoint folder of your project.

Deploy the .sppkg file to the App Catalog in SharePoint. In the “Do you trust” dialog that appears, check the box to “make this solution available to all sites in the organization” to enable access to the Add-In from Office online applications (in this case, Outlook).

Manifest

The manifest file, whether generated in this SPFx workflow or from using the Office scaffolded project, is the critical piece that tells the Office application about your Add-In; where to find the code to render and what permissions it will have within your Office application. It can also be modified for what name will appear for your Add-in and what icon to display. For the client installed Office apps, the manifest must be given special Trust status within the application. The SPFx-to-Office-online version of this is more accessible: you upload the manifest file.

Add-Ins Goal

The vision for add-ins is to achieve:

  • Speed repetitive document tasks and creation
  • Have a native and intuitive feel
  • Use the same UI as Office (Fluent UI)

Researching for this post, I hoped that the story for Word add-ins was as far along as it is for Outlook and that SPFx would also provide for building Add-Ins for on-premises SharePoint. See the first video link below to see a demo of a Word add-in built with SPFx over a year ago; I think this capability is imminent. Stay tuned!

Links

SPFx Modern Web Development

SharePoint has been a widely adopted and popular content management system for many large organizations over the past two decades. From SharePoint Portal Server in 2001 to SharePoint Server 2019 and SharePoint Online, the ability to customize the user experience (UX) has evolved dramatically, keeping pace with the evolution of modern web design. SharePoint Framework (SPFx) is a page and web part model that provides full support of client-side SharePoint development with support for open sources. SPFx works in SharePoint Online, and with on-premises SharePoint 2016, and SharePoint 2019. SPFx works both in modern and classic pages. SPFx Web Parts and Extensions are the latest powerful tool we can use to deliver great UX!

Advantages of using SharePoint Framework

1. It Can’t Harm the Farm

Earlier SharePoint (SP) customization code executed on the server from compiled, server-side code is written in a language such as C#. Historically, we created web parts as full trust C# assemblies that were installed on the SharePoint servers and had access to disrupt SharePoint for all users. Because it ran with far greater permissions on the server, it could adversely impact or even crash the entire farm. Microsoft tried to solve this problem in SP 2010 by implementing Sandbox solutions, followed by the App Model, now known as Add-In model.

SPFx development is based on JavaScript running in a browser, making REST API calls to the SharePoint and Office 365 back-end workloads and does not touch the internals of SharePoint.

The SharePoint Framework is a safer, lower-risk model for SharePoint development.

2. Modern Development Tools

Building SPFx elements using JavaScript and its wealth of libraries, the UX and UI can be shaped as beautifully as any modern website. The JavaScript is embedded directly to the page, and the controls are rendered in the normal page DOM.

SharePoint Framework development is JavaScript framework-agnostic. The toolchain is based on common open-source client development tools such as npm, TypeScript, Yeoman, webpack, and gulp. It supports open-source JavaScript libraries such as Node.js, React.js, Angular.js, Handlebars, Knockout, and more. These provide a lightweight and rapid user experience.

3. Mobile-First Design

“Mobile first”, as the name suggests, means that we start the product design from the mobile end, which has more restrictions to make the content usable in the small space of a phone. Next, we can expand those features to a more luxurious space to create a tablet or desktop version.

Because SharePoint Framework customizations run in the context of the current page (and not in an IFRAME), they are responsive, lightweight, accessible, and mobile-friendly. Mobile support is built-in from the start. Content reflows across device sizes and pages are fast and fluid.

4. Simplified Deployment

There is some work to do at the beginning of a new project to set up the SPFx structure to support reading from a remote host. An App Catalog must be created, as well as generating and uploading a manifest file. If the hosted content is connected with a CDN (Content Delivery Network), that will also require setup. However, once those structural pieces are in place, deployment is simplified to updating files on the host location. It does not require traditional code deployments of server-side code, with its attendant restrictions and security review lead time.

5. Easier Integration of External Data Sources

With SPFx, calls to data from external sources may be easier since it’s web content hosted outside of SharePoint.

SPFx Constraints and Disadvantages

The SharePoint Framework is only available in SharePoint Online,  on-premises SharePoint 2016, and SharePoint 2019 at the time of this blog. SPFx cannot be added to earlier versions of SharePoint such as SharePoint 2013 and 2010.

SharePoint Framework Extensions cannot be used in on-premises SharePoint 2016 but only in SharePoint 2019 and SharePoint Online.

SPFx, like any other client-side implementation, runs in the context of the logged-in user. The permissions cannot be elevated to impersonate as an admin user like in farm solutions, CSOM (client-side object model) context, or in SharePoint Add-ins and Office 365 web applications. The SharePoint application functionality is limited to the current user’s permission level, and customization is based on that as well. To overcome this constraint, a hybrid solution implementation with SPFx to communicate with Application Programming Interfaces (APIs). APIs would be registered as SharePoint add-in, that uses the app-only context to communicate with SharePoint. For this communication between SPFx and API to work, the API would need to support CORS (Cross-Origin Resource Sharing) as the communication would be through cross-domain client-side calls.

SPFx is also not for long-running operations as it is entirely client-side implementation. The web request cannot wait longer until it gets the response from the long-running web operation. Hence for those processes, the hybrid approach with long operations can be implemented in Azure web job/function, and SPFx can get the update from those via webhook.

Developers coming from server-side will have a learning curve with entirely client-side development. But TypeScript is there for the rescue.

SPFx Comparison to Other Technologies and Models

SharePoint lists come in handy for many organizations when entering data, but customers always ask for the ability to display the data in some reporting format, such as a dashboard. Below we compare the different ways we can accomplish this and why SPFx is a good fit:

  • Classic Web Part Pages: If we do not want to use the SharePoint Framework, SharePoint 2019 still supports the classic web part pages. You can add content editor web parts and deploy any custom JavaScript/jQuery code. However, with this approach, uploading the Js files in the SP library and manually adding pages in a library become cumbersome. We may end up writing custom JSOM (JavaScript object model) code to make the deployment easier. Microsoft does not recommend this approach, and there is the possibility that this will no longer be supported in the future. Also, with this approach, if you want to render any custom tables, you need to write custom code or use a third-party table. Using SharePoint Framework, we can easily use Office UI Fabric React components like Details list.
  • Custom App: We can design custom applications to deploy in the cloud, which can read the data from SharePoint. The challenge is that each customer environment is different. It’s not always easy to connect to SharePoint from the cloud in a production environment, especially with CAC (Common Access Card) authenticated sites.
  • Power Apps/LogicApps: With newer technologies such as Power Apps, Logic Apps, and Flow, we can design custom SharePoint Forms and business logic and connect to SharePoint using the SharePoint connector. In a production environment, it is not easy to get connection approved and to connect with on-premises data. Power Apps and Flow require the purchase of licenses.

Using SPFx, we can quickly design the dashboards using Office UI Fabric components. For deployment, we do not need to write any custom utility code, SharePoint framework package can create the lists and libraries as well.

Wrapping Up

We hope this blog provided an SPFx overview and its great functionalities. Please look forward to our next blog post (Part II) in developing and deploying custom SPFx Web Parts, Extensions, and connecting to API’s/Azure in SharePoint Online and SharePoint 2019!

Additional Links to get started in SPFx