WebMail Pro documentation

Creating new skin

Introduction

WebMail Pro uses Less and the skins are presented as sets of .less files, which are compiled into CSS upon building. Below, you'll find information on how to modify and build a skin.

Setting up prerequisites

In order to build a skin, you will need Node.js and npm installed - those provide Node environment and its package manager, respectively.

It is assumed that you're building the skin using the same WebMail Pro installation that skin will be used on. Of course, you can do that on your development system, as long as you have all the WebMail Pro files there.

Specific steps for setting up Node environment would depend on operating system you use. For Windows and Mac, installers are available at Node.js download page. For Linux, you can obtain the source code from the download page - but first, we recommend to check whether Node is available in package manager of the operating system. For example, in case of Ubuntu the following command would install both Node and npm:

sudo apt-get install nodejs npm

While building, it's assumed that main Node executable is called node - however, there are cases when it's called nodejs. To work around that, a symlink needs to be created:

sudo ln -s /usr/bin/nodejs /usr/bin/node

Building skin

  1. If you installed the product using developer's way and you already have node_modules in the root directory of WebMail Pro you can skip this step. If not, then open console / command prompt and make sure root directory of WebMail Pro is the current one. Run the following command:
npm install ./modules/CoreWebclient

It will add node_modules directory containing modules required for builder to work.

  1. Copy any skin in ./modules/CoreWebclient/styles/themes/ directory. Rename it supplying a name for your new theme.

The same needs to be done with skin found in ./modules/MailWebclient/styles/themes/ directory.

  1. Now, if you run the following command:
gulp styles:watch --themes YOUR_THEME_NAME

that will start the builder with watcher status active. The skin will be rebuilt every time any modifications to the skin source files are made.

If you only need to rebuild the skin once, simply use command below without :watch instead:

gulp styles --themes YOUR_THEME_NAME

Modifying skin

Basically theme consists of media data and styles.less file which can be treated as skin's configuration file. It holds variables and their values used by Less, as well as Mixins (Less' concept of hooks). The values are mostly self-explaining and the file has numerous comments explaining the purpose of those values.

Note: some modules can contain their own styles and overrides on per theme basis. It may be necessary to duplicate them in your new skin. To achieve this, search for .less files with the name of theme you copied in step 2, for example, DeepForest.less; rename the files you've found to YOUR_THEME_NAME.less.

MailWebclient module holds a number of variables which should be simply copied to file of new theme created under CoreWebclient directory. The entire content of modules/MailWebclient/styles/themes/THEME_NAME/styles.less file needs to be copied.

Adding skin to the product config

Once the new skin is ready, you need to adjust the product configuration and add a new entry to skins selection. That's done by editing data/settings/modules/CoreWebclient.config.json file:

"Theme": [
    "Default",
    "string",
    null,
    "Theme used by default" 
],
"ThemeList": [
    [
        "Default",
        "DefaultDark",
        "DeepForest",
        "Funny",
        "Sand"
    ],
    "array",
    null,
    "List of themes available" 
],

ThemeList defines a list of skins while Theme denotes the default one.