Create Client Side webpart using SPFX framework

By this time, you must have heard about the new SharePoint Client side framework (SPFX). Briefly describing, this framework allows you to create client side web parts that can be deployed to tenants in SharePoint online or SharePoint 2013 on-premise and can be added to both classic and new modern SharePoint pages. For detailed information about this framework you can visit microsoft’s documentation here – https://dev.office.com/sharepoint/docs/spfx/sharepoint-framework-overview.

Personally, from the development perspective, I like this framework for two reasons – Firstly, after the introduction of SharePoint App model, there was no solid approach to package and deploy my javascript based client side work to SharePoint sites. Yes, I can have a sandbox solution with module elements that can deploy my custom javascript and css files to sharepoint sites but during development to test your javascript files you need to put your custom js code in some script editor webpart in some test site first to make sure it is working as expected. Another option is to create sharepoint apps/add-ins but as the app runs in the context of the app web, as a developer I need to make special adjustments to access resources from host web. On top of that ensuring  your app uses the same style as the host web was another challenge as it runs in an IFrame. Not to mention the challenge in upgrading the app after it is deployed. SPFX webparts runs in the context of the page it is deployed to which solve many problems for the developer. The development tools available to build spfx based webparts  allows me to setup a project structure that provides in-built support such as intellisense with javascript frameworks like React and NodeJS plus you can configure it to use Angular 2.  To test these webparts before final deployment, you can use sharepoint workbench which is hosted in sharepoint to preview and test your webparts in SharePoint context that allows you to interact with sharepoint data (We will see more about this later in this blog). Secondly – it seems that this development model is going to stay for a while as SharePoint team is using this same framework to enhance it further. This is a sigh of relief for me as (hopefully!) I don’t have to learn another development model after this for sometime.

Now, lets jump in and see how we can develop a webpart using new sharepoint client side framework, also called SPFX. In my post I will take a real life example to create a “TasksAlert” webpart as shown below. This webpart iterates through all the subsites under the site it is deployed to and display a tile with the link to the subsite if logged-in user has any task assigned in the Tasks list in that subsite. As this web part would be using JQuery and SharePoint JSOM, you would learn how to configure the project structure to also provide support for JQuery library and SharePoint Client object model.

image2

I have divided this walkthrough into 5 sections –

  • Setup the development environment
  • Create the web part Project
  • Add support for JQuery and SharePoint JSOM
  • Preview and Test the webpart
  • Package and Deploy the web part

Setup the development environment

  1.      Install NodeJS – Download and install NodeJS from here – NodeJS. If it is already installed, make sure you are running the latest version by running this – node -v.
    Make sure npm is up to date by running this – npm install –g npm
  2.      Install Yeoman and gulp – To install Yeoman and gulp, run this – npm install –g yo gulp
  3.      Install Yeoman SharePoint Generator – To install Yeoman SharePoint generator, run this – npm install –g @microsoft/generator-sharepoint

Please note you need to run the above commands in Node.js cmmand prompt.

Create the web part Project

Create a new project directory in your preferred location – md TasksWebpart

Go to the project directory – cd TasksWebpart

Create a new Tasks web part by running the Yeoman SharePoint Generator – Yo @microsoft/sharepoint

When prompted:

Enter the solution name as TasksWebpart) and press enter

Select Use the current folder for where to place the files and press enter.

For now, choose No Javascript web framework and press Enter.

Keep the default TasksWebpart as your webpart name and Press Enter.

Type any web part description and press Enter.

At this point, Yeoman will install the required dependencies and scaffold the solution files. This might take a few minutes. When scaffold is complete, it should look like this –

image1

After the Project structure is created, take a time to look at it by opening the TasksWebpart folder in Visual Studio Code.

Add support for JQuery and SharePoint JSOM

Support for JQuery – 

In config/config.json, under “externals” section add below code:
“jquery”: {
“path”: “https://ajax.googleapis.com/ajax/libs/jquery/3.1.1/jquery.min.js”,
“globalName”: “jQuery”
}

Add jquery type definitions by running npm install –save @types/jquery in nodejs command prompt.

Import jquery variable into TasksWebpart.ts file : import * as $ from ‘jquery’;

Now, you can use “$” in your code.

Support for SharePoint Javacript CSOM – 

In config/config.json, under “externals” section add below code:
“sp-init”: {
“path”: “https://siteurl/_layouts/15/init.js”,
“globalName”: “$_global_init”
},
“microsoft-ajax”: {
“path”: “https://siteurl/_layouts/15/MicrosoftAjax.js”,
“globalName”: “Sys”,
“globalDependencies”: [
“sp-init”
]
},
“sp-runtime”: {
“path”: “https://siteurl/_layouts/15/SP.Runtime.js”,
“globalName”: “SP”,
“globalDependencies”: [
“microsoft-ajax”
]
},
“sharepoint”: {
“path”: “https://siteurl/_layouts/15/SP.js”,
“globalName”: “SP”,
“globalDependencies”: [
“sp-runtime”
]
}

Run npm install @types/microsoft-ajax @types/sharepoint –save-dev.

Then, tsconfig.json should look like this –
“types”: [
“es6-promise”,
“es6-collections”,
“webpack-env”,
      “microsoft-ajax”,
      “sharepoint”

Finally, Add these after the last import statement  in your webpart .ts file –
require(‘sp-init’);
require(‘microsoft-ajax’);
require(‘sp-runtime’);
require(‘sharepoint’);

Preview and Test the webpart

Even though we haven’t added any logic to the webpart but still run the command below to see if it compiles and opens up in browser without any problem –

gulp serve -o

This should open localhost workbench in default browser. It should look like this –

image3

As a next step, download this zip file – TaskWebpart.

Copy/replace the following methods from “TasksAlertWebPart.ts” file to your webpart .ts file –
render, initialize, getSubSites and onListsSuccess

Replace the whole .scss file in your project structure with what’s in “TasksAlert.module.scss” file.

Now, run gulp serve -o  again. Now, as the localhost workbench is not the sharepoint site, your webpart wont do anything. To test your webpart under the sharepoint context, we can use the workbench available for any sharepoint site. You can access  sharepoint workbench by  navigating to – http://siteurl/_layouts/workbench.aspx. In my case, I would navigate to – https://manvir223.sharepoint.com/_layouts/15/workbench.aspx to test this webpart. Just add your webpart to the page and you should see the webpart in action and should look something like this. Obviously, your subsite titles would most likely be different than mine 

image2

Package and Deploy the web part

Before you package your solution, it’s a good idea to always run gulp clean to clear everything in the package folder which is “SharePoint/Solution”.

Please note the JavaScript files, CSS and other assets are not packaged and you will have to deploy them to some SharePoint library or external location such as a CDN. 

In our case, we will store these resources in document library. To see how to store resources in some CDN, please visit this – Deploy to CDN.

Before we package the solution, go to write-manifests.json under “config” and update the CDNPath to some document library as shown below –
{
“cdnBasePath”: “https://siteurl/sites/SPFX/SiteAssets”
}

Now, run this command – gulp bundle –ship
This will create the bundle files under “temp/deploy” folder

Now, create the package by running – gulp package-solution –ship
This will create the package file under “sharepoint/solutions” folder.

Now, copy whatever inside “temp/deploy” folder to the document library mentioned as a cdnbasepath.
Upload the package file (.sppkg) from Solutions folder to the Apps for SharePoint library inside app catalog site.

That’s it! Now, no need to run any node server using gulp. Just go to any site and add a TasksAlert  app by navigation to site contents. Once the app is installed, you should be able to add it to any page. Look this app under “Under development” group in the ribbon while adding app. To change the group, make a change in the “HelloWorldWebPart.manifest.json” as shown below –

image4

Trackbacks

Leave a Comment

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