Branding requirements and general principles

Organizations typically want their portal to be unique. Custom branding can help to promote the corporate brand and values, and that's why a custom branding solution is essential for (enterprise) portals.

In the following sections, we discuss how to address these requirements.

General principles

Consider the following general principles when branding portals in a SharePoint Online environment:

The SharePoint Online service is constantly improving. Updates provisioned to the service may affect the Document Object Model (DOM) structure of out-of-the-box pages and the content of out-of-the-box files (for example, master pages). Developers must keep this in mind and should not rely on unsupported customization approaches (for example, the position of specific elements in the DOM structure of the page).

Avoid customizing master pages. Updates to the service may affect the structure of out-of-the-box master pages. If you have implemented a custom master page by copying the contents of any out-of-the-box master page, you must further monitor if this out-of-the-box master page is not updated, and re-implement these changes in your custom master page. Otherwise, some SharePoint functionality may behave incorrectly when your custom master page is in use. That's why customizing master pages leads to additional risks and maintenance costs, and we recommend that you avoid it when possible.

SharePoint Online portals must be considered a part of the overall Office 365 ecosystem. That's why every portal now has an Office 365 Suite Bar, and customizing it is not supported (see the section Office 365 Suite Bar).

Customize the look

There are several out-of-the-box ways for customizing the look of SharePoint portals:

Administrators can customize the Office 365 theme for an entire tenant.

A custom theme can be applied to a specific site.

These techniques can be used to "get" the needed colors and allow for flexible coloring across different portal sites. If more flexibility is needed, we recommend that customers start from an out-of-the-box master page (seattle.master) and apply a custom theme and/or use the site custom CSS settings (Web.AlternateCSSUrl) to hook up the needed CSS files. A custom logo image can be set by using the Web.SiteLogoUrl property.

These techniques are demonstrated in the following articles and PnP samples:

Office 365 sign-in page

Office 365 Suite Bar

The guidance for the Suite Bar from the Microsoft perspective is the following:

The Suite Bar is a tenant-level navigation component that allows users to easily move between all Office 365 services.

Your portal application does not "own" the Suite Bar, nor should it presume to do so.

Treat the Suite Bar as you would the browser toolbar in that it is not a part of your application.

You may modify/configure the Suite Bar, but only at the tenancy level, and only via the Office 365 Admin pages.

You should not use code to alter (move, hide) the Suite Bar within your application.

You should not re-use aspects of the Suite Bar (for example, the App Launcher icon) in your application.

If you decide to be "clever", you will most likely run into unexpected issues in the future.

Adjust the layout

When discussing adjusting the layout of SharePoint portals, usually the first option that is considered by developers is creating a custom master page. Although custom master pages are still supported, we don't recommend this approach due to the reasons mentioned earlier; custom master pages lead to additional risks and maintenance costs in the long-term.

Developers should consider alternative approaches that allow them to adjust the layout of SharePoint portals. These include:

Implementing custom CSS.

Using custom page layouts.

Implementing common branding elements (such as the "footer") by injecting client-side scripts (this approach is discussed in the next section).

Add functionality

Embedding client-side scripts in the pages can allow you to further customize the look and functionality of the portal. For example, this approach can be used to customize navigation controls, to add custom headers and footers to all pages of the portal, or to implement other custom UI blocks.

The following approaches can be used to embed JavaScript:

Add a custom action at the site or site collection level. This can trigger the execution of a piece of JavaScript on all pages in the site or site collection.

Add a Content Editor or Script Editor web part on a page by using actual JavaScript code or a link to a JavaScript file. This can trigger the execution of JavaScript code on a specific page.

Include JavaScript code or a link to a JavaScript file in the contents of a page layouts file. This can trigger execution of JavaScript on all publishing pages that use this page layouts file.

Note

The custom action approach works on "classic" sites only, including the current publishing portals.

The following PnP samples demonstrate how JavaScript embedding can be achieved:

Provision branding assets

The final step in implementing a branding solution is provisioning branding assets. Typically, these include images, CSS, and JavaScript files.

There are several approaches on how these files can be deployed:

Publish files to libraries in individual site collections. In this case, each site collection can use its own version of branding assets. Access to files is controlled by using standard SharePoint security mechanisms. However, updating files requires that you re-upload these to every site collection.

Publish files to a library in one site collection (central location). In this scenario, all site collections can use the single latest version of branding assets. Updated files must be uploaded to one location only. Administrators must ensure that users of all site collections have access to the files published in the central location.

Publish files to CDN (web application, Azure CDN, or Office 365 CDN). In this case, all site collections can use the single latest version of branding assets. Updated files must be uploaded to one location only. Using CDNs can improve performance; however, the content is stored outside of SharePoint, and that's why assets cannot be protected by using standard SharePoint security mechanisms (with the exception of the Office 365 private CDN capability, which can secure files on a CDN).

The PnP provisioning engine can be used to deploy branding assets to SharePoint libraries. When using the Office 365 CDN capability, the files are automatically provisioned in the CDN. When you use alternative CDN solutions, a custom provisioning approach is needed to publish files to CDNs.