Branding SharePoint Online

Even though the title for this post is Branding SharePoint Online, this is applicable to on-premises as well. Microsoft is suggesting that we should avoid creating custom master pages. Not that it should not be used, however we should consider other approaches such as themes and alternate CSS first.

The reason is, we usually create a custom master page by making a copy of the out of the box master page. So, when Microsoft releases updates to the master page with service packs (or even faster cycles in Office 365), our custom master page will not have those updates. It really takes a lot of effort to track and make updates to the custom master page.

If we can achieve the same goal with themes or alternate CSS, it would be much easier to maintain the branding with future versions of SharePoint.

Also, the new guidance is to avoid using the feature framework to deploy artifacts such as your style sheets, etc. The recommendation is to use the remote API such as CSOM because, features create unnecessary XML files on the file system to deploy our files.

We cannot apply custom master pages and CSS to other areas such as Yammer or Delve in Office 365. The Office 365 users will  usually navigate back and forth between SharePoint online and other areas such as Outlook, Yammer etc.

So, it is recommended to apply Office 365 themes which will be applied across the entire array of applications. Even though this is limited, we can get the basic branding across the entire platform.

To do this, click on the flyout at the top left and click on Admin

Click on Company profile -> Custom theming. Here you can edit the theme that best matches your company brand. This will be applied across Office 365.

If you want to reset the changes, click on remove custom theming.

If you want to brand a SharePoint site, you can create a custom theme using the Microsoft tool – SharePoint Color Palette Tool. This will give a bit more options than the Office 365 themes. After selecting the required options, we can save it as a .spcolor file. However, we can apply this only to SharePoint sites.

For setting the available out of the box themes, we can use a console application. Available themes include Orange, Green, Nature, Blossom, Breeze and Office(default). To set the out of box theme, we just have to get a reference to the web object and use the SetComposedLookByUrl method to set the theme. This method is part of the OfficeDevPnP.Core package. You can install this as a nuget package.

currentWeb.SetComposedLookByUrl("Breeze");

If you want to set a custom theme generated with the SharePoint Color Palette Tool, we can use the following code.

Web web = clientContext.Web;
web.UploadThemeFile("../../custom.spcolor");
web.UploadThemeFile("../../Background.png");

clientContext.Load(web, w => w.AllProperties, w => w.ServerRelativeUrl);
clientContext.ExecuteQuery();
// Let's first upload the custom theme to host web
web.CreateComposedLookByName("customTheme",
                      web.ServerRelativeUrl + "/_catalogs/theme/15/custom.spcolor",
                      null,
                      clientContext.Web.ServerRelativeUrl + "/_catalogs/theme/15/Background.png",
                      string.Empty);
clientContext.ExecuteQuery();
// Setting the custom theme to host web
web.SetComposedLookByUrl("customTheme");

I have uploaded the solution to github at CustomBranding project.

If we need more control, we can use the AlternateCSSUrl property to set our custom CSS page. With this, we can apply custom style sheets to our sites. I have listed the code for this below. You can get the latest code from the Microsoft Patterns and Practices site OfficeDev PnP. Basically, we are uploading our custom CSS file to Site Assets and then inserting a link to the CSS file using custom action.

Web web = clientContext.Web;

                    List assetLibrary = web.Lists.GetByTitle("Site Assets");
                    clientContext.Load(assetLibrary, l => l.RootFolder);

                    // Get the path to the file which we are about to deploy
                    string file = System.Web.Hosting.HostingEnvironment.MapPath
                    (string.Format("~/{0}", "CSS/contoso.css"));

                    // Use CSOM to upload the file in
                    FileCreationInformation newFile = new FileCreationInformation();
                    newFile.Content = System.IO.File.ReadAllBytes(file);
                    newFile.Url = "contoso.css";
                    newFile.Overwrite = true;
                    Microsoft.SharePoint.Client.File uploadFile = 
                    	assetLibrary.RootFolder.Files.Add(newFile); 
                    clientContext.Load(uploadFile);
                    clientContext.ExecuteQuery();

                    // Now, apply a reference to the CSS URL via a custom action
                    string actionName = "ContosoCSSLink";

                    // Clean up existing actions that we may have deployed
                    var existingActions = web.UserCustomActions;
                    clientContext.Load(existingActions);

                    // Execute our uploads and initialzie the existingActions collection
                    clientContext.ExecuteQuery();

                    var actions = existingActions.ToArray();
                    // Clean up existing custom action with same name, if it exists
                    foreach (var existingAction in actions)
                    {
                        if (existingAction.Name.Equals
                        (actionName, StringComparison.InvariantCultureIgnoreCase))
                            existingAction.DeleteObject();
                    }
                    clientContext.ExecuteQuery();

                    // Build a custom action to write a link to our new CSS file
                    UserCustomAction cssAction = web.UserCustomActions.Add();
                    cssAction.Location = "ScriptLink";
                    cssAction.Sequence = 100;
                    cssAction.ScriptBlock = @"document.write
                    ('<link rel=""stylesheet"" href=""" + 
                    assetLibrary.RootFolder.ServerRelativeUrl + @"/contoso.css"" />');";
                    cssAction.Name = actionName;

                    // Apply
                    cssAction.Update();
                    clientContext.ExecuteQuery();

The post Branding SharePoint Online appeared first on SharePoint Guide.