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:
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.
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.
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 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
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…
- Create your project directory, for example:
- Open Visual Studio and navigate to: File -> Open folder…
- Next locate and open your new directory
- Once opened navigate to: File -> Save Workspace As…
- 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.
- Open Terminal: [Ctrl]+[`]
- Enter the following commands:
- Next enter: MS-Graph People Search – Press enter
- Select: SharePoint Online only (latest) – press enter
- Use the current folder – press enter
- 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
- 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
- Select: WebPart – press enter
- What is your Web part name? People Search – press enter
- What is your Web part description? Search for people within your organisation using Microsoft Graph – press enter
- 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
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.
For my next post I will focus on building the structure of my webpart.