It feels like it’s been a very long journey to get this far but now we are finally ready to get on and build something that might actually be useful.

In previous articles I have covered off how to set up your development environment and guided you through how to apply suitable configuration settings for your SPFx solutions and also for client web parts that may be deployed by them. Along the way I pointed out a few gotchas and home truths and I even paused to ask you to do a quick sanity check to make sure that the SPFx is the right tool for the job at hand. And finally, I talked about web part properties and how to create them so that users can configure your web parts.

Please see the links at the end of this article to access any of the other posts in this series, but now we are ready at last to move beyond “Hello World” and build something that might actually be useful!

The Scenario

This is a real-world scenario. I’ve got a customer, a school actually, who is upgrading their aging SP2013 implementation and moving to O365 and the Modern UX. On their current Intranet page, they have a Content Editor Web Part (CEWP) with an embedded widget downloaded from the SunSmart, which is a not for profit program in Australia with a skin cancer prevention mission.

The idea is that staff at the school can check the widget for the times in their location when kids need to Slip! Slop! Slap!.

You can head over to the SunSmart web site, tweak a few settings and then copy the resulting iframe, ready to be added to your web site.

The problem is of course that we don’t have a CEWP available to us in Modern.

So the aim then is to create a custom client side web part that enables us to put this information on any page and whilst we are at it we can externalise some of the properties of the SunSmart iframe and make them configuration settings that can be controlled via web part properties, such as the location being reported on and the width of iframe etc., so that users don’t need to mess around with hacking the source HTML.

What about the Embed Web Part?

Now, I am well aware that there exists a standard Embed web part for just this sort of thing, but this is what you get if you paste the iframe markup into a standard embed web part.

Click on the guidance link and it explains that the Site Collection Administrator has to go and configure HTML Field Security from Site Settings.

Fortunately, I am a SC Admin so I can just add the SunSmart domain to list of allowable domains and we are away.

Actually, the end result is ok in that it delivers on its promise but it doesn’t align right on the page and it’s bigger than I’d like it to be.

But I think we can do better. First, up I want to avoid having to get the SC admin to do anything but I also want to allow users to tweak the web part settings without having to hack the widget code. Also, because the widget is a bit big for my liking, I’m thinking we might be able to do some crafty CSS manipulation to make it about 200px square so that it lines up nicely with the hero web part that sits along side it on the new intranet homepage and also maybe give us some other layout tweaks to may it a bit more flexible.

The End Result

It’s probably easier if I just show you what the end result looks like and then explain how we go there.

And here are the configuration properties of the web part.

In think it’s fairly intuitive as to what these properties do and so I’m not going to explain that here but rather refer you to the product page from which you can download the solution package and where the properties are explained.

The beauty is that I can simple change web part properties and have these immediately take effect in the web part. In the screenshot below, I’ve switched to the full display mode, widened the web part to 300px, positioned it centrally within the column, added a header and set the location Sydney.

And the code?

And the code to achieve this miraculous output is surprisingly small and simple. The magic all happens in the web part’s render method.

Now, I’m not going to walk you through the code to create the web part properties because I covered off how to do that in Part 6 of this series, suffice to say that in the getPropertyPaneConfiguration() method I created the necessary groups and field editor controls to govern the HTML that is rendered on the page.

Nervous Tick

Just before we dive into the code walk, brief as it is, I thought I’d explain about the use of the backtick marks that are being used here. Coming from a C# background I had never seen this before and so was at first a bit confused and then curious and then a complete enthusiast of this simple and amazing feature. It turns out that that approach allows you to format strings in a way that doesn’t require escaping quotation marks, clumsy string concatenations and allows you embed variable string elements within the resulting string.

It’s a bit like the string.Format() method you get in C#, only even better. Instead of numbered tokens inside the {} characters you can embed the variable values right inside the string with a ${<your string reference>}. How cool is that? I am a huge fan!

Code Walk

Ok, let’s go through the code.

First up, I declare couple of read-only strings which contain the fragments of style attributes I need to add to the containing div and the iframe when I want to present the output in Minimum mode, as opposed to Full, normal mode. Basically, what this does is fix the height of the containing div to be 199px, which is the same height as my hero web part tile and hide any overflow. It then shifts up the iframe so I can present just the essentials and the stuff around the edges is effectively hidden from view. It’s a bit crude I know but as the content that get returned in the iframe is completely outside of my control we have to sometimes resort to such blunt instruments.

Inside the Render method, I check the fullDisplay property, supplied by a Toggle Field control of the web part, to see which display mode has been specified by the user and if that is set to Full then I set my variables to be empty strings, when its set to Minimum then we know to add the style attributes that give us what we need.

I use the same technique to set a header for the web part, in case one is needed. Note that the webpartHeader style is actually defined in the module.scss file:

So, we can dynamically insert CSS classes as well. Just use the styles
prefix instead of the this
prefix. One gotcha here is that we must include the root CSS in a containing outer element or else our inner classes won’t take. In my case, the root CSS class was called sunSmart and was automatically set up for us when the web part solution was provisioned by Yeoman, and hence the need to wrap the whole HTML in an outer div with this parent class specified.

Then, we simply set the innerHTML of the domElement to return the markup we need but with the appropriate values coming from web part properties to control how the containing div and the inner iframe are configured. It’s all very simple really.

Probably, the only property that needs looking at in more detail is the location field control.

It turns out that the SunSmart iframe URL takes a location parameter which identifies the city and so we just need to make sure that the field control returns the appropriate key value for the selected location. Actually, SunSmart support dozens of locations all around Australia but here I have just specified the State and Territory capitals.

That’s a wrap!

So that brings me to the end of this mini series of how to get started building client-side web parts with the SPFx.

Just to recap:

• Part 1 – Getting Started: I provided guidance on setting up a development environment and how to use the local and remote workbenches with the standard Hello World web part.
• Part 2 – Packaging and Deploying Solution: I explained how to bundle and package a solution and how to add it to the app catalog of your tenancy so that it can be accessed by end users.
• Part 3 – Solution Configuration Settings: Here I went through how to set up solution titles, descriptions and application icons and covered off versioning as well.
• Part 4 – Client Web Part Configuration Settings: In this article I covered how to set titles, descriptions and icons for web parts and how to assign web parts to groups and categories.
• Part 5 – Sanity Check: In part 5, I did a bit of a reflection on the SPFx and identified my take on when you should, and should not, be using it. The bottom line being that this is the future of web part development so you’d better get with the program.
• Part 6 – Web Part Properties: This article talks about how to set up web part properties to allow users to control how the web part operates and functions.

And all of that lot led us to the point where we are in a position to build something that is actually useful.

Of course, there is lots of stuff that I have not covered yet, such as globalisation – making your web parts multi-lingual, or using the JavaScript frameworks specifically React and Knockout. But just remember that SharePoint is a journey and not a destination!

Please let me know if you enjoyed this series or any of my other articles as that will encourage me to keep doing this sort of thing.