Often times you will need to customize certain appearance aspects to suit your application's brands and identity. The Unified Modern theme customization is not performed on the CSS output itself. Instead, you make changes to the theme source which will be compiled into the designated CSS files.

The WebUI theme source is written in SCSS language, a special type of file which adds lots of additional functionality to CSS like variables, nesting and more which can make writing CSS easier and faster. The SCSS source files will then be compiled by the server running a web app to output a traditional CSS that browser can understand.

On this page:

Prerequisites

Before you can customize the WebUI theme source, make sure you have installed and configured a SCSS compiler in your development machine.

There are a good many applications that will get you up and running with Sass in a few minutes like: CodeKit, Compass.app, Ghostlab, Hammer, Koala, LiveReload, Prepros, Scout, etc. The WebUI theme source is compatible with most of the SCSS compilers available today. Based on our experience, we highly recommend one of the following SCSS compilers:

  • Web Compiler Extension for Visual Studio 2015
    A free Visual Studio extension created by Mads Kristensen that compiles LESS, Sass, JSX, ES6 and CoffeeScript files directly within Visual Studio or through MSBuild.
  • Node Sass Library
    If you're familiar with Node.js and already have it configured in your development machine, you might want to check out node-sass module which is a wrapper around libsass engine. The node-sass compiler performs fair faster than other compilers, and also provides a command-line interface that works in various operating system.

This page describes how you can configure Node Sass library. In order to do this you will need to perform:

Install Node.js

Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient. Node.js' package ecosystem, npm, is the largest ecosystem of open source libraries in the world. Get the installer of Node.js from their download page then install.

Installing Node.js is easy and straight forward:

  1. Visit the home page: nodejs.org.
  2. Click the “install” button to download the installer.
  3. Run the installer (make sure you tell the installer to add references to your PATH system variables).
  4. Restart your PC.

Almost everything you do with Node is via a command line. You can use either the standard Windows cmd.exe or Windows PowerShell (or, indeed, any other command line interpreter (CLI) you may have installed).

To use the standard Windows command line:

  1. Press Win + R (for Run).
  2. Type: cmd
  3. Click OK.

After installation completed, checking that Node is installed is as simple as opening a command line and typing:

node --version

 

Hit enter and you’ll get a result, something like:

Install Node-sass

Node-sass is a library that provides binding for Node.js to libsass, the C version of the popular stylesheet preprocessor, Sass.

It allows you to natively compile .scss files to css at incredible speed and automatically via a connect middleware.

To install Node-sass, open a command line and type:

npm install node-sass -g

Hit enter and you'll get the following result.

Sample Scenario: Customizing SCSS Variable

With everything sets up, we're now ready to customize the WebUI modern theme. Customizing the WebUI theme is designed to be easy and straightforward, thanks to the unified theming framework and the leverage of modern stylesheet preprocessors. Instead of making changes to the CSS styles directly, you can easily modify the predefined SCSS variables which affect all styles across multiple components that reference the variables.

For example, consider that you want to change the focus border color of all WebUI input components, all you need to do is defining the $control-frame-border-focus variable in the _custom-variables.scss file such as shown below.

// original
// $control-frame-border-focus: $input-border-focus !default;

// change to
$control-frame-border-focus: orange;

Save the changes in _custom-variables.scss file. Open command prompt and type the following in order to compile the modified scss file and generate the css file.

node-sass c:/Test Project/EmptyWebAppUnified/Themes/webui-bootstrap/scss/webui-bootstrap.scss c:/Test Project/EmptyWebAppUnified/Themes/webui-bootstrap/css/webui-bootstrap.min.css --output-style compressed -w

The webui-bootstrap.min.css file is updated showing the changes that we made in scss file.

.common-combo.active:focus, .common-input-text-active:focus {
    color: #555;
    background-color: #fff;
    border-color: orange;
    outline: 0;
    box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075), 0 0 8px rgba(255, 165, 0, 0.6);
}

The screenshot below shows an example result of WebCombo and WebInput before and after the SCSS variable is customized. Notice how a single variable customization affects all WebUI components sharing the same semantic. At this point, you should have gain better understanding of the WebUI Unified Theme goals.

Before:

After:

Related Topics