Hi SharePoint fellows,
In this post, I would like to demonstrate how easy it is to implement a really engaging and modern user experience in a SharePoint Framework client-side WebPart.
The purpose of the WebPart is to present a Kanban Board view of a configured list. The user will be able to change the items from a status to another using drag-and-drop.
- The source list will be configured through the WebPart properties.
- The statuses are the choices of a ChoiceField in the list.
- The status ChoiceField to use will also be configured through the WebPart properties.
The UI will dynamically generate a column for each status in which each task will be contained in a tile. We will leverage the natively supported Office UI Fabric CSS framework that will make our UI fully responsive and in line with the SharePoint modern look and feel.
For the drag-and-drop capability, we will use the popular jQuery UI library. For manipulating the SharePoint data, we will use the sp-pnp-js library.
This will be a very simplistic and, I would roughly say, “quick and dirty” implementation. The purpose here is to focus on possibilities and ease offered by SPFx. You will see it is possible to build a real engaging WebPart with SPFx within 2 hours (1 hour for developping, 1 hour for CSS fine tuning 😉 )*.
(* Obviously, for a real clean and scalable project, we would prefer a robust implementation with a well defined project structure, separation of concerns,…)
Let’s code !
Create a folder named kanban-webpart-demo/, open it from a console, type the famous yo @microsoft/sharepoint and enter the values as following
When the scaffolding process is finished, let’s first install the required packages. In the console, type the following command:
$ npm install jquery jquery-ui sp-pnp-js –save
This Kanban Board will display and manage task items, we will then declare an interface with the relevant properties for us. In the kanbanBoard/ folder, let’s create a models/ folder that will contain a ITask.ts file.
In a first step, we will use hard coded fake data. In the beginning of our WebPart class, let’s add the collection of groups and the collection of tasks.
The User Interface
We create now a private _renderBoard() method that will generate the dynamic HTML and stick it into the WebPart. This method will use a _getColumnSizeClassName() helper method that returns the appropriate Office UI CSS class name according to the number of columns to display. In the KanbanBoardWebPart class, bring the following changes. The render() method must also call our new _renderBoard() method
We need now to add some CSS for our custom elements, let’s replace the content of the KanbanBoard.module.scss file with the following
To have full features of the jQuery UI drag-and-drop, we also need to include some jQuery CSS. (you can also consider customizing it by yourself). In order to achieve that, we have to load the CSS dynamically using the SPComponentLoader. We will take the CSS file from the jQuery CDN
Make the following changes in the KanbanBoardWebPart.ts file
We can now test our WebPart in the local Workbench with the hardcoded fake data, enter the gulp serve command in the console and let’s check the WebPart behaves as expected.
You should see something similar to the figure below. Try to drag and drop task tiles from a column to another to verify everything works fine.
The REAL model (SharePoint data)
Now that the UI is what we expect, we have to integrate it with real SharePoint data. As stated above, the data will come from a configured list and the Status field must be configurable as well.
We will then have to play with not only Tasks but also Lists and Fields, create two new files under the models/ folder
Let’s now define the properties we need for our WebPart to be configurable, update the content of IKanbanBoardWebPartProps.ts with
We can also configure the default values for these settings in the KanbanBoardWebPart.manifest.json file. Set the following as the value of the properties in the preconfiguredEntries section.
Back to the KanbanBoardWebPart.ts file, adapt the class as the following for the settings to be configurable from the Property Pane.
Read and Write data to SharePoint with the PnP JS Core library
In order to fetch and update data from and to SharePoint, we will need to call the REST API, We are totally able to do it with the native SPFx SPHttpClient class but the main issue with this one is that we have to build manually the URL string which, in many cases, leads to issues (from simple typos to badly generated strings in more complex scenarios). Plus you have to know the exact syntax, spend time
on Google, in the Reference Docs instead of coding each time you need a new thing.
In order to limit these issues and to improve your productivity, you can use the PnP JS Core library. It will build the REST URLs in the correct syntax for you and will tell you what’s available with the intellisense in your IDE (thanks to TypeScript definition files).
Let’s write our data manipulation methods, adapt the KanbanBoardWebPart.ts file like this:
- Select the Task list you have just created.
- Select the field you want to use for grouping (e.g. “Task Status”)
And see it magically updating :
Let’s first verify the data is correct
Move a task from a column to another and check the data is properly updated in the list
YEAAAAH It works ! What..? Did you doubt?
Let’s now verify it is really dynamic and responsive, Go to your Tasks list settings and modifiy the available values in the Task Status field.
Let’s refresh our Workbench:
(* Since we are using Office UI Fabric that has a Responsive Grid based on 12 columns, and I wanted my columns to be equal in width, in the case of 5 columns, the size of a column is 12 / 5 = 2 as whole number, it is why we can see a blank space on the right)
In this post, we saw how to implement an engaging and easy to configure WebPart with SharePoint Framework. This implementation is not perfect in terms of code and project structure (and maybe not optimized since all the lists are loaded on startup). It is actually on purpose because I want to demonstrate in a upcoming post how we can write reusable, scalable and beautiful code with SPFx.
You can get the entire solution on my github repo here
I hope you liked it, give your feedback !
See you soon,