Developer Resource - Theming
Themes
Customizing or creating themes for Agent is a quick way to apply your own color palette to the application. The application has been broken down into a basic set of standard elements each having LESS variables that can be redefined to create a custom look without having to worry about structural layout concerns.
Themes also allow for a users personal preference of styles. Agent currently ships with three themes including Default, Dark and Quiet Light. The Dark and Quiet Light themes extend the Default theme by only changing colors where necessary while still creating a very different user experience.
About the Default Theme
The Default theme file (a5-theme.less) contains over 700 color, background, box-shadow and text-shadow variables that are used and reused to allow in a way that allows extending the Default theme much more manageable.
The Default theme variables are dash-named and prefixed with @theme. For example: @theme-background-color
There are just over 130 total theme variables of which over 40 are set by the remaining 90 uniquely assigned variables.
The Agent application utilizes third party libraries and styles, including Twitter Bootstrap and Kendo UI, which have each been forked into baseline. Each of these incorporated libraries have been modified just enough to allow for our Default theme be the basis for all of their colors as well. Using this Default theme as a foundation we've been able to make our Dark theme with just 94 assignments and the Quiet Light them with only 53!
Creating a New Theme
A new theme is created by extending the default theme.
The Dark and Quiet Light themes are examples of new themes. Review the styleguide\styles\less\themes\Dark.less and styleguide\styles\less\themes\Quiet Light.less files for examples on creating a new theme.
To create a new theme:
Add a new LESS file to the
styleguide\styles\less\themesfolder.The name of the file is important, and should match the name used in step two.
The first line of your new theme must be:
@import "../agent/a5-theme";This will include all of the default theme settings.In this file you can override the default
@themevariables. You can change the@camelCasedBootstrap variables (such as@btnTextColor) or change specific Agent elements and widgets through modification of the@a5-variables (such as@a5-alert-success-background-color).You can use the default theme file (
a5-theme.less) for reference.Add the theme name to the User Defined List named Themes. Remember to Refresh the application cache after editing the list.
Customizing an Existing Theme
An existing theme can be customized by editing one of the custom theme override files.
These are located in the styleguide\styles\less\custom\themes folder, and follow the filename pattern of custom-${themeFileName} where {themeFileName} is the name of the theme you wish to extend from the styleguide\styles\less\themes folder.
Theming Best Practices
The idea behind the baseline theme variables was to breakdown the default theme into basic user interface elements which are then built upon for more granular and specific widgets. For example the @theme-border-color is the most reused variable and with nearly 60 subsequent usages any change can have a nice impact on a custom theme. Use the theme variables according to how they are named. For example a border color variable is applied to a border color property and not a background property. This way you won't have unexpected behavior in your theme down the road where what you read in the code doesn't match what you see on the screen.
Theme Development Workflow
To run a continuous watch task that will automatically reload the browser (if using LiveReload), execute the less-watch task via gulp. This can be done in a number of ways. If gulp has been installed globally, simply run gulp less-watch. If not, ./node_modules/.bin/gulp less-watch. If using yarn, yarn run gulp less-watch will do the trick regardless of where gulp has been installed.
Making Custom Widgets Themable by Adding Themable Variables
While the baseline theme file provides a seemingly comprehensive list of tweakable variables we aren't able to account for your imaginative creations of your own custom widgets. To allow for custom themable widgets there is a custom-theme.less file with a similar purpose to the a5-theme.less file. This file is where you would add new theme variables that you apply to your custom widgets in custom-styles.less. Adding your new variables into custom-theme.less makes them available to new and customized theme files. Think of the variable assignments in this file as your default theme for your custom widget just like a5-theme.less assignments make up the baseline theme.
Naming your new themable variables should follow the naming scheme of the baseline @theme. Choose any prefix you'd like and stick with one for these examples we're using dt. After the prefix portion you would identify the scope of your item or widget. In the example it is a date widget and more specifically the today part of that date widget. The next section closely resembles the CSS properties with the exception of foreground which applies to text and icons that is sometimes actually the widget's background-color.
Item scope Property
|----------|----------------|
a {
background-color: @dt-date-today-background-color: red;
background: @dt-date-today-background: border-box red;
color: @dt-date-today-foreground-color: green;
border-color: @dt-date-today-border-color: @dt-border-color;
}In this example we're looking at the addition of an element state specificity. The highlight keyword which is used in place of hover, active, focused wherever it makes sense. Another example element state is be disabled.
Item scope Property (State)
a:hover { |----------|----------:---------:-----|
background-color: @dt-date-today-background-highlight-color: blue;
}You can chain these together to make variables that make sense when being used as well as when being extended.