com.smartgwt.client.docs

Interface CustomSassSkins

public interface CustomSassSkins

Customizing Sass-based Skins

Support for templated skins

Some skins have a stylesheet generated from Sass templates and compiled with compass. Each such skin has a "template" subdirectory containing various files, including those used to regenerate the skin's stylesheet (skin_styles.css) using compass. The files of interest to a custom skin are in the template/sass directory:

Files you can edit

• _userSettings.scss - This file is initially empty and can be edited. It should contain Sass variables and font declarations intended to override settings in the builtin skin (see _skinSettings.scss and _base.scss below)
• _userStyles.scss - This file is initially empty and can be edited. It should contain CSS intended to be incorporated after the styles in the builtin skin (see _skinStyles.scss and _base.scss below), overriding both

Files that should not be edited

The other files in template/sass should not be edited and can be largely ignored (see the discussion below on Keeping the skin you extended up to date) - but their purpose is listed here:

• skin_styles.scss - This is the bootstrap file that lists the fragments to load and is executed by running 'compass compile' in the parent folder. There shouldn't be any need to alter this file - but you can do so if you want to add further custom fragments
• _base.scss - This file contains all the base CSS and the defaults for the supported variables in the builtin skin that your custom skin is based on. This file should not be edited
• _skinSettings.scss - This file contains Sass variables and font-declarations for the builtin skin, intended to override the defaults set up in _base.scss. This file should not be edited
• _skinStyles.scss - This file contains custom CSS for the builtin skin, to be appended after that in _base.scss. This file should not be edited

Creating a custom skin

A custom skin is created by copying and extending an existing one.

You can start from any templated skin but note that, if you want to make pervasive color/font alterations, for example, then you should consider starting from the "Cascade" skin, where variable values often cascade from one another, allowing simple, high-level changes to affect much of the skin.

In other templated skins, Tahoe, Stratus and Obsidian, where more of the variables are customized or overridden, changing a base variable value won't affect the parts that have been overridden.

To create a custom skin based on "Cascade":

• Copy the skins/Cascade directory to skins/MySkin
• In skins/MySkin/load_skin.js, find and replace instances of "Cascade" with "MySkin"
• In skins/MySkin/template/sass/_userSettings.scss, declare $theme_name: 'MySkin'
• Change to skins/MySkin/template and run 'compass compile'

Customizing your skin

What to edit

As noted at the top of this discussion, the files you can edit are in the template/sass directory - specifically, _userSettings.scss for customizing supported variable values and _userStyles.scss, for overriding existing styles.

You can see the CSS classes that can be overridden in _base.scss.

You can see the list of available variables in _skinSettings.scss, grouped and named according to what effects they have. You can copy the variables you want to override into your _userSettings.scss file, change their values and run 'compass compile'.

By way of example

Try adding these settings to _userSettings.scss and running 'compass compile'

$primary_hue: 120; // generally green rather than blue
$standard_widget_border_color: #006400; // darkgreen borders for widgets
$standard_button_border_radius: 5px; // give all buttons rounded corners

After editing

When you make changes to _userSettings.scss or _userStyles.scss, you can compile them into your skin by running 'compass compile' from the skins/MySkin/template directory. This compiles the various fragments from the template/sass directory (listed in skin_styles.scss) to produce the skin's stylesheet, at skins/MySkin/skin_styles.css.

After making changes and running 'compass compile', clear your browser cache before refreshing your test page, to ensure the old skin_styles.css isn't cached.

Keeping the skin you extended up to date

As noted earlier, some of the files in template/sass should not be edited. This is because, from time to time, we may make fixes or improvements to our builtin skins - when this happens, you can keep your custom skins up to date, without clobbering any of your customizations, by copying _base.scss, _skinSettings.scss and _skinStyles.scss from the skin you extended to your skin's template/sass folder, replacing the existing copies. From there, running 'compass compile' will incorporate the latest builtin skin changes into your custom skin, without affecting your existing customizations.