Skip to content

UI Theming

Jump to bottom
kevinpschaaf edited this page Oct 17, 2012 · 11 revisions

These are (probably) the docs you're looking for.

However, please be aware that the support for dynamic stylesheets described in this article is not included in the most recent official release of Enyo (2.0.1). Look for it to appear in the upcoming 2.1 release.

UI Theming

Overview

Enyo offers a first-class UI widget set called Onyx, which contains a wide variety of native-quality controls for building Enyo applications. While you are certainly welcome to use Onyx controls straight out of the box to develop your app, we know that many developers will want to adapt the look and feel of these widgets to meet the design requirements of their particular projects. To that end, we offer three discrete "theming" strategies.

Which strategy will work best for you depends largely on the degree of customization you need. In this document, we discuss the three approaches to theming, proceeding in order from least-effort-and-least-flexibility to most-effort-and-most-flexibility:

  • Variable-Based Theming: Customization of pre-defined variables that control Onyx styling
  • Rule-Override Theming: Free-form overriding of rules that control Onyx styling
  • Library-Based Theming: Creation of new Enyo kinds, extending Onyx or the Enyo core UI

Variable-Based Theming

In variable-based theming, you simply override the default values of certain variables that are used to generate Onyx's CSS stylesheets. For example, you could set the @onyx-toolbar-background variable to orange to make all of your app's onyx.Toolbar controls orange.

Since release 2.1, Enyo has included support for LESS, a dynamic stylesheet language that extends CSS with features such as variables, mixins, operations, and functions. Enyo's variable-based theming leverages LESS to break out common styling parameters into semantically-named, easy-to-override variables.

Enyo's LESS Integration

If you include .less files alongside .css files in your package.js, they can be transparently compiled into traditional CSS, either in the client during development (by including LESS's client-side less.js library in Bootplate's debug.html file), or as part of the minification process (via LESS's Node.js-based compiler, now integrated into the Bootplate deploy script). This capability is enabled right out of the box, without any additional tools or setup.

If you're wondering how this affects backward compatibility, please note that using LESS with Enyo is completely optional. Pre-compiled .css files for Onyx are provided alongside the top-level .less files; if the client-side less.js library is not loaded and Enyo's loader finds a .less file while parsing a package.js file, it will fall back to loading the .css file of the same name. As such, you are free to modify CSS directly, or use a server-side tool such as CodeKit to pre-compile your LESS to CSS instead of using the client-side compiler. Additionally, you may pass the "-c" flag to Bootplate's deploy script to enable similar CSS-fallback behavior when deploying your app.

Overriding Onyx Variables

Onyx's CSS lives inside two key files: onyx-variables.less and onyx-rules.less. Onyx's default theme is built from these two files and pulled in when you include $lib/onyx in your app's package.js file.

That being said, you can easily create and use a custom theme for Onyx as follows:

  1. Include "$lib/onyx/source" instead of "$lib/onyx" in your package.js. This will cause your app to load only the JavaScript source; the default CSS will be ignored.

  2. Create a Theme.less file in your application (we provide one in Bootplate by default).

  3. In Theme.less, import onyx-variables.less and onyx-rules.less. Then insert your custom variable definitions between the two @import statements:

     @import "../lib/onyx/css/onyx-variables.less";

 /* Place your Onyx variable overrides here. */

 @import "../lib/onyx/css/onyx-rules.less";

    The Onyx defaults will be overwritten with your chosen values.

Onyx Variables: A Quick Tour

The following is a high-level overview of the types of variables that you may define in your theme to control the look and feel of Onyx. Refer to onyx-variables.less for a complete list of the available variables and their default values.

  • Font: @onyx-font-family

  • Font-size:

    • High-level: @onyx-font-size-small, @onyx-font-size-medium, @onyx-font-size-large
    • Widget-level: @onyx-<widget-name>-font-size`

  • Text color:

    • High-level: @onyx-text-color
    • Widget-level: @onyx-<widget-name>-text-color

  • Background color:

    • High-level: @onyx-background-color
    • Widget-level: @onyx-<widget-name>-background-color

  • Border radius:

    • High-level: @onyx-border-radius, @onyx-border-radius-tight
    • Widget-level: @onyx-<widget-name>-border-radius

  • Padding

    • Widget-level: @onyx-<widget-name>-lr, @onyx-<widget-name>-tb

  • Icon Size: @onyx-icon-size

  • Disabled Opacity: @onyx-disabled-opacity

  • Gradient Overlays: @onyx-gradient and @onyx-gradient-invert

  • Images: @onyx-<widget-name>-image, @onyx-<widget-name>-image-width, @onyx-<widget-name>-image-height

To quickly illustrate how the variable syntax works, if you were to create a simple "My Little Pony"-inspired theme, your Theme.less might look like this:

@import "../lib/onyx/css/onyx-variables.less";

@onyx-text-color: pink;
@onyx-toolbar-text-color: pink;
@onyx-button-text-color: pink;

@onyx-background: pink;
@onyx-popup-background: pink;
@onyx-toolbar-input-background: pink;

@onyx-button-background: purple;
@onyx-groupbox-background: purple;
@onyx-progressbar-bar-background: purple;
@onyx-toolbar-background: purple;
@onyx-toolbar-button-background: purple;
@onyx-tooltip-background: purple;

@onyx-border-radius: 15px;
@onyx-border-radius-tight: 15px;

@import "../lib/onyx/css/onyx-rules.less";

Rule-Override Theming

When no variable exists for the piece of CSS you want to customize, your next option is to use a CSS rule override. Rule overrides go in the aforementioned Theme.less file, after the @import statement for onyx-rules.less:

@import "../lib/onyx/css/onyx-variables.less";
	
/* Place your Onyx variable overrides here */
	
@import "../lib/onyx/css/onyx-rules.less";
	
/* Place your Onyx rule overrides here */

Let's say you want to change the color of the glow that surrounds a focused input. Input.less doesn't break that value out into a variable, but we can look up the name of the relevant style in Input.less and write a custom rule to override the default color.

Global Overrides

To override a rule globally (so the override applies to all Onyx widgets), simply define the rule overriding the property (or properties) whose styling you wish to customize. In the case of the input glow color, that might look like the following:

@import "../lib/onyx/css/onyx-variables.less";

@import "../lib/onyx/css/onyx-rules.less";

/* Add a nice red glow to input decorators */
.onyx-input-decorator.onyx-focused {
    box-shadow: inset 0px 1px 4px rgba(255,0,0,0.3);
}

Selective Overrides

Of course, you may wish to be more selective about where your rule overrides are applied. In that case, simply define your rule override using a compound selector; that is, add an additional class to the definition, such as .red-glow below:

@import "../lib/onyx/css/onyx-variables.less";

@import "../lib/onyx/css/onyx-rules.less";

/* Add a nice red glow to input decorators */
.red-glow .onyx-input-decorator.onyx-focused {
    box-shadow: inset 0px 1px 4px rgba(255,0,0,0.3);
}

Now the rule override will only affect instances of onyx.InputDecorator that have the selecting class ("red-glow") applied, e.g.:

components: [
    {kind: "onyx.InputDecorator", classes: "red-glow", components: [
        {kind: "onyx.Input"}
    ]}
]

Alternatively, you may apply the selecting class to a parent component, which will cause all of its child input decorators to receive the override:

components: [
    // Standard Input
    {kind: "onyx.InputDecorator", components: [
        {kind: "onyx.Input"}
    ]},
    // Both input decorators will have "red-glow" applied
    {classes:"red-glow", components: [
        {kind: "onyx.InputDecorator", components: [
            {kind: "onyx.Input"}
        ]},
        {kind: "onyx.InputDecorator", components: [
            {kind: "onyx.Input"}
        ]}
    ]}
]

Library-Based Theming

Finally, there may be situations in which the look-and-feel changes you want to implement lie beyond the styling capabilities of CSS. This is often the case when DOM or behavioral changes are required.

For example, you might want to implement a "Slider" as a rotary dial instead of a horizontal track with a handle. Even if your new Slider has the exact same API as onyx.Slider (i.e., the same published properities and bubbled events), it will still require completely different DOM, CSS, and internal event tracking.

In this scenario, the idea of "theming" grows to encompass the building of a new library, made up of (one or more) Enyo kinds that implement your desired look-and-feel, while allowing you the freedom to implement custom DOM, CSS, and behavioral logic as needed.

In keeping with Enyo's emphasis on reusability, we encourage you to follow certain best practices when creating alternate UI libraries:

  • When possible, extend from Enyo's base UI library, found under enyo/source/ui. That folder contains an assortment of unstyled Enyo kinds that wrap common HTML form elements, such as:

    • Button
    • Checkbox
    • Image
    • Input
    • Popup
    • RichText
    • TextArea

  • When providing an alternate implementation of a higher-level UI component not supplied in the base UI (such as a Menu or Slider), consider extending from the equivalent Onyx kind (and thus starting from the same API for published properties, events, and functions) and overriding where necessary.

Clone this wiki locally