Utilizing SPFx serveConfigurations

Recently a new serveConfigurations section was added to the serve.json config file in new SPFx Extension projects. These are a huge help when it comes to debugging extensions and are especially helpful when testing ClientSideProperties.

Robot-Tennis--33121

Background

Prior to the introduction of serveConfigurations, you couldn’t just run the gulp serve command like you do for webparts since that launches the local workbench where extensions couldn’t (and still can’t) be tested.

So the advice was to use gulp serve –nobrowser and then just navigate manually to a page in O365 and paste an ugly (and easy to screw up) set of querystrings.

Waldek Mastykarz even created a gulp task, gulp serve-info, that made this a little easier. I used it in my extensions and it was a huge leg up, but the whole thing was still clunky and a significant complexity preventing new developers from getting into extension development (or at least frustrating them).

What was needed was something as simple as gulp serve that took into account your custom locations and unique property settings. Fortunately, that’s where serveConfigurations comes in!

Setting up your serveConfigurations

When you generate a new SPFx Extension you’ll find a couple of initial serveConfiguration entries were created for you automatically in the config/serve.json file:

Default serveConfigurations

The values of these configurations should remind you of all of those querystring parameters because that’s exactly how these are going to be used. These values will build the URL for you when you serve your solution. The IDs and properties all match what was generated (although you are unlikely to keep the testMessage property for long).

The first thing you should do is replace the pageUrl property with the page address in your O365 tenant where you want to test the extension. Keep in mind these values are NOT used in the final package and are only for testing.

The sample above is for an Application Customizer (which is why the location property exists). Each type of extension will have slightly different properties (same as the debug querystrings), but will be added for you with your extension.

Multiple serveConfigurations

If you’re only doing a single extension in your solution and you aren’t using ClientSideProperties then all you need is the default entry using your own pageUrl value. If however, you have multiple extensions, then you’ll want an entry for each so that you can selectively decide which one you are serving when running gulp serve.

It is also comes in handy when you want to test different ClientSideProperty configurations. For my Field Customizer sample SPFx Item Order I allowed users to specify an OrderField property. When it was present the extension did one thing and when it wasn’t it did another.

To make this easy I included 2 serveConfigurations entries (one with the property and one without):

custom serveConfigurations

Using the serveConfigurations

Text in a json file! WOW! But how does this help?

Now when you run gulp serve the default serveConfiguration entry will be used and the browser will go to the pageUrl you specified and the debug querystring will be built using the values you provided!

Even better, you can specify which serveConfiguration you want to use using the –config parameter. So for the Item Order Field Customizer shown above, I could test the custom field configuration by entering this at a command prompt:

gulp serve --config=customField

Now the browser will be launched and my custom property will be set!

You can even see the URL that the browser will be sent to directly in the command output:

GeneratedURL

Aren’t you glad you didn’t have to type that (and get it right)? So, if you’re doing SPFx Extension development, serveConfigurations makes your life much easier!

Thank You SPS Cincy!

This weekend I had the pleasure of speaking at SharePoint Saturday Cincinnati. It was a really well organized event with speakers coming from as far away as Chicago, Texas, Georgia, Indiana, Canada, and even England. However, it wasn’t just the speakers willing to travel, there were attendees coming from all over Ohio, Indiana, Pennsylvania, and even Tennessee!

BillBaerKeynote
Bill Baer’s Virtual Keynote

Unfortunately, Bill Baer wasn’t able to attend in person (family reasons) but he got up super early and delivered a top notch keynote virtually.

My Session

I presented Getting Started with the SharePoint Framework. You can find the slides below. Here was the outline:

  • Setup Steps 1 & 2
    • Installing NodeJS LTS
    • Installing VS Code
  • SharePoint Development: A Brief History
    • SP 2016 Development Recommendations
    • Office 365 Development Recommendations
  • The Modern Experience
  • Setup Step 3 & 4
    • Installing Yeoman & Gulp
    • Installing the SPFx Generator
  • An Introduction to the SharePoint Framework
    • Client-side Web Parts
    • SPFx Extensions
    • Tool Comparison
    • The SharePoint Workbench
  • Building Your First Client-Side WebPart
    • Running the Generator
    • Trusting the Dev Certificate
    • Exploring the Local Workbench
    • Adding a Custom Property
  • SharePoint Patterns & Practices
    • What’s in PnP (Selective Highlights
    • Staying Up to Date with PnP

If you have any questions about what I presented, or the SharePoint Framework in general, you can comment here or reach out on Twitter anytime. The presentation went over very well and people seemed very excited about using SPFx, whoo whoo!

Resources

You can find my slides here: Getting Started with SPFx – SPSCinci17 (now with embedded fonts!)

Many of these slides are original but several have been adapted from other sources (mostly Ignite).

I had a great time! SPS Cincinnati had great organizers, great sponsors, great speakers, and great attendees! If you missed it, be sure to be on the lookout for it next year.

Join us at Cincinnati SharePoint Saturday on October 14th!

Matt Jimison and I will be presenting Getting Started with the SharePoint Framework (SPFx) on Saturday, October 14th, 2017 in Cincinnati as part of ScarePoint Saturday (SPS Cincinnati)!

SPSCinci17-TitleSlide

Bill Baer will be delivering the keynote: SharePoint, OneDrive, and Digital Transformation – and there are a ton of other great speakers (plus it’s free)!

Our session is at 10:40 and will introduce you to the SharePoint Framework (both web parts and extensions). We’ll actually walk you through getting the various tools installed and ready (bring your laptop) so that by the time you leave you’ll know not only what the SharePoint Framework is, what it can do, and when to use it – you’ll be ready to start experimenting immediately!

SPFx Extensions List Item Clone Demo

I was fortunate enough to present in the PnP Monthly Community Call yesterday. I demoed a sample I contributed to the SharePoint Framework Extensions sample repository called JS-Command-Clone. The sample is a ListView Command Set SPFx Extension that enables the creation of duplicate list items and utilizes PnP JS Core.

Ryan Schouten has provided a great summary and write-up of the full call. You can also watch the recording directly on YouTube. Of course, you can even watch it here where I’ve directly queued up my demo:

Please feel free to reach out to me with any questions or other feedback. Thanks!

Here are some related links:

SPFx Extension Toastr Notifications Demo

Applies To: SharePoint Framework

I had the honor of taking part in the PnP JS SIG call (Patterns and Practices JavaScript Special Interest Group) earlier today. On the call I was able to demo a sample I contributed for the SharePoint Framework Extensions called jQuery-Application-Toastr.

You can find a great write-up of the call on the Tech Community. You can also just watch the video directly on YouTube. You can even watch it right here, conveniently queued up to my demo, wowee!

Here are some related links:

Thank You SPS Charlotte!

This weekend I had the honor of speaking at SharePoint Saturday Charlotte. Great attendance, great speakers, great sponsors, and great organizers! I had a fantastic time and I heard a lot of very positive feedback from attendees. SPSCLT 2017 was a huge success and I’m grateful I got to be a part of it.

SPSCLT17 Speakers
SPS CLT 2017 Speakers at TopGolf

Here’s a video of me hitting a golf ball for maybe the third time in my life. Behold my glory:

My Session

I presented Understanding SharePoint Framework Extensions. You can find the slides and a link to the samples demonstrated below. Here’s the outline:

  • SharePoint Development: A Brief History
  • Modern Pages
  • An Introduction to the SharePoint Framework
    • Client-side Web Parts
    • Tool Comparison
    • The SharePoint Workbench
    • Key npm and Gulp Tasks
    • Hello World Demo
  • SPFx Extensions: Extending Modern Pages
    • Types of SPFx Extensions
    • Current Extension Limitations
    • SPFx Extension Demos
  • SharePoint Patterns & Practices
    • What’s in PnP (Selective Highlights)
    • Staying Up to Date with PnP

Demo Troubles

Prior to SPS I noticed that there were some changes in my developer tenant that required some adjustments of the List Driven Placeholders sample. Specifically, the placeholders seemed to be switching from PageHeader to Top and from PageFooter to Bottom. This was pretty easy to work around, but I reached out via the issues list since I was nervous other changes were on their way.

Vesa reached out immediately and let me know I was “in slightly dangerous waters” and suggested I take screenshots just in case. I followed his advice (glad I did!) and even included his response in the slides as my official disclaimer, haha.

Needless to say, I was a little nervous and checked the demos constantly including 30 minutes before my session. Everything was working! However, during the actual session I received a lot of errors. I remember saying that I thought there might be some errors but that I had expected them on the site not during my gulp serve command. Perhaps I should’ve listened to myself.

Unfortunately, I let confirmation bias and the nerves of speaking overrule my troubleshooting skills. I assumed the dreaded breaking changes had gotten me! In reality, I hadn’t stopped my last gulp serve command from showing the hello world web part. A really simple and (normally) obvious mistake.

Fortunately, I was able to show the screenshots as Vesa had suggested and things worked out fine. I regret that I gave the impression that SPFx Extensions were temporarily broken. I’m also sorry my audience didn’t get to see the samples in their full glory (screenshots work, but aren’t as cool as seeing it actually do the magic).

Resources

You can find my slides here: Understanding SPFx Extensions – SPSCLT17

Many of these slides are original but several have been adapted from other sources (mostly Ignite).

Samples Demoed:

 

Despite my demo hiccup, things still went really well. It was a great day for the SharePoint community and the SPSCLT organizers should be very proud. Thanks Charlotte – see you next year!

Join me at Charlotte SharePoint Saturday on August 26th!

I will be presenting Understanding SharePoint Framework Extensions on Saturday, August 26th, 2017 in Charlotte, NC as part of SPS Charlotte!

I’m sure you’ll all attend just for my session – but stay for everything else. Just look at this lineup!

SPSCLT

Andrew Connell will be delivering the keynote, Where are We and Where are We Going?

My session is at 11:15 am and will focus is on understanding how the SharePoint Framework (SPFx) and the Extensions fit within the historical and modern approaches to SharePoint development. The goal is for attendees to know what SPFx is and when to use it, how the extensions fit in the framework, and to know where to go to get additional details. This session is perfect for power users, managers, and developers new to SPFx.

After my session, stick around for the unofficial “Part 2” at 2:15 pm, Andrew Connell’s Modern UI Extensions with the SharePoint Framework – Command Sets, Application, and Field Customizers where he’ll be providing additional depth, details, and demos.

After attending these 2 sessions you should have everything you need to dive into SPFx extensions just in time for the upcoming Release Candidate 1 and General Availability coming later this year!