First look at SharePoint Framework

Jurgen Wiersema |

Background

In the history of development for SharePoint many different development platforms have been introduced over the years. Among these were full trust solutions, bin-folder deployments, sandboxed solutions, Client-side object model, the different models for building Add-ins and JavaScript in a script editor webpart. And shortly we will have yet another way to customize SharePoint On-premises and Online, the SharePoint Framework (SPFx)!

This new development model does not really bring new capabilities with it but is instead (finally) a real delivery platform for building JavaScript solutions in a structured way. JavaScript has always been present in Web development and has, in recent years, matured and even taken over server-side development through NodeJS. Frameworks such as AngularJS, KnockOutJS and React are standard tools for front-end development since the introduction of highly user friendly Single Page Applications. The SharePoint framework is aimed to bring SharePoint development into the realm of the ‘common’ web developer in order to greatly increase the number of developers that can customize the platform.

This document describes my first experiences and thoughts on the new development model and the repercussions of it for SharePoint developers.
Introduction

SPFx will be available on SharePoint Online in Q4 of 2016 and later be deployable to SP2016 through a Feature Pack. The introduction in SharePoint Online will go together with several other changes among which is the new responsive page model. The new page model changes the way a user can edit the content of pages, greatly improving the user experience because no page reloads are required. This is the way almost all big web platforms work and soon SharePoint will too!

Beside the responsiveness of the buttons and other controls to edit pages, the pages themselves will also be designed in such a way that they are mobile accessible. The pages will respond to the user’s device to show an optimized view of the page for that screen. Finally, the new page model allows for almost full-screen customization of the page, only a small portion is reserved for the ribbon and a side menu. This makes it easier for developers to make SPAs in O365 and increase the usability of SharePoint. SPFx WebParts will be available on the new page model, the older ‘classic’ type pages and a little later also on publishing pages.

The SharePoint framework webparts are built with a multitude of web development tools such as NodeJS and Yeoman, which will be discussed below. The tools can also minify and package the SPFx webpart as an .spapp package which is deployed to your farm via the App Catalog. Microsoft’s idea is that you deploy the source files of your webparts to a publicly accessible CDN location. This should make the files quickly accessible to end-users all around the world, and is a more maintainable deployment location than in Style libraries or masterpage galleries scattered throughout your entire SharePoint farm, where they might be deleted or corrupted by power users in the business.
The project templates for building a SPFx WebPart supports several JS frameworks (KnockOutJS and React) for development and more will follow. This nudges developers to start using a framework which will increase stability and maintainability of the code.
Microsoft mentions the following characteristics of SPFx:

  • It runs in the context of the current user and connection in the browser. No iFrames.
  • The controls are rendered in the normal page DOM.
  • The controls are responsive and accessible by nature.
  • There is a life cycle that the developer is involved in.
  • It’s not just render, but load, serialize _and _deserialize, configuration changes, etc.
  • It is framework agnostic – You can use any browser framework that you like – React, Handlebars, knockout, angular – take your pick.
  • The tool chain is based on common open source client development tools like npm, TypeScript, yeoman, webpack, gulp, etc.
  • Performance is key.
  • SPFx client-side solutions that are approved by the tenant administrators (or their delegates) can be used by end users on all sites – even self service created sites like teams, groups, personal, etc.
  • Can be deployed in both classic web part and publishing pages as well as the modern pages.

Tooling

The necessary tooling for building SPFx webparts is vast and for most SharePoint developers an entirely new world. However, it is the standard for common web development and will bring new people to SharePoint but also open up new opportunities for SP developers that are willing to learn something new.

First of all you will need NodeJS and its package manager NPM. Through the package manager you will need to install the project generator (Yeoman) and the task handler (Gulp). When you then install the Yeoman project template for SPFx webparts you will get the SharePoint workbench with it. The SharePoint workbench is a local development tool that you can use to locally develop and test a SPFx WebPart. In order to be able to deploy a SPFx webpart to Office365 you will most likely want to use an Azure storage account with CDN endpoint. Any CDN will do but the Yeoman project template includes the gulp tasks to deploy to an Azure storage account automatically. The dependence of SPFX Webparts on a CDN (and possibly API’s for advanced scenarios) may provide a boost to Azure usage for companies using Office365 which is a welcome side effect in my book.

When you have installed these prerequisites and scaffold a SPFx project you can start developing. Of course you can use Visual Studio for this, but actually lightweight editors such as VS Code or Sublime should be preferred. Besides the editors you better keep your command line open because that is the way to run and debug the code! Through the defined Gulp tasks in your project you build, run, package and deploy your project through command line options such as build, serve and package-solution.
SPFx development defaults to using TypeScript as the preferred JS dialect. It is probably harder to try and develop a SPFx webpart without TypeScript so this new development model is another big push of TypeScript by Microsoft. You are also encouraged to try to use the Office Fabric UI controls as much as possible. Office Fabric UI is a set of common HTML+CSS controls that you’ll often want to use on Office365. Next to this SASS (‘programmable’ CSS) is something you will want to try and conquer in order to speed up and structure the front-end development.
The included JS frameworks with the Yeoman template are React and KnockOutJS. More will follow.

Framework review

The previous section shows the great amount of new tooling that is required to be a successful SPFx developer. The reliance on open source, common web development tools and frameworks has SharePoint development enter a new chapter in its development history. The introduction of SPFx may beckon a whole new group of developers towards SharePoint, and likewise push the ‘old’ SharePoint developers into the Wild West of structured JavaScript development. It makes possible a more mature and professional way of developing client-side applications on SharePoint. It steers away from the practice of inline scripts on a page, and towards packages that can be successfully maintained and deployed.

Next to this, this new way of development should make it easier for web designers and developers to work together because of the reliance on SASS, the Office Fabric UI and editors like VS Code or Sublime. Prototyping apps is also faster and easier thanks to the SharePoint Workbench, making rapid development and design cycles possible. One possible downside to this is that this model is not very open to the power users/functional developers that are used to using the script editor web part and deployment into the style library. Because of the heavy reliance of SPFx on all the tools and frameworks it might be difficult for these types of people to step into SPFx development. The biggest threat to the success of SPFx (as with the other SP development models) will be that not all SP developers will want to adopt the model and will keep doing their JavaScript development in script editor webparts because it is the easiest path to delivery. This could mean a messy implementation and difficulty in maintaining Office365 solutions.

The user will likely also gain big from the SPFx framework and the new page model. Responsive and mobile accessible pages are a hard requirement nowadays and finally this will also be possible in SharePoint. Because also all of the new pages can be customized, designers and developers will be able to deliver completely unique experiences that are highly user friendly without going against best practices in SaaS/Office365 development. Next to this the new document library pages will also become customizable thanks to SPFx.

SPFx code should be deployed via Content Delivery Networks according to Microsoft because of the decreased loading times and because it facilitates the maintenance of the scripts. Also, the SPFx will allow easy integration with Microsoft Graph API’s and can also be used to talk against custom WebAPI’s that provide functionality that can only be achieved by server side code. For example, running in a different context than that of the current user or safe communication with on premises applications. Because of all this, SPFx may push companies to get Azure subscriptions or make more use of their existing subscriptions by building custom WebApis and integrating them with Office365.

Tips and tricks

When the SharePoint Framework and the new page model has been introduced in SharePoint Online and On-premises and you start a new project it is advised that you still build a development VM. Even though you can use a non-server OS and it uses only lightweight applications it will still be advisable to use a dev VM for each client. In this way you can be sure that it stays stable and that all developers work with the same version of Node, NPM, Gulp, Yeoman, the SPFx yeoman template, etc. It is easy to start developing on your own desktop, but when time progress and you get more projects using SPFx, you will start to be required to upgrade these tools and you may end up with old projects for other clients not working anymore. Besides creating a full fledged (probably Windows) VM, you can also use the popular Docker container software. Waldek Mastycarz has released a Docker image specifically for SPFx development. This is also an easy way to try out SPFx without installing all the prerequisites. Docker is a great way to virtualize an environment, especially when you can use a tried and tested Docker image.

In order to become proficient at using the new tools a developer has quite a steep learning curve ahead of him/her. It is advisable to get at least a working grasp of the node modules used, the gulp tasks, command line options and one or more of the supported JS frameworks like React or KnockOut. An explanation of the node modules included in the SPFx project template should be delivered soon by the MS team that is responsible for it. The Gulp tasks are also included in the project template, so get to know them and perhaps even learn how to add new, custom Gulp tasks yourself in order to speed up the development cycle. The SPFx also provides a great opportunity to get to know TypeScript and build more reliable JS solutions. Lastly, you will need to know what is in the Office Fabric UI pack in order to increase the maintainability of your designs.

In order to make full use local development cycle using the SharePoint WorkBench, it is advisable to include mock data in your SPFx webpart. In this way you can quickly show you app locally before it is on Office365 and iterate faster during development. Using mock data is done as such:
1. Create models can serve to define the data structure of the data to show
2. Create a MockHttpClient class
3. Add GetMockData and GetRealData methods to webpart class
4. Import environment type
5. Add RenderDataAsync method that switches between getting mock and real data based on environment type and renders the data
6. Add call to render data in the main render method (also add html container to provide location for rendering the html)
See the Connect to SharePoint documentation for in-depth guidance.
The following Gulp tasks are included in the Yeoman project template and can be found in the folder /node_modules/@microsoft/sp-build-web/lib/index.js

  • Build
  • Bundle (option –ship)
  • Deploy-azure-storage (uses /config/deploy-azure-storage.json )
  • Package-solution (option –ship uses /config/write-manifests.json )
  • serve Use option –ship in bundle and package-solution to deploy to CDN.

SharePoint Framework webparts allows a user to fill in properties of the webpart in order to customize the appearance or function of the webpart. A SPFx webpart contains a manifest file to set the most appropriate default values for these properties. An attempt at making the operation of setting a web part property user friendly is to make the properties reactive to user input by default. MS went a little overboard with this, because this means every time you type, the code in the SPFx webpart get executed again. This is not very usable when the variables are used in web service calls, which will often be the case. Because of this you will almost always want to disable the reactive nature of the web part properties. This is done by overriding a property in your SPFx webpart’s code like so:
Set property disableReactivePropertyChanges to true (non reactive properties)
protected get disableReactivePropertyChanges(): boolean { return true; } The yeoman project template for SharePoint Framework apps contains a great deal. Below I mention the most used files and their use.
What are the files in the yeoman template for?

  • IHelloWorldWebPartProps.ts (web part properties interface class)
  • HelloWorldWebPart.ts (the webpart itself inclusing render method, property pane code, import statements)
  • HelloWorldWebPart.manifest.json (default value of webpart properties)
  • HelloWorld.module.scss (styling for your webpart) SharePoint Framework webparts allows the developer to make use of a handy pageContext variable that contains some useful properties shown below.

WebPart.context.pageContext variable

  • SPSite guid
  • SPWeb guid, absolute url, relative url, title, permissions
  • SPUser: email, displayname, loginname Currently the actual properties of the (publishing) page do not seem to be included in this variable. It would be very useful for the developers when the current page’s properties could be easily read so they can be used in the code in order to make each page unique. For example, showing the date of publication, categories/tags of the page, related articles/people, etc.

Something to keep in mind when starting development is that the tools like Gulp and NPM are not very fond of a deep folder structure. So make sure you start your projects very close to the root folder.
When you want to try out SPFx right now, and this might occur after introduction as well if it is updated, make sure you’re using the most recent version of NPM, Yeoman and the Yeoman project template. Breaking changes may have been introduced in a newer version. MS promises that after SPFx goes GA they will not introduce breaking changes anymore. An example of an error you might get is the following. Instructions for updating your tooling follows.

Error:
Error loading debug manifest script. (Error: http://localhost:4321/temp/manifests.js did not call System.register or AMD define. If loading a global module configure the global name via the meta exports property for script injection support. Error loading https://localhost:4321/temp/manifest.js) Ensure loading unsafe scripts is allowed.
Update tooling:
npm update yo –g (update yeoman) npm update -g @microsoft/generator-sharepoint (update yeoman sharepoint framework app generator)
yo @microsoft/sharepoint (new project)
gulp serve (run template project)
In chrome you’ll get security warnings. Go to advanced -> progress to site. SharePoint workbench inside Office365 will work again as well.

Conclusion

Hopefully this document has shown what a useful development paradigm the SharePoint Framework might become. Everything stands or falls with community adoption. However, SPFx might actually lead to new communities evolving around customization of Office365/SP2016. It may also provide new opportunities for old-school SharePoint developers if they adopt the platform. It will be exciting to see the range of solutions that will be developed using this new development model!

Show Comments