Kaboodle Branding Package

The Kaboodle Branding Package is a powerful SharePoint Framework (SPFx) Application Customizer solution that allows you to customise SharePoint Modern pages in a way that can be consistently applied across a single site collection or to all the sites associated with a Hub Site. You can even define branding customisations in one place and have it applied to every site in your tenancy where the Kaboodle Branding App has been added.

Overview

Modern SharePoint pages don’t have a master page and there is no easy way to add custom CSS or JavaScript to every page in a site collection, Hub Site or tenancy in a consistent and controlled way. As such it is very difficult to apply custom branding to say:

Add a custom footer or header to every page
Tweak style attributes to personalise the UI
Hide unwanted elements such as the Feedback Button or Mobile Upsell button

Fortunately, Microsoft does provide a supported way of adding an additional payload to Modern pages by the means of an SPFx Application Customizer solution.

Solutions such as the SharePoint Starter Kit provide some excellent demonstrations of how an SPFx Application Customizer can be used to deploy configurable content to Modern pages but the solution is scoped to a single site collection and offers no way to implement consistency across a number of different site collections. That’s where the Kaboodle Branding Package comes in.

Features

When users access Modern pages, a simple configuration file is checked to see if additional artefacts should be added to the page. These artefacts offer the following potential capabilities:

The ability to add an arbitrary payload of HTML, CSS and/or JavaScript to the header and/or footer section of all Modern pages in the site in which the solution package has been installed.
The ability to add custom script, script links, CSS and any other page elements permissible within the site – so you could use this approach to add jQuery to every page for example.
A way to easily hide elements that are often not wanted such as the Microsoft Feedback and Mobile App Upsell buttons.
A means to provide a consistent set of customisations to:
- All the sites and sub-sites within a single Site Collection
- Be shared between several Site Collections
- All the sites and sub-sites associated with the same Hub Site
- All sites and sub-sites in the entire tenancy
It provides a way of associating sites within a Hub Site to a top-level global navigation item which can then be styled accordingly so that sites can be logically associated with different ‘spaces’ such the Intranet, Teams or Projects for example. In other words, the global navigation menu of Hub Sites can branded to indicate a context for the site.

Getting Started

The remainder of this article addressed the following:

Where you can download the solution package
What preparatory steps that need to be taken in order to successfully deploy the solution package to your tenancy
How to upload and configure the solution package in the tenancy App Catalog
Taking the solution for a test drive

Download

The solution package consists of a single file called KaboodleBranding.sppkg and it can be downloaded from here.

Tenancy Preparation

Before you can install the package you first need to make sure that your tenancy is properly prepared. That involves:

Ensuring a SharePoint App Catalog site has been provisioned
Ensuring that the tenancy has been configured to act as a public CDN

Configure App Catalog

If your tenancy already has an App Catalog you can skip this section.

All custom solutions require an App Catalog to be provisioned as this is the place where custom solution packages are uploaded and deployed for use within the tenancy.

Configuring an App Catalog is beyond the intended scope of this article but Microsoft provide a number of resources that can be used to step through the process. We recommend starting with the following link:

https://docs.microsoft.com/en-us/sharepoint/use-app-catalog

Adding and Configuring the Solution Package

There are 2 steps involved here:

Uploading and deploying the solution package to the App Catalog
Configuring the properties of solution package in the App Catalog

Upload the solution package to the App Catalog

Navigate to App Catalog for you tenancy and click on the Apps for SharePoint link. Then upload or drag and drop the downloaded solution package, the KaboodleBranding.sppkg file, into the App Catalog.

This will trigger the pop-up of the “Do you trust…” dialog.

Click the Deploy button to complete the deployment of solution package

Edit the solution properties for the solution item

Click the edit button to access the solution package item properties.

Apply the following values for the properties as shown and listed below:

Short Description: Kaboodle Branding Package
Description: Provides the ability to apply custom branding elements consistently within a single site collection, across a Hub Site or throughout an entire tenancy.
Icon URL: https://kaboodlesoftware.files.wordpress.com/2018/10/spfxbrandingapptile.png
Publisher Name: Kaboodle Software
Support URL: https://kaboodlesoftware.com/products/framework-solutions-for-sharepoint-modern/kaboodle-branding-package/

Click Save to apply the property updates.

Solution Activation

Once the solution has been successfully deployed and the correct properties applied, the next step is to add the solution to a site and take it for a test run.

Login and navigate to a suitable test set with an account that has sufficient permissions to create a new SharePoint list. We recommend using the root web in a site collection but that it will still work if you choose to deploy it on a test sub-site so long as the account has sufficient permissions to create a list at the root web site.

Although the process for installing and configuring the solution is essentially the same for all sites, in this walk-through we will start by using a free-standing site, that is to say a site that is not currently associated with a Hub Site. We will come back to Hub Sites later.

Go to the Your Apps page of the test site where you will see the Kaboodle Branding Package Solution as shown below:

Click on the app tile to install the solution. It may take a few moments for SharePoint to complete the installation process.

Creating a default configuration

When the solution has finished loading, navigate to the homepage of the site and you will see that a yellow footer has been added as shown below:

The message in the footer explains that the site is not currently associated with a Hub Site and that a branding configuration file cannot be found.

When a site is not associated with a Hub Site the solution looks for a file called Config.txt in the SPFxBranding folder of the Site Assets library in the root web site in the Site Collection.

As this configuration file does not currently exist, the footer also shows a button, which when clicked, will create a default configuration. Go ahead and click the button and, assuming you have the necessary permissions, an alert dialog will report that a new default configuration has been created for the Site Collection, as shown below:

Click OK and the page will reload and will now display a default footer as shown below:

The footer contains a link to where the newly created branding resources have been created.

Note that if neither the Site Assets library nor the SPFxBranding folder need already exist in the site. Clicking the button will simply create whatever is needed.

The default branding solution implements a sliding footer panel using jQuery and you can click on the up arrow in the centre of the footer to reveal it’s contents.

The contents of the default footer includes a couple of Kaboodle brand logos and a collection of links to some useful resources. Click the footer again and it will slide to the closed position.

Of course you will be able to change that content of the footer to be whatever like, or not have a footer at all, as described in the Branding Configurations section of this document.

Hub Site Configurations

If the site in which the Kaboodle Branding Package has been deployed is not a free-standing site but rather is already associated with a Hub Site then no local branding configuration is required as the solution will go in search of the branding configuration defined in the Hub Site.

If a Hub Site contains a branding configuration then that will control what additional artefacts get loaded into all Modern pages in the site. If the Hub Site does not contain a configuration file then a similar warning footer will be displayed, inviting you to create a default configuration for the hub in Hub Site.

In the screenshot below, I have now associated the test site with a Hub site called INTRANET and it can be seen that the configuration file not resides in the Hub Site (/sites/Communication) rather than using the site collection configuration we just created a moment ago.

If a site is, or is going to be, associated with a Hub Site then there is no need to create a local configuration. A local configuration is only required if site is in a free-standing site collection.

Branding Configurations

If you click on the link in the default footer, it will open the SPFxBranding folder, which by default will contain the 3 files shown in the screenshot below:

Config.txt

The default contents of the Config.txt contains a fragment of JSON as shown in the screenshot below.

This JSON file is used to tell the solution how to apply branding changes to the site and where to find content that is to be loaded into the header and/or footer content placeholder on Modern pages.

There are 13 elements in all and their purpose and function is detailed below:

RemoteConfigUrl: When missing, or 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 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 payload to be loaded into the header content placeholder. Obviously, if the property is missing or set to an empty string then there is nothing to load.
FooterUrl: The site relative link to a file that contains the 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 element 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.

In this default case, the Kaboodle Branding Package knows that this is the configuration to use, as the RemoteConfigUrl property is an empty string. If the RemoteConfigUrl property pointed to another web site then the configuration for that web site would be loaded instead.

By using branding redirects in this way it is possible for every site in the tenancy to use a single, centrally managed, branding configuration, regardless of whether they are associated with a Hub Site or not.

In the default configuration the ScriptLinks property is used to specify the CDN URL of jQuery, for which we need to have a references so that the footer panel will slide up and down gracefully.

The configuration also hides the Feedback and the Mobile Upsell buttons by default.

And the configuration also points to 2 files, the Footer.txt and the Scripts.txt file which will be loaded into the content placeholders on Modern pages. These payload files are specified by a site relative URL and so they must reside within the same Site Collection as the Config.txt file, although not necessary in the same folder or even the same library as the Config.txt file. However, its usually convenient to store everything in the same place.

The Scripts.txt file

The content of the default Scripts.txt file is shown below:

It can be seen that the file contains a single jQuery function that just toggle-slides the named element called ‘slidingFooter’ which is just the div in the Footer.txt file that needs to slide into view when the lower div for the footer bar is clicked.

On completion of the slideToggle action the function toggles between displaying an up-arrow or a down-arrow character identified by the explicit character codes.

The Footer.txt file

This file contains the payload that is actually inserted into the footer content placeholder. It’s just plain old HTML with some CCS and to get the icons I included a reference to Fonts Awesome.

I’m not going to walk through my markup in the default Footer.txt but if you do want to examine it and adapt according to your needs that’s fine by me. You might want to save the file with .html extension and open it up in a suitable editor such a VS Code or Notepad++.

Here is the content of a very much simplified alternative footer file which I named Footer.html and uploaded to the SPFxBranding folder.

I then updated the Config.txt file to so that the FooterUrl property of the configuration now points to the Footer.html file rather than the default Footer.txt file. The result is shown below:

Global Menu Context

As brilliantly useful as the Hub Sites are for defining a global navigation menu that is consistent across all sites in the hub, the standard offering misses a trick in that there is no native way to apply custom styling. Not only do I want to apply custom styles to the menu but I also want to use it as a kind space-indicator, so that I can provide a context to the user so that the can associate sites with a global menu item and have the relevant menu light-up when a matching site is selected.

I suppose I want a logical tabbing system that works at the global navigation level. And that’s exactly what can be achieved with the Kaboodle Branding Package.

If you refer back to the Config.txt file you will see that the JSON contains 3 Global Navigation Style properties that are used to specify the style attributes to be applied when the menu item is hovered over, when it is selected, that is to say there is a logical association between the site and a global navigation menu item, and the normal state, when not such association with the menu item exists.

All that is required is a means to associate the site with a global menu item and then the Kaboodle Branding Package can apply the appropriate styles to the menu items.

Associating a site with a global menu item couldn’t be easier. All you have to do is edit the sites description and provide the title of the associated menu item as the start text for the description.

In the screenshot below you can see that I have set the site description to be “Projects” and that’s enough for the solution to understand that I want this site to be associated with the PROJECTS global navigation menu item.

Any site in the Hub with a description starting with “Projects” will light-up the PROJECTS menu item. In a similar way, I can associate other sites in the hub with other global navigation items simply by setting their descriptions to start with “Teams”, “Communities” or “Apps” etc.

Note that the name mapping is not case sensitive and that if a site cannot be matched with a global menu item then none of the items light up.

This is a simple but effective way to provide users with some additional context information about the site they are currently viewing.

Known Issues

Hub Sites are a fairly new construct in SharePoint Online and thing sometimes get plagued by some over-zealous caching which may lead you (and the solution) to think that the site is no longer associated with a hub.

This seems to happen most often when the branding of the Hub is changed but these changes are not instantly pushed to associated sites. This normally sorts itself out in a couple of hours but if you can’t wait that long then we have found that breaking the connection with the hub and then re-establishing it again, usually resolves things straight away.

Also, be aware that if you navigate to from site in a Hub where the Kaboodle Branding Package has been activated to a site in the same hub where the package has not been activated then the menu context styling cannot unload (you need the solution to do the unloading). This might be a little confusing because you would expect that none of the menu items would light-up but it more a case of solution not being able to switch the light-off from the previous location. The solution is easy, just enable the Kaboodle Branding Package in all sites in the hub.

Resources

If you are interested in finding out more on how we built the Kaboodle Branding Package then please check out the associated blog post.