Understand & Get Started with the SharePoint Framework development Story

Andrew Connell

0 comments

Are you new to the SharePoint Framework?… In this eBook you will learn about your toolset for SPFx development: Node.js, NPM, Yeoman, VS Code, Webpack…but most importantly you’ll learn what you can ignore, and what to focus on.

SharePoint Framework Development allows you to develop using modern web development skills, which can be applied to any other development project. You can take the skills which you learn in a SharePoint Framework development project, learning how to use open-source frameworks, React and other technologies all of which can be applied to other web projects.

In this eBook companion to the Virtual Summit session, we will be looking at what the SharePoint Framework is, why we need it, understanding the development toolchain, and finally building client-side web parts.

History of SharePoint Development

SharePoint development, much like the product itself, has evolved over a number of years. Let’s take a quick look at the journey to help us understand how we have arrived at the SharePoint Framework.

SharePoint 2003

The initial versions of SharePoint Portal Server were based on .NET framework 2.0. Customisations were developed using VB.net or C# and were only able to use a server-side API, no client-side API existed. Any customisations that were developed needed to be full trust solutions, but as no packaging framework existed, everything needed to be deployed manually.

Microsoft Office SharePoint Services 2007

MOSS 2007 was based on the next version of .NET, using .NET version 3.0 but still only offered customisations using the server-side API. Still, customisations ran as full-trust solutions, however, a new deployment mechanism was added, whereby they could be packaged up as solutions and then deployed using the new feature framework.

SharePoint 2010

SharePoint 2010 changed the development model by introducing the concept of sandboxed solutions. These solutions were partial-trust which meant that you didn’t need to deploy them to the server, you could upload the solutions directly to a site collection. This did mean however that solutions were limited only to a single site collection.

SharePoint 2010 also introduced the client-side object model which allowed remote calling to SharePoint, so again removing the need to install code onto the SharePoint server itself.

SharePoint 2013 & SharePoint Online

With SharePoint 2013 came a hugely improved set of client-side APIs which also opened the door to two new ways of deploying customisations: SharePoint Hosted Add-ins and Provider Hosted Add-ins. SharePoint Hosted Add-ins were centred around SharePoint components such as lists, libraries, pages etc. The logic is implemented using JavaScript rather than using .NET languages as they had been in the past.

Provider hosted add-ins, on the other hand, relied on a two-tier model, where the logic was stored and executed on a remote server, using the client-side object model to call back into SharePoint, while the presentation of the add-in appeared directly within SharePoint. Whilst this gave a lot of flexibility in terms of being able to develop customisations, the implementation within SharePoint wasn’t great as add-ins would effectively run as a subsite of the site collection and be viewed using an iFrame on the SharePoint page.

This period of development also saw continued development in the client-side APIs, and developers started to move towards JavaScript injection. Content Editor Web Parts and Script Editor Web Parts were commonly used to execute JavaScript to interact with and display data from SharePoint. Customisations created in this method were often prone to errors, weren’t repeatable, and were at risk of not running if a browser policy would not allow JavaScript.

This method of development became more and more popular, and this shift in development methodology was noticed by Microsoft. This change of methodology is what gave birth to the modern way of developing customisations, using the SharePoint Framework (SPFx).

What is the SPFX

It was recognised by Microsoft that the most popular way of applying customisations to SharePoint was by using Javascript injection, and by utilising the client-side object model and REST APIs. Microsoft also realised that the ways to customise which had been provided in the past had not been wholly adopted by the developer community. The SharePoint Framework was designed to be a customisation framework that came up with solutions to the issues of the past.

SharePoint Framework provides full support for client-side customisations as well as giving us easy access to SharePoint data through an API that handles the authentication for us. This means that developers don’t need to worry about authenticating against the REST APIs, i.e. reaching out to Azure AD to get an access token which is then included in any calls, because the code runs within the context of the user who is logged in.

The new SharePoint Framework model embraces the modern web development stack, which means that developers no longer need to have specialist SharePoint skills to be able to develop. The skills which modern web developers have can be easily applied to SharePoint Framework.

Customisations created in the SharePoint Framework are also very flexible, as they work in both classic and modern sites. It should be noted that SharePoint Framework web parts will work in classic sites as well as modern sites, however classic web parts will not work in the modern experience. The only way you can develop for both experiences is using the SharePoint Framework.

The SharePoint Framework isn’t just a development methodology being used by third-party developers. Microsoft is also using the SharePoint Framework for developing their web parts, which means that they will find the same limitations that, we as a non-Microsoft developer. If they find those limitations, they are likely to resolve the issue which then benefits everyone.

Now that we understand what the SharePoint Framework is, we need to ensure that we have the correct tools to support the development

Tool chain

Regardless of what tools you use for the actual development, there are resources which you will use throughout the process of creating your customisations.

Workbench

The workbench is a virtual SharePoint page that allows you to create and validate the basic functionality of your customisation without physically touching SharePoint. When launched, it actually launches a web page on localhost.

Once you have confirmed your basic functionality using the workbench, you will need to deploy it to SharePoint to ensure that any data interactions are working correctly.

Developer Tenant

You don’t necessarily need a developer tenant; however, you can get one for free from Microsoft which gives you access to the full capability of Office 365. The idea is that you have a full-blown SharePoint environment where you can test your web parts which are isolated away from any production tenancies which your organisation may have.

https://docs.microsoft.com/en-us/office/developer-program/office-365-developer-program

Having a tenancy, such as a developer tenancy, means that you can then test your web part against data within SharePoint through the SharePoint workbench. The difference now is that rather than the workbench being hosted on localhost, you would access it from a SharePoint Online site by accessing a URL similar to:

https://your-sharepoint-tenant.sharepoint.com/_layouts/workbench.aspx

Now we need to look at the tools which we will use to develop our customisations.

Tools

Earlier we looked at the evolution of SharePoint and how the development practices changed. The tools which we use have also evolved. Let’s first of all look at what we would use in traditional development and look at the technologies which have now replaced them.

Classic DevelopmentModern Development
Microsoft .NETNodeJS
NuGetNPM
Visual StudioVisual Studio Code
Yeoman
C#TypeScript
MS BuildGulp
 Web Pack

Node.js

Node is a JavaScript runtime that allows us to run JavaScript on a server. This is the equivalent of us installing .NET Framework in a classic development.

There are different versions of Node.js available, so always check on the SharePoint Framework documentation to confirm which version you should be using. Generally, it is recommended that you use the Long-Term Service (LTS) release.

NPM

Every development toolset has the ability to create or use packaged code, including any dependencies for the code. In traditional development, this took the form of NuGet packages, however, in modern development we use NPM to install and manage those packages from the command line.

Visual Studio Code

Visual Studio Code is a source code editor developed by Microsoft for Windows, Linux and macOS. It includes support for debugging, embedded Git control, syntax highlighting, intelligent code completion, snippets, and code refactoring. This is an extremely lightweight development environment that serves as an alternative to the full-blown Visual Studio application. It is designed to support modern web development, having a built-in command-line console so that you can easily interact with commands such as NPM.

Yeoman

Yeoman is the scaffolding tool that will create the basic structures needed to support the development of the customisations.

A screenshot of a cell phone

Description automatically generated

Think of this as going to New Project within Visual Studio, which would automatically create the basic folders and files needed to get the basic customisation up and running.

TypeScript

TypeScript is an open-source development language that is based on JavaScript, however, it introduces a large number of improvements such as the ability to assign type information in the same way that you can with .NET development. When TypeScript files are compiled, they generate the fully formed JavaScript files which can then be executed within the customisation.

Gulp

Gulp is a modern development equivalent of build jobs which we used to use within .NET development. The idea is that it will provide levels of automation around the compilation, packaging and deploying of your customisations so that you don’t have to do everything manually.

Node Version Manager (Optional)

There are actually two different projects relating to the Node Version Manager (NVM). NVM is actually a Mac/Linux only project, therefore if you are a Windows user then you will need the Corey Butley version of NVM which can be accessed from the following link:

https://github.com/coreybutler/nvm-windows

NVM provides the ability to easily switch between different versions of Node.js, which is particularly useful if you want to test modules with the latest version of Node without having to remove your more stable release version.

Full install instructions are available from the Corey Butler GitHub repository.

One of the most useful commands available is to check what version of Node is currently installed, which can be found by running the command: node -v

Using NVM, I can then get a list of all available versions of Node, using a command which will speak to the Node.js website API. What gets returned is a list of all versions of Node which I can install.

To do this we need to run the following command:

nvm ls-remote

This will return the entire list, including highlighting specific versions such as LTS releases as well as showing which version you currently have running.

Getting Started with creating a web part

There are a number of very good guides available on the SharePoint Dev pages (aka.ms/spdev-docs) which will guide you through the set-up process for your environment. That will guide you through the installation of Node.JS including advising the version that you should install, right through to creating your first web part.

Creating the web part

Step 1 – Create the directory (if you haven’t already created it) by using the command:
md helloworld-webpart

Step 2 – Navigate to the folder by using the command:

cd helloworld-webpart

Step 3 – Create a scaffolded SharePoint Framework Web part by using the Yeoman generator. Enter the command:

yo @microsoft/SharePoint

Step 4 – Enter the name of the web part

Step 5 – Select the version of SharePoint which you are going to be developing for. Notice here that there are different options such as SharePoint 2016. This is because there are different versions of the SharePoint Framework available on SharePoint 2016, and on SharePoint 2019 compared to SharePoint Online. The difference in the versions is because SharePoint Online is consistently being updated when compared to on-premises servers, and the same can be said for the SharePoint Framework.

Step 6 – Enter the requested information in each question or just accept the defaults

Step 7 – When prompted for the framework, select no framework. Once we have completed the questions, the web part creation will take place. You will see that there are resources being pulled down to your local machine. This is where modern development is most notably different. In classic, all of the files and configurations required by the project already exist, whereas, in our new development environment, they are downloaded as part of the creation process.

Step 8 – Once the creation is completed we have got the bare bones of the web part which we can now open in our chosen editor.

Step 9 – When we open the files in a tool such as VSCode, we will see the files and can now begin our development.

HelloWorldWebPart.ts

Location: src/webparts/helloWorld/HelloWorldWebPart.ts

This file is a TypeScript file that gets compiled to JavaScript. It contains a number of import statements which are the equivalent of Using statements from C# development.

The main class is the HelloWorldWebPart class which contains a number of methods, the first being the render method. This method contains the code to determine how the web part will look and feel, notice that you can create your HTML here to stipulate the web part layout.

The second element to draw your attention to is the getPropertyPaneConfiguration method which allows you to define what is seen when you edit the web part in SharePoint and get access to the properties screen. In this example, we are just going to get a description.

Now that we have created the web part, let’s run it.

Running the Webpart

In order to see our part, we now need to use a Gulp task to fire up the local workbench and view the web part. Whilst the workbench is intended to act as a “preview”, any functionality which you write into it will be available for you to try here.

In order to build the project, compile the JavaScript and create a local website to view the web part, we run the command:
gulp serve

The Workbench

Once the gulp task runner has finished processing, your default browser will launch and will open the local workbench.

It looks and feels like a modern SharePoint page, where I can go and add my web part. To do this click on the + on the page, and you will see our web part created. Simply select it, and it will appear on the page. We can also interact with the web part by editing the properties, which will open the properties blade and allow me to change the description text appearing in the web part.

A really cool thing relating to the SharePoint Framework is that if you leave the browser open and return to VSCode, you can update your web part and those changes will automatically flow through into your workbench so that you can (almost) immediately see your modifications.

What else can I create?

As well as being able to create web parts, there are also other customisations that can be developed using the SharePoint framework.

Application Customizer

This will allow us to add JavaScript to a page such as being able to add Google Analytics, or even adding HTML to placeholders that are available on the page i.e. at the top or bottom of the page. This is the replacement for ScriptLinks from classic development.

Field Customizer

Field customizers are the modern equivalent of JSLink, whereby we can apply some custom rendering to a cell within a list. Unlike SPFx web parts, this will only work on modern lists. Should you wish to achieve the same goal on a classic site, then you will need to use JSLink.

Command Set

Command Sets are similar to custom actions from classic development and allow us to add buttons to the toolbar or the context menu on an item or document. You can specify the conditions when a command becomes available, e.g. whether it appears when no, one, or multiple items are selected.

Summary

We have now had a look at what we need to do to get started with the SharePoint Framework, but more interestingly where it has come from. The fact that Microsoft realised that developers were using JavaScript injection for their customisations prompted the creation of this modern development practice using the SharePoint Framework.

We looked at the key tools which we need to be able to create our customisations, including Node.JS, Yeoman, VSCode as our development environment, Gulp etc.

We then went through a basic introduction to creating a SharePoint Framework web part which started with creating a folder and then using Yeoman as the scaffolding tool, to create the folder structure and relevant files needed to get us up and running. Remember that there are different versions of the SharePoint Framework needed for SharePoint 2016, SharePoint 2019 and SharePoint Online, so ensure that you select the right version when creating.

Once we had generated our web part, we then previewed the web part, in an interactive sandbox called the Workbench which runs locally on the development machine. Whilst the webserver is running, any changes made to the web part will automatically be made available to the workbench.

Finally, we looked at how the SharePoint Framework can be used to customise other areas of a SharePoint page through the use of extensions. Extensions allowed us to add additional content to placeholders using Application Customizers, change the look and feel of a cell in a list by using Field Customizers, and Command Sets which allow us to create additional options on toolbars and item context menus.

Further Reading

Full documentation for the SharePoint Framework, including tutorials and guides, can be found at the SharePoint Developer site https://Aka.ms/spdev-docs

0000-00-00 00:00:00


Leave a Reply

Your email address will not be published. Required fields are marked

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}