It’s coming… the SharePoint Framework (SPFx). A new development model for SharePoint 2016 and Office 365.
By now you’ve likely seen the deluge of content about the SharePoint Framework and the myriad of code samples out there. There’s so much content out there already that you have to remind yourself it’s still in preview!
What is the SharePoint Framework?
In a nutshell, the SharePoint Framework is a new development model for building Client Web Parts for the new Modern Team Sites and Site Pages in SharePoint. The SharePoint Framework does NOT replace ANY of the previous development models for SharePoint. SharePoint Add-Ins are still fully supported. The SharePoint Framework utilizes TypeScript and “Modern” Open Source tooling (which will be the biggest obstacle for .NET developers).
Basically, Microsoft was like “What the what??? Look at all these people injecting script on a page in SharePoint with Content Editor Web Parts!?!! Why the heck are they doing that?!!?! We need to give these guys a better way.”
And the SharePoint Framework was born.
Why use the SPFx?
You may be wondering why or under what circumstances you’d use the SharePoint Framework. Do we really NEED another development experience in SharePoint? What makes the SharePoint Framework so unique?
1st Party and 3rd Party Development
What makes the SharePoint Framework unique is that Microsoft is actually using the SharePoint Framework to build the new modern site pages experience in SharePoint. This is really great for the rest of us! It means that Microsoft (1st party) is going through the same pain as the rest of us (3rd party). Now, when there’s an issue it affects Microsoft developers as well and hopefully it means they are more likely to embrace this technology and invest time into keeping it updated and supported.
More Control and Better Management
You Kinda Have to For the New Modern Pages
The new modern Team Sites use SPFx Client Web Parts and if you want to develop web parts for these modern pages you’ll have to use the SharePoint Framework. Will there be a script injection story for the new modern pages? Likely, but we still don’t know what it will look like.
Upgrading your current CEWP Customizations
Let’s take an example solution from one of my recent blog posts: The Ultimate Content Slider for SharePoint
In that blog post we are creating a content slider by adding a Content Editor Web Part to a page in SharePoint and linking it to a script that references jQuery, Unslider, and a couple of style sheets. It also makes a REST call to a SharePoint list to get the content for the slider. This is an ideal candidate for something that SHOULD migrate over well to the SharePoint Framework.
Let’s walk through the steps needed to convert our solution. The prebaked solution can be found over on GitHub at: https://github.com/mrackley/PAITSliderSPFx
- Create the Project
- Use Yeoman to create the Web Part Project
- This is equivalent to “File->New Project->Select Template” in Visual Studio.
- Copy over our files
- Copy over the files used for the CEWP script to the /src/webparts/<project> folder
- Reference jQuery
- Add an “externals” entry to the config.json file located in /config
- Tweak the script
- My script from the above blog post utilizes the Form Digest on the page, but that Form Digest doesn’t exist in our Workbench for testing so, we need to tweak the script to get the Form Digest differently. The Form Digest is needed for the HTTP Post we are doing in the script.
- Import the CSS
- @import url(‘filename.css’);
- Render the content slider
- Now we need to modify the file responsible for rendering our client side web part found at /src/webparts/<project>/<project>WebPart.ts
- From here we need to
- Declare jQuery as a variable
- Execute the method to render the slider
- Take advantage of the properties
- At this point we have a working content slider as a SPFx Client Web Part. However, to take full advantage of the SPFx features, we should convert the parameters used for initializing our Content Slider to Properties that end users can modify. We’ll do this by creating properties the user can edit and modify the script to use these properties.
- To create/modify properties you’ll need to make sure you set them up properly in a few places:
- /src/webparts/<project>/I<project>WebPartPartProps.ts (for the Interface)
- /src/webparts/<project>/loc/en-us.js and /src/webparts/<projct>/mystrings.d.ts (for the labels used)
- /src/webparts/<project>/<project>WebPart.manifest.json (for default values)
- /src/webparts/<project>/<project>WebPart.ts (to create the Property Panel with your properties)
- We also need to disable the reactive property changes so that users have to click an “apply” button when editing the properties, otherwise the user will get errors when trying to update the list and view name properties. This is done by overriding the get property disableReactiveProperyChanges and having it return true;
- Test the Client Web Part
- Execute “gulp serve” to build and deploy your web part
- Test in your site by browsing to /_layouts/workbench.aspx
Confused? Let’s take a look at a video which walks you through the entire process.
At this point you may be thinking “wow, that was a lot of work when all I previously had to do was stick a CEWP on a page and link it to a file.” Well, you aren’t wrong, but you also aren’t seeing the bigger picture. With the SPFx it’s now a one step process to add our web part on a page instead of 3 or 4. Also, users can take advantage of the property settings to change how the web part works without having to modify the script (this is huge). Now you can develop one web part, deploy it to multiple sites and pages and users can configure the web part without having to modify a piece of script. Also, the SPFx gives us some “Script Isolation” which means it’s harder for developers to write client web parts that overwrite the styles or hijack the variables of other client web parts on the page. So, yes, there is more upfront work, but there’s absolutely more long term gain.
Packaging and Deploying Your SPFx Client Web Parts
After you build your SPFx Client Side Web Part, you’ll need to understand how to deploy it for testing and package it for deployment. Take a look at the following two posts for step-by-step instructions to both packaging and deploying your solutions.
- Deploy your client-side web part to a classic SharePoint page
- Deploy your SharePoint client-side web part to a CDN
What to do next?
If you haven’t already done so, head over to GitHub for step-by-step instructions on setting up your machine to build SPFx Client Web Parts. There are several steps to follow, and if you are an old school Visual Studio developer you’ll be exposed to tools you may have never heard of before:
The next thing I’d suggest you do is read up on the Framework from those trusted people who’ve been using it for quite a while now. There’s a lot of great content, examples, and advice out there if you know where to look.
- Waldek Mastykarz
- Andrew Connell – (Check out AC’s latest blog post on using Yarn instead of NPM to more effectively handle your node_modules)
- Chris O’Brien
- Wictor Wilén
Finally, if you are looking for an online course for the SharePoint Framework, you can sign up for announcements from Andrew Connell’s new training site Voitanos. AC is in the process of building a great in depth course which I was lucky enough to get a preview of last week.
To Sum it all up
The new SharePoint Framework is coming and with it come a new set of skills that you need to learn as a SharePoint Developer. It’s different, it’s “modern”, and it’s necessary for some of your customizations for the new modern team sites.