Converting your CEWP Customizations to the SharePoint Framework

December 11, 2016 Mark Rackley Uncategorized 0

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

Unlike simply injecting a script in a page with a Content Editor or Script Editor Web Part, by using the SharePoint Framework developers can work in a more managed environment with a better testing, packaging, and deployment story. Users can easily take advantage of web part properties to customize scripts instead of forcing users to update JavaScript they likely don’t understand.

TypeScript

Okay, so this isn’t exactly a reason for ME to use the SPFx, but there are a lot of .NET developers that don’t have a lot of experience writing JavaScript, and let’s face it, JavaScript development can be painful and difficult to debug. The SharePoint Framework uses TypeScript which allows developers to create applications that compile down to JavaScript but take advantage of strong typing and compile-time errors. Do you HAVE to use TypeScript to create SPFx web parts? No, but it would make your life easier if you did.

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

This leads us to the point of this blog post. What would it take to take one of my existing JavaScript customizations for SharePoint and convert into a SharePoint Framework client web part? How hard would it be?

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
    • Because we are using Unslider’s CSS files we don’t want to have to re-write Unslider’s JavaScript files to work with the SharePoint Frameworks style rendering (which is awesome for isolation). So, we need to import Unslider’s css files by adding import statements to the /src/webparts/<project>/<project>.module.scss file
    • @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
      • Add a require statement for the JavaScript files we’ll be using that we copied over
      • 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.

For another really great blog post (which helped me with my customization in this post) you must check out Waldek’s blog post “Migrate SharePoint JavaScript customizations to SharePoint Framework – jQuery AJAX calls and showing data”

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.

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:

Welcome to the SharePoint Framework Developer Preview!

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.

Next, if you really plan on using the SPFx I’d highly suggest you learn TypeScript. I WAS able to convert my customization to SPFx using mostly JavaScript, but in the long term and for larger development efforts learning TypeScript will make your life easier. PluralSight has some great courses on TypeScript as well.

icon-vertical-fullcolor-250x168[3][5]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.

I see the SPFx being hardest to grasp for those pure JavaScript developers out there who have never experienced .NET development. The use of Interfaces and Lambda Expressions might just make your head explode. 😉 If you can get past it though, your world opens up and you’ll be learning some cool (marketable?) skills and you don’t have to worry about end users breaking your scripts anymore!!

Happy coding!

Families in Germany who are facing divers health problem, such persons can buy drugs from the Web without prescription. With the market flooded with divers web-sites selling sundry medicaments, purchasing medicines from th WEB is no longer a trouble for common man. Certain medications are used to treat infections caused by dental abscesses. Of course it isn’t all. If you’re concerned about erectile soundness problem, you probably know about Xenical and Hoodia. Probably each adult knows about Garcinia. (Read more PhentermineXenical). The symptoms of sexual health problems in men turn on improbability to have an erection sufficient for sexual functioning. Certain medications may add to sex drive difficulties, so its vital to cooperate with your health care professional so that the prescription can be tailored to your needs. Preparatory to taking Levitra or other medicament, speak to your pharmacist if you have any allergies. Talk to your health care provider for more details. Preparatory to ordering this remedy, tell your physician if you are allergic to anything.