Wijmo and Sass

We recently switched to Sass to make it easier to create and maintain Wijmo CSS files.

Sass improves CSS the same way TypeScript improves JavaScript. It provides modularization, variables, structure, compile time syntax checking, selector nesting, functions, and more. Over the last few years, Sass has become the most popular CSS preprocessor, being supported by all popular JavaScript frameworks and bundler tools.

Just like TypeScript, Sass is optional. You can use the CSS files we build with Sass and forget it exists. But if you want to customize the Wijmo styles, create your own themes, or create smaller CSS files that include only the Wijmo modules you use, then we suggest you use Sass.

If you choose to use Sass, you will a Sass tool. Our favorites are:

Folder Structure

We use the following folder structure for Wijmo's Sass files:

wijmo.scss                  // main scss file
misc
    _constants.scss         // color names
    _glyphs.scss            // Wijmo glyphs
    _mixins.scss            // utility functions
    _variables.scss         // theme variables
core                        // modules in Wijmo core
    _chart.scss
    _chart_hierarchical.scss
    _chart_interaction.scss
    _core.scss
    _gauge.scss
    _grid.scss
    _grid_filter.scss
    _grid_grouppanel.scss
    _input.scss
    _nav.scss
enterprise                  // modules in Wijmo enterprise
    _chart_finance.scss
    _multirow.scss
    _olap.scss
    _sheet.scss
    _viewer.scss 
themes                      // bundled themes
    wijmo.theme.cerulean.scss
    wijmo.theme.cleandark.scss
    wijmo.theme.cleanlight.scss
    // etc

Following Sass conventions, files with names that start with an underscore are included by other files and do not generate stand-alone CSS files.

The wijmo.scss file is used to generate our main CSS file, wijmo.css. It contains the following:

// wijmo.scss

// misc
@import "misc/mixins"; // functions
@import "misc/constants"; // named colors
@import "misc/variables"; // theme variables
@import "misc/glyphs"; // wijmo glyphs

// core modules
@import "core/core";
@import "core/input";
@import "core/grid";
@import "core/grid_grouppanel";
@import "core/grid_filter";
@import "core/chart";
@import "core/chart_interaction";
@import "core/chart_hierarchical";
@import "core/gauge";
@import "core/nav";

// enterprise modules
@import "enterprise/sheet";
@import "enterprise/multirow";
@import "enterprise/olap";
@import "enterprise/viewer";
@import "enterprise/chart_finance";

If you run this through the Web Compiler or any other Sass tool, you will get the regular wijmo.css and wijmo.min.css output.

Smaller CSS files

If you don't use any of the Wijmo enterprise modules and would like to reduce the size of your CSS files, you could create a wijmo-core.scss file that looks like the wijmo.scss above minus the last five lines (the ones that include the enterprise modules).

This will create a wijmo-core.css file that is about half the size of the full wijmo.css.

We have done this for you already. The wijmo-core.css file is included in our distribution. But you can use this approach to generate optimized CSS files that include only the modules your application needs. For example, you could create a CSS file that contains rules only for the input and grid modules.

Custom Themes

In addition to the standard wijmo.css file, Wijmo includes many custom themes. Most themes are created by overriding the value of a few Sass variables. For example, the cerulean theme is created from the wijmo.theme.cerulean.scss file:

// wijmo.theme.cerulean.scss -- cerulean theme
$wj-bkg: #fcfcfc;
$wj-txt: #082d43;
$wj-bdr: none;
$wj-hdr-bkg: #033c73;
$wj-hdr-txt: #fff;
$wj-sel-bkg: #2a9fd6;
$wj-msel-bkg: #77afc9;
$wj-cell-grp-bkg: #777777;
//� etc �

@import "../wijmo.scss";

The theme file sets some Wijmo variables and then includes the base wijmo.scss file. That's all there is to it. The output is a wijmo.theme.cerulean.css file that can be used instead of the standard wijmo.css.

NOTE: The theme files are self-contained. They replace rather than extend the standard wijmo.css file. This is a change from previous versions of Wijmo.