Customizing UI16 Through CSS and System Properties

When you've got two UI versions included in your instance (such as with Geneva, having UI15 and UI16), customizing the user interface can become somewhat complicated. You could spend hours modifying a theme, or modifying the default UI, only to find that that doesn't modify UI16 at all, and there's no real way to tell. 

In this article, I'm going to guide you through modifying every little bit of UI16's theme. I'll also show you how to make a custom theme that users can select, and modify the UI16 UI to include your company's branding, logo, and slogan. 

First up, I want to point out that ServiceNow provides some great documentation on this - unfortunately, some of the documentation is just incorrect when it comes to UI16. What isn't incorrect, is incomplete. 

I know it's a little frustrating not to have everything in one place, but ServiceNow is a huge platform that has to support customers running multiple previous versions. Things are bound to fall through the cracks. With that in mind, this article focuses on Geneva and UI16, since it is the latest and greatest, and since it's also the most difficult to find accurate/complete documentation on. 

Most of what I've done here is scour the ServiceNow documentation for articles like this - which is a great place to start, but is unfortunately vastly incomplete - and then I'd compare it with articles like this. With that information, I'd make some guesses about how the system behaves, and then test those guesses to determine the correct answer. This article is the sum of all the information I was able to piece together. 

Creating Custom Themes

In addition to the default theme, ServiceNow comes with several built-in themes which, in UI16, can be selected from the System Settings sprocket at the top-right of the page, then going to the Theme tab. In this section, we're going to learn how to create our own custom themes that will show up right there next to the built-in themes. 

To get started, navigate to System UI > Themes. In this list, you might notice that several of these themes match the names of themes you saw in the System Settings menu, such as "Blimey" and "Clean". But there are loads of other themes here too. They're not all inactive, but you can't see them in the Themes menu. What's the deal? 

servicenow custom themes configuration form

There is a field on the Themes table, called Device. Quite unintuitively, if the Device field is set to Browser, then the theme only applies in UI11. If set to Doctype, if only applies to UI15. Finally, only if it's set to Concourse, does it apply to UI16
Why? -- I have no idea why. 

Anyway, click on New to create a new theme, and name it whatever you like. For the Device field, you'll want to select Concourse if this is for UI16 (or you could select Doctype if you want to design a UI15 theme, but I won't go into the exact CSS to do so here). 

To override the CSS of the default system theme, you'll need to add a CSS selector (like $navpage-header-bg) and a hex color value. For example: 

$navpage-header-bg: #fff
$navpage-nav-mod-text-hover: #fff

The above ~CSS would make the header background white, as well as the module text color when hovered over. To find all of the CSS properties and what they do, head back over to System Properties > Basic Configuration UI16 with the update set that I'll discuss in the next section installed.

Pro Tip: You can find some additional CSS properties in the System Properties > CSS page; however, you'll notice that by default, even in a fresh Geneva instance, this includes UI properties for UI14. Strange. To remove them, go to the URL for the page, and find "sysparm_category%3DCSS,UI14%2520CSS". Change that to "sysparm_category%3DCSS%20CSS". These properties are for customizing fonts and some other less-accessible bits. 

Hovering over the labels for any color field on that properties page, will show you the property name (as you can see in the screenshot to the right). These property names will look something like css.$navpage-header-bg. Simply remove the "css." from the beginning of the property name, and that'll tell you the CSS property to add to the CSS field on the Theme form. In this case, "css.$navpage-header-bg" becomes "$navpage-header-bg". Add that to the Theme form on a new line in the CSS field, then a colon, then the hex value for a color you want to   set.

By using the update set I mentioned above (and below), you'll unlock all of the 23 CSS properties that can be used in your custom theme. You can see a list of them here

When the theme you're creating is selected, the CSS defined here will override the properties you specify on the System Configuration UI16 properties formatter page. Any properties you don't specify/override will revert back to their defaults, which you can see in the System theme. 

Customizing the Default Theme

Adding themes to your instance is a little unintuitive, but isn't too difficult, once you sort out how to do so in UI16; we'll go over that shortly. First, what if we want to customize the default UI16 theme? 

We could create a custom theme, and then add a global preference to the sys_user_preference table, so all users see it as their default until they select something else -- but there's a better way. 

There is in fact, a properties page specifically for customizing some of the CSS properties, as well as many other important components of UI16 (banner image, page header caption, browser tab title, etc.). To get there, go to System Properties > Basic Configuration UI16 in the Application Navigator. This "properties formatter" page is really cool. If you're not familiar with these sorts of pages, here's a short digression on how they work:

If you navigate to http://<yourinstance>$, you'll see a blank page and a Save button. This is the properties formatter. You can pass in "sysparm" arguments to this page via the URL, in order to display certain lists of properties. For example, to see all of the properties in the category "System Configuration UI16", you can append "?" to the URL (to indicate URL-arguments are about to be passed) and then add sysparm_category=System Configuration UI16 or, in URL-escaped characters: sysparm_category%3DSystem%20Configuration%20UI16. You can add another argument just to make things look pretty, to customize the browser tab title: &sysparm_title=UI16 Configuration
The final URL would look something like this: 
http://<yourinstance>$ Configuration UI16&sysparm_title=UI16 Configuration

This page formats properties (hence the title, "properties formatter") so that you've got a quick and easy way to view a big chunk of system properties, in a friendly way, as fields in a view. The properties that display here, are all of the properties that are in the System Configuration UI16 category. 

Unfortunately, there are many properties missing from this page, that we can actually edit directly in CSS. Double-unfortunately, editing the CSS for the default theme is really difficult (though it's trivial for custom or non-default system themes).
This means that we have to get clever. 
I love it when we have to get clever. 

The system property that controls the color of the background of the application navigator and a bunch of other things in the navigator section, is css.$navpage-nav-bg. If you were to create a custom theme using CSS, you could use the CSS property $navpage-nav-bg.
See the similarity?

The system properties that control the CSS styles of the default theme simply correspond to the CSS selectors you would use in a custom theme, with "css." at the beginning. Armed with this knowledge, we can now create our own system properties that correspond to those CSS elements. In fact, if we add them to the System Configuration UI16 category and give them useful descriptions, we can even display them on this properties formatter! 

Pro Tip: We've built an update set that you can load into your Geneva instance, in order to add these properties to your configuration page. This will save you from having to slog through loads and loads of pseudo-CSS and properties, and give you a single interface to update your default system theme. We've also modified the existing properties that are part of the UI16 configuration property formatter to have far more useful descriptions. We strongly recommend that you download the update, and deploy it into your instance. 

With the above update set deployed into your instance, you can edit any of the available default system color properties from the System Configuration UI16 application navigator module.