Recently I was asked to develop a webpart for a modern SharePoint site. My first thoughts were; where do I start, I haven’t done any webpart development for years? I would like to share my journey with you over the next few posts and hope my experience will help new and returning developers along the way.

In my previous post I covered:

• Development Environment & tools
• Frameworks & Fashion
• Back to School

In this post I will cover:

• Avoiding Pitfalls (Part #1)
• Solution Design (Avoiding Pitfalls Part #2)
• Choosing a Framework
• Creating a SPFx Project
• Source Control

Avoiding Pitfalls Part #1

Let’s start by addressing the pitfalls I listed in my last post:

1. Distracted by someone else’s code

This one is easy; we are going create a new / blank project. If we need to refer to someone elses code for inspiration, then we will do this outside of our project.

2. Getting bogged down in detail

The React website has a great article on this called Thinking in React which I recommend reading. So, let’s practice what we preach….

3. Avoid the muddying of data and presentation code/layers

Well the plan we made to avoid the previous pitfall will also help with this too. If we are still confused it is because we need to do some more planning… 😊

4. Check the SPFx Project Generator Version

The tooling used to scaffold SPFx project is out of date. This should not be a problem if you have just configured a new brand environment/machine. If, however like me you are coming back to an existing environment/machine then I would recommend uninstalling everything SPFx related:

npm uninstall @microsoft/generator-sharepoint --global
npm uninstall yo --global
npm uninstall gulp --global

And finally, Node.js using the “Add or remove programmes…” to check the version and uninstall if required.

Once done, you can re-install the tools with confidence…

Solution Design (Avoiding Pitfalls Part #2)

Let’s start by creating a wire-frame, which essentially is a design without branding or colours. There are many great tools on the market for creating wire-frames, such as Balsamiq, Lucidchart or Microsoft Visio. However for this example, I am going to use Microsoft PowerPoint to demonstrate how easy it is to create an effective wire-frame. Click here to open my People-Search-Wire-Frame.pdf file.

Wire-Frames

Start by adding the components to the diagram, while thinking about how the end-user would interact with your webpart.

On the next diagram I have labelled each control, giving a brief description of each control and / or its behaviour. If you are a solo developer you may decide to skip this detail, however, I find the validation process useful.

The last page/diagram breaks the webpart down into components. I have done this by functionality, repeatability and in some cases, where the data will come from.

Data Sources

Now that I have a design I can start thinking about where the data is going to come from. In the past I may have used SharePoint Search with the User Profile Service, however today I am going to use the Microsoft Graph API, as “The Graph” combines multiple Microsoft 365 services into a single endpoint.

Tip: The Graph Explorer is a great place to start working Microsoft Graph, it has a number of sample queries to run against dummy data or better still sign in to your Microsoft 365 Tenant and test queries against your own data (see my next tip).

Tip: Sign-up to the Microsoft Developer Programme and get a Microsoft 365 developer subscription to develop your solutions independent of your production environment.

The table below lists the components I expect to build, obviously this may change if I find other complexities once the build is under way, plus:

• The Data Source gives a rough idea as to where to find the data.
• The Expected Results gives a rough idea of shape of the data.
• The Component Action describes what the component will do with the data.

Component Name	Data Source	Expected Results	Component Actions
Search Wrapper	–	–	–
Search Box	Graph Users	Zero to more items	Filter
Search Clear	–	–	Clear data & filters
Filter Wrapper	Graph Users	Zero to more items	–
Filter Combo-box	Graph Users	Zero to more items	Filter
Filter Auto-suggest	Graph Users	Zero to more items	Filter
Result Wrapper	Graph Users	Zero to more items	–
Result Card	Graph User	One item	Display
Result User Photo	Graph User Photo	One item	Display
Result User Presence	Graph User Presence	One item	Display
Result User Contact	Graph User	One item	Display
Footer Wrapper	Graph Users	Zero to more items	Display

Choosing a Framework

Just because you are developing a SPFx webpart does not mean you have to build it in React, there are other options, such as “No JavaScript framework” (i.e. hand-rolled or do it yourself) or Angular.

Sorry to disappoint, however I am going to stick with React – React Hooks possibly with useReducer.

Creating a SPFx Project

To help you reproduce my solution I have listed the steps below.

Creating a VS Code Workspace

I am a fan of Workspaces they enable you to save and share preferences including UK/NZ spellings…

1. Create your project directory, for example:
   C:\…\Company.SPFx.Webparts.People
2. Open Visual Studio and navigate to: File -> Open folder…
3. Next locate and open your new directory
4. Once opened navigate to: File -> Save Workspace As…
5. Navigate up a folder, enter “Company.SPFx.Webparts.People.code-workspace” and click save

Scaffold the SPFx Project

Now we are ready to open the Terminal window with VS Code and run the Yeoman SharePoint generator.

1. Open Terminal: [Ctrl]+[`]
2. Enter the following commands:

yo @microsoft/sharepoint

1. Next enter: MS-Graph People Search – Press enter
2. Select: SharePoint Online only (latest) – press enter
3. Use the current folder – press enter
4. Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment or adding apps in sites? – Y
5. Will the components in the solution require permissions to access web APIs that are unique and not shared with other components in the tenant? – N
6. Select: WebPart – press enter
7. What is your Web part name? People Search – press enter
8. What is your Web part description? Search for people within your organisation using Microsoft Graph – press enter
9. Select: React – press enter

Once the Yeoman command has completed, we can check the solution by running the following commands:

gulp clean
gulp build
npm shrinkwrap
gulp serve

Source Control

I am going to designate source control out of scope for this post, however what I would recommend committing your code (or backing it up) at this point, so that you have a place you can rollback to if it all goes wrong.

Next time

For my next post I will focus on building the structure of my webpart.