SharePoint Framework – from Hello World to being productive

Joel Rodrigues

0 comments

The SharePoint Framework is fantastic, but there are a lot of new things to learn before you feel productive on your job. In this ebook, I try to cover all the elements that I believe to be fundamental for any SharePoint Framework developer, regardless of the level of experience.

The aim of this article is to give you some tips on how to be productive using the SharePoint Framework when getting started.

The SharePoint Framework is fantastic, but there are a lot of new things to learn before you feel productive in your job. Here, I try to cover all the elements that I believe to be fundamental for any SharePoint Framework developer, regardless of the level of experience.

Motivation

The motivation for this article came from a recent experience. I have been involved in a recruitment process where I had the opportunity of interviewing some SharePoint developers. While some of them had great SharePoint framework skills, others were just getting started or only had experience with previous SharePoint customisation models.

Despite the huge growth in SharePoint framework adoption since its first release, it was clear that there are still many SharePoint developers who haven’t made the transition to the latest customisation model.

To me, this presents an opportunity to help others by sharing some of the things that I have learned in the same way that others helped me when I started this journey.

Where to start

The title of this article has a reference to the “hello-world” learning stage but let me step back a little bit to include some guidance to others who have not started learning the SharePoint framework yet.

If you are just getting started, I strongly recommend that you visit the official SharePoint framework documentation page and follow the “getting started” guides carefully. Unlike previous customisation models, SharePoint framework documentation is great, and you will find that you will refer to it very often.

Setting up your development environment successfully and without major problems is a crucial step for a smooth start. Ensure that you carefully check and follow the information provided, especially if you are not yet familiar with some of the tools. Pay particular attention to the versions of Node.js currently supported (8 and 10 for SharePoint online) as this is a common issue for developers that try to start without checking the documentation first. With the wrong version, your project will simply not build! There are also instructions on how to get an Office 365 dev subscription, which you may find very useful!

The “getting started” guides for web parts and extensions will give you a quick introduction to many concepts and capabilities available when creating each type of solution. They take you through the journey of creating your first “hello world” web part and extension, making some changes, and finally deploying the solution package. Do not start creating solutions without following these guides as otherwise, you may end up spending a lot of time trying to make sense of the basic concepts!

Web parts – getting started

Extensions – getting started

What is possible

Once you complete the getting-started guides and finish your hello-world solutions, you may be tempted to start creating your first production project. But before you do that, there are still many capabilities and concepts that you should be aware of to support your decisions and make your job a lot easier.

The first step is to understand all the SharePoint framework capabilities and common patterns, and how you can use them to your advantage. As previously mentioned, SharePoint framework documentation is really good and covers all this in great detail, so make sure you spend some time getting familiar with it. It contains extensive information about all types of solutions: web parts, extensions, and library components. It also contains information on how to bundle and share external libraries, easily connects to APIs (including SharePoint, Microsoft Graph and Azure AD secured APIs), UI design guidance, solution setup and deployment (including Office 365 CDN) and many other topics that are well worth the time to review.

In addition to this, you can also find short “getting started” videos on YouTube that show you how to take advantage of those concepts.

Frameworks

After you get familiar with the SharePoint Framework capabilities and common patterns for development, it’s time to think about frameworks. You can use any JavaScript framework of your choice, but I would strongly recommend that you consider React. The reason for this is that React is the default JavaScript framework used on the official documentation and samples, making it easier to apply the same concepts to your projects. If your company already has an adopted JavaScript framework, then this may be something that you would also consider.

There are more tools available for React currently, but details on this later.

You can also opt to use jQuery if you plan on doing a simple solution, or just plain JavaScript, but be mindful that a modern JavaScript framework will give you many benefits, especially if your solution needs to grow in complexity and size over time.

Regarding front-end frameworks, again, you are free to use any framework of your choice. But unless you have a strong reason not to, it would make sense to use Fabric React. Microsoft uses Fabric React to build the modern SharePoint sites and many other products from the Office 365 suite, so by just using Fabric React, your custom components will have a similar look and feel.

Community

Now it’s time to cover the tools that will make your job a lot easier and your solutions significantly better!

The SharePoint development community (also known as the SharePoint PnP community) released multiple open-source tools to fill some of the gaps when developing SharePoint framework solutions.

You can take advantage of those right from the moment you create your solution by using the PnP SPFx Yeoman generator. This generator extends the official one by adding many new features: additional frameworks, additional libraries and tools, the latest TypeScript versions, and even a definition for Azure DevOps, among other things.

During the development phase, you can take advantage of the great collection of reusable controls for React that are highly customizable and easy to use on your solution. And if you are building a web part, you can also take advantage of the reusable property pane controls to create a great configuration experience for your solution. Ensure that you spend a moment getting familiar with the controls already available as otherwise, you may end up “reinventing the wheel.”

It is likely that your solutions will need to interact with SharePoint via the REST API. While there is nothing wrong with creating the requests to the specific endpoints, I strongly recommend that you use PnPjs instead. Taken from the website: “PnPjs is a collection of fluent libraries for consuming SharePoint, Graph, and Office 365 REST APIs in a type-safe way”. This library takes away most of the complexity of the SharePoint REST API and gives you a much easier way to connect to the API endpoints, while also providing intellisense capabilities.

And last but not least, the Office 365 CLI provides a huge list of commands that can be of great assistance. It can generate an upgrade report with the steps to upgrade your solution to a newer SharePoint framework version, or a report with the instructions on how to externalize your project dependencies. It also contains many other commands that can be of great assistance, like managing the lifecycle of your app on the app catalog site.

Community tools

You can also find a large repository of sample web parts and extensions to use as a reference, as they provide sample solutions to many common scenarios. And there is also a repository of solutions that are ready to be installed and consumed, like the global footer and modern search web parts.

Sample solutions

Tutorial: Create a sample solution

We are now going to create a solution using some of the tools mentioned previously. At this point, I am assuming that you are already familiar with the basic SharePoint Framework development concepts and have already built your first hello-world solution. If not, go back to the Where to start section of this article to find all the relevant information. We will also use multiple community solutions on our project, so if you are not familiar with them, please go back to the Community section above and spend some time exploring the resources provided.

We will start by creating two solutions: the first using the default SharePoint framework generator, and the second using the PnP SPFx Yeoman generator. Here you will see the advantages offered by the PnP generator and how it can save you time.

We will then update the solution created using the PnP generator to include some reusable property pane controls to allow the end-user to select a SharePoint list as source of data and a user picker field (just to showcase).

Next, we include the placeholder control from the reusable controls for React to be displayed when the web part requires configuration, making it a great experience for end-users manually adding the web part to the page.

With the configuration story complete, we then need to load the data from SharePoint. For this, we use PnPjs, which, together with the async and await pattern, make interaction with the SharePoint REST API very simple and intuitive.

With the data available, it’s time to display it to the end-users. We use the list view control from the reusable controls for React to quickly create a list that is similar to the default SharePoint look and feel.

Let’s get started!

Step 1: Create new solution

With your environment correctly set up and both the default and the PnP Yeoman generators installed, create two solutions. One using the default generator (left terminal on the image), and one using the PnP generator (right terminal on the image). Remember, you can simply type yo to start Yeoman and select the generator using the interface provided.

On the first terminal, create a solution using the @microsoft/sharepoint generator and the options from the image below. After you complete all the generator questions you can stop the npm package installation. We will not use this solution for the rest of our tutorial; this step is here so we can compare the options available on each generator.

Next, go to the second terminal and create a solution using the @pnp/spfx generator and the options from the image below. As you go through each question, pay particular attention to the different options available that add additional value to your solutions.

After you complete all the above steps, you are then presented with the same questions available on the @microsoft/sharepoint. Complete the questions as per the image below to finish creating your solution and wait for the npm packages to be installed.

You should now be able to recognise the additional value that the @pnp/spfx generator adds to your solutions.

Step 2: Add reusable controls to the web part property pane

We are now going to add configuration options to our web part.

As our tutorial covers retrieving data from a SharePoint list, we will add the PropertyFieldListPicker control to our solution. Open the documentation page to check how to use the control on your solution and copy the sample code provided.

Please note that we don’t have to install any dependencies as we already did that when creating the solution.

Open your solution on the code editor of your choice and start by importing the required modules into your HelloWorldWebPart.ts

Next, copy the lists property for your web part, where you will save the list selected. We are only selecting one list, so no need for an array.

And finally, copy the custom control to the property pane configuration

Just to demonstrate that the same process can be used for other controls, repeat the previous steps but this time add the PropertyFieldPeoplePicker control.

Now let’s test. Save all the changes and run the gulp build task to ensure that there are no errors. You can ignore possible style lint errors on HelloWorld.module.scss as we are not focusing on that and the solution will still work.

Start your local server by running the gulp serve –nobrowser task. Then go to a SharePoint site collection and open the workbench page to test your web part (_layouts/15/workbench.aspx). Add the HelloWorld web part to the page and edit the web part to validate that the property pane contains the custom controls added.

Step 3: Add a reusable placeholder for default status

When you add a new web part that requires additional configuration to a page, it is best practice to display some information to the user so that he knows what to do next. We will add a React reusable control to our solution that allows us to easily achieve that.

Open the documentation page of the Placeholder control and check how to add the control to your solution. You can decide whether to add it to your web part file, or to a React component. In this tutorial, we are going to add it to the default React component on our solution.

Import the required module on the HelloWorld.tsx component.

Copy the control declaration to the render method of the component and only display it when the description property is not available, otherwise display the current elements.

Copy the _onConfigure function that will open the property pane if the provided button is clicked.

At this point, your component should look like this:

As you can see from the image above, you will have an error in the code as the React component is not aware of the web part context, so we will just pass the context to the component as a property. We will also pass the property containing the list ID selected by the user as we will use this later to retrieve data.

Start by adding the additional context and list properties to your HelloWorld react component (IHelloWorldProps.ts file)

Update the render method of your web part to pass the new properties to the component

Update the render method of your React component to test if a list is configured, otherwise display the Placeholder component (line 9 from the image below)

Save all the changes, return to the workbench page, and you should be able to see the Placeholder component being displayed when there is no list selected on the property pane of the web part.

Step 4: Getting SharePoint data using PnPjs

We already installed PnPjs on our project when we created the solution, so all we need to do next is to establish the context of the web part on the onInit method, which you can copy from the documentation page.

Your web part should now look like this

With PnPjs configured, we can now use it to retrieve data from our list/library. Open the documentation page for the List Items entity, and within the Basic Get section, you can find an example to get all the items from a list – perfect, that’s what we need!

Copy the import declarations to your React component. As this is a simple tutorial, we will get the data directly from within the React component

Now create a new function to get the data based on the sample provided, but instead of getting the list by title, we use the list ID that we already have. We will be displaying the name of documents within a document library at the end, so we will need to expand the File endpoint from the REST API to get the data we need.

We will use the async/await pattern for dealing with asynchronous calls as this keeps our code clean. Our request fits in one line!

At the top of our component, we call our _getItems method inside the React componentDidMount lifecycle method so that it gets executed at the correct time.

If you now test your solution in the browser, you can see that the information about the documents within the SharePoint document library is logged to the browser console (our method to retrieve the data was also logging the result).

Step 5: Display data using a list

Finally, we are going to create a user interface to display our data – our list of documents.

To do this, we will use the ListView control as it is very simple to use and provides an interface similar to SharePoint libraries.

As we did with previous components, we will start from the sample provided on the documentation after importing the required modules.

The viewFields property expects a declaration of the fields that will be visible on the list, so just add the following to your React component file (outside the main class)

In order to refresh the interface and display the items after they are loaded, we will use React state to store the items. Create a simple interface with just the items property and use it in your class. We can use ‘any’ as the type for your items as this is just a tutorial, but you should avoid this on real projects. Add a constructor to your class and initialise the state items as an empty array.

We will use the list as the main element within the render method of our React component, replacing the elements created by default with our solution. Remove the groupByFields property from the sample provided as we will not use this on the tutorial and clear the value of the defaultFilter property.

Your render method should now look like this (note we are rendering the items from the state)

Next, update your _getItems method to set the state with the data retrieved from SharePoint. Setting the state triggers the render method to execute, and our data will be displayed immediately after being retrieved.

You can now save all the changes, go back to the browser, and refresh the page to see a list with the documents from your document library.

By using the right tools, we were able to quickly create a sample web part that can be configured to work with any SharePoint document library, retrieve data from that library, and display it in a list.

And we did all this in just a few steps!

Keeping updated

So, after you have invested a lot of time to catch up with the latest capabilities on SharePoint framework development, what’s next?

You must ensure that you keep up to date, so you don’t have to go through a similar situation again.

My personal recommendation is to join the SharePoint development community calls, which are split into three types: general development, SharePoint framework, and monthly community updates. The calls are open to everyone and generally cover updates from the SharePoint engineering team and community projects. You can download the recurring meeting invites from the following link:
SharePoint development community calls

Another easy way to keep up to date with all the news is to follow certain accounts on Twitter. Some mandatory ones are @Microsoft365Dev, @SharePoint, and @m365pnp. If you are new to Twitter, you will quickly identify many people you can follow to receive content related to SharePoint development.

There is also a huge collection of blogs (personal or corporate) and media sources (podcasts or video series) if this is a format of content that suits you better.

Getting help

No matter how good you are, there will always be moments where you would appreciate some help. And I have good news for you! The SharePoint development community is extremely active and helpful, with a lot of places where you can ask for help.

Some common places are:

People often spend their personal time trying to help others, so if you are asking for some help, try to provide as much information as possible from the start, as this may greatly improve your chances of getting an answer in a short period. Also, avoid tagging specific people on your issues or questions, unless you are replying to them. If they are related to that specific subject, they will likely see your question at some point. Remember they are probably doing this on their own time.

Summary

And that’s it from me. We have quickly covered:

  • Where you should go first to learn about SharePoint framework
  • Where you can learn about all the features available
  • Some considerations about JavaScript and front-end frameworks
  • Community tools and resources available to simplify your work
  • A sample solution to showcase some of the tools
  • How to keep updated with new features and possibilities
  • And finally, where and how to ask for help

I hope you have enjoyed the article and that the content helps you on your journey with SharePoint framework development.

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"}