The SPFx Kaboodle Branding Package

At O365 Saturday in Sydney last week I demonstrated an SPFx Application Customizer solution that I have called the Kaboodle Branding Package. I think the session went well and there was certainly a great deal of enthusiasm for the enhancements delivered by this solution, so I thought I’d better blog it and provide the solution download.

So, what’s it for?

I built this solution out of necessity because the OOTB Modern UX currently doesn’t quite do what I need it to do.

So, I think I’d better explain what I am intended to achieve. Actually, there are quite a few things that the Kaboodle Branding Package can do but I guess the key ones are:

• It can provide a payload of any HTML, including CSS and JavaScript, to be added to the header and/or footer content placeholders that are available on every Modern page.
• It provides a way to easily associate any site with a top-level menu item in the global navigation for sites associated with a hub site. It turns the bog-standard navigation into a space navigator to provide context for users
• It provides a really easy way to hide UI elements that just get in the way, specifically the Feedback Button and the Mobile App Upsell Button which Microsoft don’t currently provide an effective way of disabling.

Let’s look at each of these, a bit more closely.

The HTML Payload

So, an SPFx application customizer solution provides a means to add an additional payload to 2 locations on every Modern page on the site in which the solution has been deployed. If you come from a traditional SharePoint developer background these are a bit like the delegate controls of old, except delegate controls have many more insertion points available in the master page and you are adding server-side components to the page. With an SPFX application customizer you only get to insert a payload as a header and/or a footer to the page and you are restricted to client-side markup of course, but fortunately that can include CSS and JavaScript.

This provides a great way to add a consistent header and or footer to the page and the SharePoint Starter Kit provides some great examples which show-case how this might be useful. It provides a solution where you can enter items in a list that then gets rendered either as banner messages in the header or as a footer for every page in the site.

Outstanding as it may be, the starter kit offering has some obvious and stark failings. First of all, the payload is not very flexible. You are basically limited to what gets added to the list items used to provide the content and we don’t get any custom styling options either. The Kaboodle Branding Package removes this limitation by allowing you to link to the HTML payload of any arbitrary file. The downside is that yes, you will have to handcraft the HTML content yourself, but the upside is that you have total control over what is displayed and how it gets rendered.

Another limitation of the Starter Kit solution is that your header or footer content is scoped only to the Site Collection (SC) in which the solution has been activated. But Microsoft’s best practice these days is not to use sub-sites if they can be avoided and so instead of having just a dozen or so SCs, you might in fact have hundreds, if not thousands of them. Page footers, in particular, are about providing access to content that is consistent throughout a tenancy (or at least that’s the way I see it) and so trying to keep them consistent across multiple SCs, especially when you have lots of them, simply isn’t going to work.

The Kaboodle Branding Package gets around this by giving you the option to get all your footer content from one source. Instead of specifying the content in each SC you can have everything point to a single file. So, you can have the same footer used throughout your tenancy and then changes made in one spot are globally and instantly applied. You don’t have to use the same payload file of course. You are perfectly at liberty to use a different payload file, or no payload at all, for each SC.

Ah, but it gets better. Microsoft recently introduced the concept of Hub Sites and the Kaboodle Branding Package allows all the sites associated in the same hub to use the same branding configuration. So, if a site is associated with a hub then it just goes and looks at what the hub site is doing and follows along. You just configure the branding solution for the hub site and then then all sites in that hub know to use that same configuration. So, all you have to do for a site that is associated with a hub site is install the app – no configuration required!

And say you have multiple Hub Sites and you switch a site to a new one, then that’s no problem, it just picks up the configuration specified for its new parent hub.

Space Hoppers

When I sit down with customers and help them to figure out what they need from their SharePoint environment I usually encourage them to think in terms of spaces. The following is my starter set of spaces:

• Intranet Portal: Where users come to consume news or access online resources and services.
• Collaborative Working: Where users work collaboratively on producing new content or updating existing content. Typically, I break down Collaborative Working into 3 distinct spaces:
  • Teams: Workspaces for business units and teams – so department work areas basically.
  • Communities: Workspaces for cross functional and inter-departmental work – think working groups, committees and social clubs.
  • Projects: Workspaces for project teams.
• Apps: Where users can access SharePoint hosted general or specific line of business applications – think leave requests and invoice processing, respectively.
• Archive: Where old information should go to die. Nearly everyone forgets this one, as everybody focuses on how to get stuff into SharePoint and pays little or no attention as to how stuff should exit in a graceful way so that it doesn’t just end up as noise.

I’m not saying that this is the only way to think, nor that its always the right way to think, but I know from experience that it works. It’s a concept that most users get and is easy for them to understand.

Now, the new hub sites are doing much in the way of helping us to dynamically stitch together SCs so that navigation is now more of a logical construct than a physical one. I can see a pattern where a large organisation might have several hubs which link together team sites and then the business restructures and the team sites get repositioned logically rather than physically. With SharePoint hub sites that’s now very easy to do because all you are changing is the navigation and not having to relocate any content physically.

However, what hub sites don’t currently do, is work at the space level. So that means that the hub global navigation is plain, un-stylised and currently incapable of giving a visual cue to the user as to which space they might be in currently.

I think a picture paints 1000 words here. Below is a screen-shot of a custom deployment I have been working on.

You can see that the Global navigation immediately lets the user know that they are in the Intranet Space. The hub global navigation link is styled differently, it’s bold and underlined.

When I switch to a site that is associated with the Teams space then the Teams tab is styled as being in focus.

Once again note, this is nothing to do with how the SCs are physically arranged or structured but rather this is all about a logical association.

But how do you associate a site with a space and a global navigation item? It’s very simple, just set the start text of a site’s description to be the text of the global menu item to which it should be associated.

If, the site’s description can be matched to a global menu item, then it lights-up. If it can’t be matched then it doesn’t light up.

I think that this is something that would add real value to the UX and with the Kaboodle Branding Package it is unbelievably easy to set up.

For me, there is a natural alignment between hubs and spaces. Spaces are conceptual, logical associations and hubs are how those logical associations are implemented in the technology.

Hey, you’ve got to hide your love away

Much as I love Microsoft, they do sometimes make some strange decision sometimes. Amongst these are:

• The insistence on displaying Feedback and Mobile Upselling Buttons or every blinking page!
• Adding a border around the site icon for all Modern pages – why?
• A random splodge of theme colour on the main tile of the Hero web part when it displays a title

Microsoft have provided a PowerShell command that hides the Feedback button, only (at the time of writing) it doesn’t work properly. It works for modern site pages but the button still shows up on system pages like the Site Contents page – grrr! We don’t even get a PowerShell option for the Mobile Upsell button and the explanation for this is that apparently each button is controlled separately by 2 different teams within Microsoft – like we care about that!

The reason a find these buttons so irksome is their all-pervasive nature and the fact that they cause confusion with simple users who think, when they are providing feedback, that they are talking to the IT department. Come on Microsoft, sort this out please it would take you no time all. In the meantime, the Kaboodle Branding Package to the rescue.

Actually, you are not limited to hiding these ugly buttons you can actually manipulate just about everything on the page. This is because your page payload can contain JavaScript and CSS overrides. So, if you wanted to simplify the UI by hiding the Share Site or the Following buttons you can do that very easily. Having said that, just because you can do something, doesn’t mean that you should. So, whilst I think its fine to hide stuff that you really don’t want (like that border that surrounds the site icon), I recommend you think twice before changing the position attribute of divs or you might end up with something that is no longer supported in a Responsive Design pattern.

Sadly, have found that CSS does not reach into the Suite Bar. So, either the Suite Bar is side-loaded in some kind of iframe or Microsoft have done something to prevent that from working. That’s a bit of a shame because it would be nice to be able to brand each hub-space individually, which you can’t do.

Microsoft go to great pains to point out that the suite bar is in artefact that belongs to O365 and not to SharePoint. You can brand the Suite Bar but only in a limited way and at a global level. Could do better here I feel.

So how does it work them?

Conceptually, its very simple. Everything is driven from a small configuration file which contains some JSON that specifies how the solution is to behave and what artefacts are to be loaded. That configuration file is named Config.txt and is stores in a top-level folder called SPFxBranding in the Site Assets library. So, the path for the configuration is consistent namely: <site URL>/siteassets/SPFxBranding/Config.txt.

When the Kaboodle Branding Package is deployed to a site and a modern page is loaded, it goes in search of a branding configuration file.

The key points are:

• If the site is a Hub Site then it looks to its own Site Assets library
• If the site is a Freestanding Site (not part of a hub) then it looks to its own Site Assets library
• If the site is a sub-site of a Freestanding Site then it looks for the configuration in the root web site of the site collection
• If the site is associated with a hub, regardless of whether it is a sub-site or the root web site in the site collection then it looks to Site Assets library of its associated Hub Site
• A configuration can act as a pointer to a configuration in any other different site

This last point is important, because what this means is that you could potentially have all Hub Sites using a single configuration defined in what I would call a Hub Master Site so you can have complete consistency across the entire tenancy. Simple, but elegant.

What does the Config.txt file look like?

Well its just a very simple lightweight fragment of JSON. The default Config.txt file looks like this:

Let’s look at each element in turn:

• RemoteConfigUrl: When left as an empty string the solution knows it has found the configuration settings that need to be applied. However, if this property contains the URL to a different web site then the solution is effectively redirected to that new site and uses the configuration defined there and will ignore any of the other settings defined within the current configuration file.
• GlobalNavigationStyle: This lists the style attributes to be applied to the global navigation items when the site is not associated with that navigation item (space).
• GlobalNavigationStyleSelected: The style attributes to be applied to the global navigation item when the site is associated with the navigation item (space).
• GlobalNavigationStyleHover: The style attributes to be applied to a global navigation element on mouse over.
• FaviconUrl: The absolution URL to a graphic icon file to be used as a favicon. Now don’t get your hopes up with this one because I can’t get this to work yet. I can see that a correctly referenced favicon gets loaded up in the page HTML but it doesn’t get picked up by the browser. I’m still investigating why this should be but my guess is that the suite bar is taking control of things. I’ll keep working on this one.
• HeaderUrl: The site relative link to a file that contains the HTML payload to be loaded into the header content placeholder. Obviously, if the property is set to an empty string then there is nothing to load.
• FooterUrl: The site relative link to a file that contains the HTML payload for the footer content placeholder.
• ScriptsURL: The site relative link to a file that might contain JavaScript or CSS that should be added to every page.
• ScriptLinks: A comma separated list of URLs that get added as script links to the page. This might be useful if you want to make sure that say jQuery is available on every page by loading it from a CDN.
• HideById: A comma separated list of elements Ids to specify elements that are to be hidden from the UI.
• HideByClass: A comma separate list of elements with are hidden based on their class name.
• HiddenFeedbackButton: When set to true, the Feedback button is hidden.
• HideMobileUpsellButton: When set to true, the Mobile Upsell button is hidden.

So how do I try it out?

Want to give it a shot? Then, head on over to product page for the Kaboodle Branding Package and find out how to download, install and use the solution.

If you have any suggestions for improvements please let me know.