Frontend Styling

Agent has been designed to be easily customizable not only in functionality, but also in appearance. This wiki will cover what vendor styles we include, the architecture that Agent has used to build it's css and how to customize it.

LESS

LESS is a precompiler for CSS that allows for easier code writing and use of some constructs that aren't built into CSS natively, most importantly variables, mixins, and inheritance. The syntax of LESS is very similar to CSS so reading the code should not be difficult, and LESS's website has very good documentation.

Compilation

Since we use LESS, this must be compiled into CSS before the app can use it. In order to do this, we leverage grunt. Specifically, there is a grunt less task that will compile all the LESS files and output the generated CSS files to the correct location.

Along with grunt less, there is a developer-friendly task, grunt less-watch. This is an ongoing task that watches for changes to the LESS files, and when one occurs immediately recompiles the LESS. This makes developing styles for your customizations much faster.

Vendor Styles

Agent leverages Twitter Bootstrap 2.3.2 at its core. The grid is used extensively throughout the app, along with form styles, buttons, badges, etc. In addition to that, Agent also adds Selectize, bootstrap-timepicker, bootstrap-datepicker and nprogress styles. Terelik's KendoUI styles can also be found though we've kept it separate and is only be used on the Calendar pages.

Architecture

The CSS architecture Agent uses is called Object Oriented CSS, or OOCSS for short. This type of architecture strives for reusability, fast developer understanding, and robust styles. The two main principles of OOCSS are

1. Separate Structure and Skin
2. Separate Content from Containers.

We make use of LESS's variables to define and reuse values throughout our stylesheets. The variable names can be found at the top of each a5-*.less file and in a5-variables.less under the styleguide/styles/less/ directory. All of the visual styles for the baseline theme can be found in a5-theme.less.

Theming

Using our OOCSS architecture we created a straight forward way to change just the colors, or skin, of the Agent application by using themes. The baseline code includes the default Agent theme, a "Dark" theme, a "Blue" theme and lighter colored theme called "Quiet Light". You can get a idea of how theming works by opening up one of the alternate themes to see how various LESS variables are redefined to cascade throughout the site style.

The main method of changing the look of Agent is by customizing an existing theme or creating a new theme of your own. For basic customizations of the default theme you'll need to add your modifications to the custom-default.less file in styleguide/styles/less/custom/themes. All of the default theme variables that can be changed can be found in styleguide/styles/less/agent/a5-theme.less.

When adding new variables for custom elements you've created those variables need to be added into the custom-theme.less file. Then a widget you've added to Agent can be themed in the same manner the rest of the site is themed. If you added a variable @mycompany-widget-background-color: #444 to that file it then can be re-set in the other custom theme files allowing you to continue to support multiple themes for your custom work.

The complete theming guide is available in the Dovetail Agent Theming documentation.

Next: Backend Introduction