Custom Theme Creation and LESS CSS

By on July 22, 2011 9:12 am

As a part of our Free Dojo Support initiative, we received the following questions with regard to custom theme creation and using LESS CSS to create and compile CSS files.

The Question

I have a few questions related to the creation of custom themes; best practices, organisation etc., especially considering the switch to LESS for the Dijit core themes.

We have a Dijit-heavy application, styled using a custom theme based on Tundra. The theme has accumulated lots of cruft over the last few years, for various reasons, so I intend to refactor it over the next month and am keen we don’t make the same mistakes as before.

So my questions are:

  1. For the current theme, we add the ordered classes “tundra custom-theme-name” to the <BODY> tag and our theme overrides the default values. Does this technique hold for the more recent version of Dojo? Is there a more efficient way then loading the base theme and then loading the custom theme, in the same page (aside from manually writing the CSS rules)?
  2. Am I right in thinking that Claro, being defined as a set of LESS rules, can be loaded on the fly if the LESS JavaScript is in the page, or compiled into a theme (via Node.js, I think) for the production environment? Would you advise us to split dev/prod up in this manner (being impractical to build the theme for every change in a dev environment)?
  3. We’re working in a Windows-only environment, and I understand that Node is still fiddly to setup under Windows. Do you suppose this would be an issue?

Our Response

Excellent questions indeed! Dijit theming is a very popular topic as branding is an important part of marking any UI. Here are answers to your questions:

  1. Your present strategy of using two className’s on the <BODY> element is exemplary; adding multiple className’s allows you to load the Dijit theme and override those rules to your desired settings. For the CSS rules you choose to customize, duplicate its corresponding LESS file and place into its own theme CSS folder, mimicking Dijit’s structure. Doing so will make your CSS more maintainable when upgrading Dojo versions in the future. Place only the selectors and properties you want to override within your .less file to keep your custom theme more manageable and compact.

  2. Your thoughts are correct. The .less files may be loaded into the page and parsed using less.js, but to prevent potential conflicts, it’s important to parse the .less files before including Dojo.js. When it’s time for your application to be pushed into production, the .less files should be compiled and pushed to a CDN for optimal loading.

    Another resource available is, which can compile and minify your CSS any time you save a .less file. Unfortunately is presently only available on Mac.

  3. NodeJS is in fact known to present more problems on Windows-based machines, but NodeJS version 0.5.1 provides a Windows binary which should make using LESS on Windows a bit easier. Since the lessc binary that comes with Less will only compile one file at a time (i.e. not a directory), the Claro Dijit theme comes with a compile.js which finds each .less file and compiles each file found.

    To complete this process, do the following:

    1. Download the Windows Node binary
    2. Download the LessJS source
    3. Navigate to the claro theme folder (C:\path\to\dojo-release-1.6.1-src\dijit\themes\claro) and edit the following line within compile.js:
      // CHANGE 'C:/less/lib' to wherever your less/lib folder is
      require.paths.unshift('/opt/less/lib', 'C:/less/lib');
    4. Run path/to/node.exe path/to/compile.js.

    If your configuration is correct, all .lesss files within the theme directory will be parsed. If you’re familiar with or prefer Cygwin, there’s a detailed tutorial on installing Node with Cygwin.

Excellent questions and happy theming!

Next Request Please!

Have a Dojo question you’re just dying to ask? Get your free Dojo support now! Or sign-up for the Best JavaScript and Dojo Support available to get all of your questions answered all the time!