Adventures with the SharePoint Framework (SPFx): Part 4 – Client Web Part Configuration Settings

In this article I want to guide you through the process of applying some useful configuration settings when developing client web parts using the SPFx. In the previous post I covered how to set similar properties at the solution level but here I am going to take it down a level and look at the options for applying configuration settings for individual client web parts.

I know that these settings do not affect the functionality of your solution, which is why so many developers never get around to changing anything and just accept the default settings, but once you know what to do, it only takes a couple of minutes and can make all the difference between a professional and an amateur looking job. So, read on…

Specifically, I will address the following:

• Title and Description: Where and how to set a web part’s title and description
• Icons: The options you have for using a meaningful icon to represent your web parts
• Groups and Categories: How to associate your web part with one of the standard groups when adding an instance of your web part to a Modern page and how to assign it to a category when adding an instance to a Classic page

Each web part that you deploy with a SPFx solution will have its own json manifest file in the src/webparts folder of the solution directory. The actual manifest filename is prefixed with the web part’s name in the format {Web Part Name}.manifest.json and it is from this file that you can apply the appropriate configuration settings. My sample test web part is called, rather imaginatively I feel, TestPartWebPart so the manifest file of interest is TestPartWebPart.manifest.json.

Titles and Descriptions

You will want to set a meaningful title and description for you web part and the place to do that is in the preconfiguredEntries object in the manifest file as highlighted below.

Note that the title property is what will be shown in the web part picker dialog when adding a web part instance to a page. You don’t have much text to play with here before the UI cuts you off with an ellipsis, so keep the title short and pithy. The description text is shown as a tooltip when hovering over the web part item, so you can afford to be more verbose here.

After a re-package and re-upload to the App Catalog the web part will adopt the new title and description properties as shown in the screenshot below:

Icons

In the above screenshot you can see that the icon associated with our web part is a rather non-descript page-symbol with a dog-eared corner. This is the default icon for your web part and is specified using the officeFabricIconFontName property. You can simply head over to https://developer.microsoft.com/en-us/fabric#/styles/icons (use Chrome or Edge as this page does not like IE) and pick one of the 600 or so icons at your disposal. Simply hover over your icon of choice to see its AppFabric name and replace the default “Page” value with your preferred value in the json file. Beware that the name is case sensitive, so if you misspell it or get the text case wrong then no icon will be shown at all.

Here’s what the BirthdayCake icon looks like in the local Workbench.

It seems that in some early implementations of the SPFx not all the AppFabric icons were supported and so you may come across older articles which state that you are limited to a sub-set of specific icons. It appears that this is no longer the case

If none of the AppFabric icons meet your needs then you can add an iconImageUrl property that provides a URL to any icon of your choosing – I just picked one at random from the Internet.

And this is what it would look like if I left that URL in situ:

Contrary to what I have read in some other posts, I have found the following:

• You don’t need to remove the officeFabricIconFontName property from the json file if you would prefer to set a custom icon URL
• iconImageUrl seems to trump officeFabricIconFontName, some other posts say it’s the other way around
• You don’t need an icon that is of exact and specific dimensions. Although the schema states “The image at the URL must be exactly 38×38 px” this is in fact not (or no longer) the case.

If you inspect the encasing div in your browser toolset of preference, it seems that you have a space of 82px wide by 28px height at your disposal but the image will not be stretched but rather resized to the confines of the constraining dimension. My source image was actually 32px square and so was shrunk to 28px square and placed centrally in the <div> container. There is an abundance of 32px square icons out there and most will look just fine squashed by 4px but if you are a perfectionist you may want to create your own to exacting dimensions.

If we do decide that our web part needs a custom icon (maybe we have a brand identify we want to promote) that brings us to another point and that is where such an icon image should be stored. Your choices are:

• Find a suitable image on the Internet and just use the URL (ensuring that you comply with any licensing requirements of course)
• Host a custom icon image yourself on a web site or CDN
• Bundle a custom icon image it as part of your solution
• Base64 encode your image

The first option is not really a good choice as it relies on a 3^rd party managing the resource and they might easily delete, rename or make the graphic no longer accessible without consulting with you – how very dare they!

I think that option 2 is probably the best approach if your web part is for a mass market as it gives you the opportunity to change the icon from a single place and allows you to swap out you image for a new one without the need for users of your web part to upgrade the solution package.

Whilst I recommend option 2, I am now going to guide you through options 3 and 4 as you may not have a suitable hosting location at your disposal and you may consider it unlikely that you will want to upgrade the icon universally from a single point.

Let’s start with option 3. First, we have to include our graphic in the package that gets shipped the CDN, remember we’re still using the inbuilt CDN capabilities of the tenancy for now. To do that simply copy a suitable icon graphic to the src/webpart/{your web part} folder, mine is named WPIcon.png. All that is required now is to specify the relative URL to the new graphic in iconImageUrl property. As the graphic is in the same folder as the json file then all we have to do is prefix the graphic file name with a “./”, so the file now looks like that shown in the screenshot below:

Gulp serve to see your handiwork.

As straightforward as this is, an even more elegant solution put forward by Elio Struyf is to Base64 encode your graphic. Just head on over to an online convertor app, Elio suggested this one https://www.base64-image.de/. Upload your source image, copy the resulting URL and paste it in as the iconImageUrl property as shown below:

This way you don’t even need to bundle the graphic as a resource that needs to be shipped with your package, as the data for the icon is embedded within the URL – very cool.

Groups and Categories

There are 2 properties in the preconfiguredEntries object which control the group and category in which the web part will be displayed.

The group property is for use with Classic pages and the value you set here will be treated the same as the Category property of a traditional web part. And, as with a traditional web part, if you omit the group property then the default Miscellaneous category will be assigned. The SPFx defaults to setting the group property to “Other” which is a bit confusing in my opinion because with (inherently lazy) developers you might well end up with both a Miscellaneous and an Others category. I think it would have been better to set the default value to “Client Web Parts” or “SPFx Web Parts” or actually anything slightly more useful than “Other”. As I like to group all my web parts together under a brand name, I will use “Kaboodle” as the group property value.

The groupId property is for use with Modern pages and is a required property that should be assigned one of 7 GUID values which map to 7 out-of-the-box groups shown in the web part picker dialog. The ID values and the corresponding group names and descriptions are shown in the table below:

It seems that in Modern we are limited to one of these 7 predefined groups which is a bit of a disappointment because it would be nice if product vendors could group all their wares by a brand name, after all we have always been able to do that in the past, and we still can, in Classic pages, by setting the group property.

Also, pasting in GUIDs is a but ugly. I can’t help but feel that with a little bit off effort Microsoft could have given us nice text constants to play with. I suppose I’ll cope.

In my example json manifest file I have now assigned the web part to the “Text, media and content” group in Modern pages and the “Kaboodle” category for use in Classic pages.

Gulp serve it and from a tenancy workbench you can check that it is assigned to the right group in Modern. Viewing it from your local workbench won’t show any groups of course.

Notice that web parts are shown in alphabetical order within each group and that there is only enough space to show the first 8 items in a group. To access the rest, you need to click the “See all” link, highlighted above. To make sure your web parts get noticed one might be tempted to use that old telephone directory trick and name you web parts with early letters in the alphabet (or numbers even) – AAA Plumbing anyone!

If you want to check the assignment of category in Classic pages then you have to do a full re-package and upload to the App Catalog rather than being able to shortcut with the Workbench. But it does work as advertised as can be seen from the screenshot below:

Conclusions and Recommendations

Configuring web part parts is fairly straight forward, you can easily:

• Set the web part’s title and description as it appears in the UI
• Assign it to one of the 7 standard groups available to use in the Modern UX
• Assign it to any Category you like, including a custom one of your own naming, when the web part is being added to a Classic page
• Associate it with one of 600+ pre-defined icon graphics available in AppFabric
• Or, use a custom Icon graphic of your choosing for which you can either:
  • Link to a local resource by providing a relative URL to a suitable graphic included within the solution package
  • Link to an external resource by providing an absolute URL to an appropriate graphic file, hosted externally somewhere that is universally accessible location
  • Base64 encode your graphic file and provide that as the icon link

Room for improvement? Sure, but nothing that’s a show stopper:

• It would be nice to be able to assign our web parts to custom groups like we can assign regular web parts to custom categories in Classic pages
• Using a GUID to uniquely identify one of the pre-defined groups is a bit ugly

I recommend that you take the time to set these web part properties. It only takes a few minutes to set things up and will make all the difference between your web part looking amateurish and the professional piece of work that you always intend it to be.

So far in this series, we have looked at the plumbing and configuration of creating a solution using the SPFx. Important as this may be, we have yet to do anything creative. Well that’s all going to change with the next few posts, where I am actually going to build something that might actually be useful.

However, before we go there, I think its time that we did a sanity check to make sure that the SPFx is the right tool for the task at hand.  That sanity check is the subject of the 5th article in this series.