@sencha/ext-modern-theme-base

#Ext JS Modern Toolkit Theming Guidelines

Dynamic Variables

All variables should be defined using the dynamic() function. This ensures that the last variable declaration wins, and is valid throughout the entire scope, allowing variables to derive from one another without concern for ordering.

File Naming

All Component variable and UI mixin declarations (all non-rule-generating code) should be placed in the theme's sass/var/ directory in a file matching the Component's class path. Since all var files are included in the build regardless of whether or not the corresponding class is actually required by the app, this allows variables to freely derive from any other variable. Including mixins in the sass/var/ directory ensures that a derived theme can override those mixins before they are called by any code in the sass/src/ directory.

All rule-generating code, including calls to UI mixins, and rules not contained inside the body of a mixin should be placed in the theme's sass/src/ directory in a file matching the Component's class path. At build time, src files are only included if the corresponding Component is required by the app, thus ensuring that only the rules that the app actually needs are included in the CSS output.

Base Styles vs. Configurable Styles

Layout-specific styles, and styles related to core functionality of a Component should always be placed in theme-base/sass/src/ in a file matching the Component's class path. The properties set in these rules should NOT be configurable using variables, as changing them would likely break the functionality or layout of the Component. Some examples of CSS properties that should generally not be configurable are:

• display
• visibility
• position
• overflow
• z-index

Configurable styles not related to the core functionality or layout of a component should always be controlled using variables. These variables should be defined in a scss file matching the component's class path in the theme-neptune/sass/var directory, and the rules that use these variables should be contained in a UI mixin in the same file. Examples of commonly configurable styles are:

• background-color
• color
• padding
• border-radius
• font-size

The neptune theme is the base for all other themes and should contain the universe of possible theming capabilities supported by the framework although it may not utilize them all itself. Themes derived from theme-neptune should avoid defining new UI mixins and creating their own CSS rules, but should instead simply set the values of variables defined in theme-neptune. When a new feature is needed by a derived theme it should be added to theme-neptune with variables to tune its behavior rather than adding the new feature only to the derived theme.

##Variable Naming Conventions

Component variables should always begin with an xtype, and end with the CSS property name being styled, for example:

$button-font-family: dynamic(helvetica);
$button-color: dynamic(#fff);
$button-background-color: dynamic(red);

If the component has various states such as hovered, focused, and pressed, the name of the state should come immediately after the xtype, but before the CSS property name:

$button-hovered-background-color: dynamic(blue);

If the component has variables that control the styling of sub-elements, the name of the sub-element being styled should be included after the xtype, and state if present. For example, when styling the button's "badge" element:

$button-badge-color: dynamic(#fff);
$button-hovered-badge-color: dynamic(green);

If however, the "state" refers to a sub-element's state, it should come after that element's name. For example, if a tab has a close icon that has a separate hover state from the tab:

$tab-close-icon-hovered-background-color: dynamic(red);

Components should have separate variables for border-width, border-color, and border-style, and all three properties should accept either a single value or a list of values so that 4 sides can be specified separately if needed:

// BAD
$button-border: dynamic(1px solid green);

// GOOD
$button-border-color: dynamic(red yellow green blue);
$button-border-width: dynamic(1px 3px);
$button-border-style: dynamic(solid);

Variables should use the following names to indicate component state:

• "pressed" when the component is being pressed by the user or is in a pressed state
• "pressing" if the component has a "pressing" state that is separate from "pressed"
• "hovered" when the mouse pointer is over the element
• "focused" when the element has focus
• "disabled" when the component is disabled.

Since "focused" can sometimes be combined with other states components may need to provide variables that indicate a combination of states, for exmaple $button-focused-pressed-border-color

Normal and Big Modes

Each theme has 2 modes of sizing - normal and big. Big mode increases spacing and sizing to be more touch-screen friendly. Themes select whether or not to use big mode by inspecting Ext.platformTags in the theme's overrides/init.js and adding a CSS class name of x-big to the <html> element on the page. For example, the triton theme only enables big mode when loaded on a phone and uses normal mode otherwise:

Ext.theme.getDocCls = function() {
    return Ext.platformTags.phone ? 'x-big' : '';
};

All variables that set properties affecting visual size of a component, like font-size, line-height, and padding should have big counterparts. Big variables always have the -big suffix appended to the end:

$button-padding: dynamic(1rem);
$button-padding-big: dynamic(1.2rem);

SASS rules target big mode using the .x-big selector:

.#{$prefix}button {
    padding: $padding;
    
    .#{$prefix}big & {
        padding: $padding-big;
    }
}

##Component UIs

Every component should have a UI mixin for generating multiple visual renditions of that component. The mixin should be named [xtype]-ui. For example button-ui or panel-ui.

UI mixins should have a parameter for each of the component's global variables, and the parameter names should be the same as the global variable names with the exception that the mixin parameters should not contain the xtype in their names. For example, a global variable named $button-border-radius, would correspond to a parameter of the button-ui mixin named $border-radius.

The parameters to the UI mixin should all default to null, and should not produce any output if unspecified by the caller. This means that when the mixin is invoked it should produce a set of styling that represents a delta from the default UI. This minimizes the number of css rules required to create new UIs since the mixin automatically eliminates any null values from the output.

The styling for the default UI should be applied using CSS class names that do not contain a UI name, for example x-button, not x-button-default. This is the key to minimizing the number of rules required to create additional UIs, since all buttons will have the x-button class in addition to one or more optional x-button-[ui] classes. It allows the default UI to serve as a base set of styles for all other UIs.

A typical UI mixin should look something like this:

@mixin button-ui(
    $ui: null
    // $xtype is the only variable that does not default to null
    // since it is only used in selector names and does not affect
    // the output unless other non-null values are passed.  It is
    // typically only passed by mixins of subclasses (see section on
    // "Derived UIs" below)
    $xtype: button,
    $background-color: null,
    $border-radius: null
) {
    // returns '' if $ui is null, otherwise prefixes $ui with "-"
    // To generate default UI we will not pass the $ui parameter
    $ui-suffix: ui-suffix($ui);
    
    .#{$prefix}#{$xtype}#{$ui-suffix} {
        // Fashion compiler removes null values from output
        // If all values are null, the entire rule is eliminated.
        // This means there is usually no need to check == null
        background-color: $background-color;
        border-radius: $border-radius;
    }
}

Since all UI mixin parameters default to null, the default UI invocation must explicitly pass all the global variables for the component. This generates the set of base styling rules for the component that all other UIs build upon. Note that this invocation does not pass $ui so that the base styles are applied to the base x-button class, not a UI-specific one:

@include button-ui(
    $background-color: $button-background-color,
    $border-radius: $button-border-radius
);

To generate additional UIs, invoke the mixin again, passing only the parameters that are different from the default UI. For example, the following mixin call generates a UI named "action" that builds upon the default UI by changing the background-color to red, but inherits all other properties from the default UI via the cascade. The output from this UI invocation is very minimal - it only contains the rule or rules needed to set the background-color, nothing else.

@include button-ui(
    $ui: 'action',
    $background-color: red
);

Derived UIs

Every subclass of a Component that has a UI mixin should also have its own UI mixin, along with a complete set of global variables for configuring that mixin. The sublcass mixin should inoke the superclass mixin passing its own xtype as the $xtype parameter before adding any rules of its own. Any subclass variables that are not intended to have different default values from the superclass variables should default to null. This ensures that they will inherit the proper values via the parent CSS class rather than redefining a redundant value. NOTE: you must define a classCls equal to x-[xtype] on both Components in order for this pattern to work (See section below on CSS class names). An example of this pattern is the grid pagingtoolbar component which extends toolbar:

// theme-neptune/sass/var/grid/plugin/PagingToolbar.scss
$pagingtoolbar-background-color: dynamic(null);

@mixin pagingtoolbar-ui(
    $ui: null,
    $xtype: pagingtoolbar,
    $background-color: null,
    $prev-icon: null
) {
    $ui-suffix: ui-suffix($ui);
    
    // Call base toolbar mixin.
    // Only produces output for non-null parameters
    @include toolbar-ui(
        $ui: $ui,
        $xtype: $xtype,
        $background-color: $background-color
    );
    
    // paging toolbar specific styles
    .#{$prefix}#{$xtype}#{$ui-suffix} {
        .#{$prefix}icon-prev {
            @include icon($prev-icon);
        }
    }
}

// theme-neptune/sass/src/grid/plugin/PagingToolbar.scss
@include pagingtoolbar-ui(
    $background-color: $pagingtoolbar-background-color;
);

##Configuring Theme UIs in Derived Themes

In the classic toolkit additional UIs provided with a theme typically were accompanied by a complete set of global variables for configuring that UI in derived themes. This resulted in massive amounts of duplication (variable count = total component vars * number of UIs). The modern toolkit takes a simpler approach - additional UIs provided by a theme are not configurable via global variables. Instead, these UIs are wrapped in a mixin of their own, which can be overridden by derived themes to change the parameters:

@mixin button-action-ui() {
    @include button-ui(
        $ui: 'action',
        $background-color: red
    );
}

Themes should provide a single variable for each additional UI that defaults to "true" but can be overridden to "false" in derived themes to completely disable generation of the UI. This variable should have the same name as the corresponding mixin:

@if $button-action-ui {
    @include button-action-ui;
}

##Composable UIs

UIs should be composable where possible. For example if 2 separate button renditions are required, a red "action" button, and a rounded red "action" button, simply create an "action" UI and "round" UI:

// sass/var
$button-action-ui: dynamic($enable-default-uis);
$button-confirm-ui: dynamic($enable-default-uis);

@mixin button-action-ui() {
    @include button-ui(
        $ui: 'action',
        $background-color: red
    );
}

@mixin button-round-ui() {
    @include button-ui(
        $ui: 'round',
        $border-radius: 10000px
    );
}

// sass/src
@if $button-action-ui {
    @include button-action-ui
}

@if $button-round-ui {
    @include button-round-ui
}

To compose UIs simply use any number of UI names, space separated, in your component config:

ui: 'action round'

Note, that if multiple UIs set the same properties, the winner is the last one in the cascade, i.e. the one whose mixin was invoked last. To avoid confusion, composable UIs should typically strive to limit their area of concern to separate aspects of styling (colors, sizing, border-radius, etc), so that there is little ambiguity when combining them.

Using composable UIs ensures that the generated CSS code remains very DRY, by avoiding unnecessary duplication of CSS rules. In the example above, we avoid duplication of the background-color rules for every UI that may optionally need roundness, since any UI can be combined with the "round" UI to add roundness.

##Size Optimizing Mixins

Some css properties (like border-width, border-color, and border-style) can sometimes be collapsed in to a single property (border). Themes should use mixins that intelligently collapse these properties if possible to optimize CSS file size.

Pass border variables to the border mixin to collapse them into a single border declaration if possible. If any values are null or if any values are a list then it will output separate border-width, border-color, and border-style properties, otherwise it will output a single border property.

.x-foo {
    @include border($border-width, $border-style, $border-color);
}

Likewise the font mixin should always be used for generating a font declaration from variables, since it also collapses properties into a single font property if possible

.x-foo {
    @include font($font-weight, $font-size, $line-height, $font-family);
}

Margin and padding should always be included using the margin and padding mixins. This allows themes to specify margin and padding variables as a list that may include null values. A null value means "do not set the value", and in many cases is preferred over 0. For example:

// sass
$foo-padding: dynamic(1em, null);

.x-foo {
    @include padding($foo-padding);
}

// css output:
.x-foo {
    padding-top: 1em;
    padding-bottom: 1em;
}

CSS Class Names

It is important to maintain consistency in naming of CSS classes since they they play a major role in adding semantics and structure to the DOM elements that are generated by Components in the framework. This consistency of naming serves two purposes:

1. It improves the readability and maintainability of SASS code, and reduces the chance for error.
2. For users who do not use the SASS API, it provides a clear and understandable dom structure for styling.

Main Element and UI CSS Classes

Each Component should have a class name of x-[xtype] on its main element. For example, a Text Field component should have a CSS class name of x-textfield. There are two possible ways for Components to set this main CSS class. They can either set classCls or baseCls on the body of their class definition (classCls is preferred). Setting either of these will add the CSS class to the main element and use it as the prefix for UI-specific class names that are also added to the main element. classCls and baseCls only differ in their inheritability. classCls is inherited by subclasses and is additional to the classCls of those subclasses, whereas baseCls is not. Additionally, when using classCls a UI-specific CSS class name will be added for each and every classCls in the class hierarchy. For example, a Ext.field.Password component with a ui of foo would have the following UI classes:

• x-passwordfield-foo
• x-textfield-foo
• x-field-foo

Using this pattern ensures that styling is correctly inherited through the class hierarchy and allows Components to only provide styling for the functionality that they add. For odd edge cases where inheriting styling is not desired Components may set classClsRoot:true to prevent inheritance of classCls from ancestors, but this should usually be avoided.

Reference Element CSS Classes

Reference elements should follow the pattern x-[referencePrefix]-el. For example the bodyElement reference element of a form field should have the CSS class x-body-el (for consistency element references should always have the Element suffix on the JavaScript side). The -el suffix on the CSS class name helps to differentiate the reference element from a potential Component with an xtype of the same name.

CSS Classes for Component Configuration and State

CSS class names that reflect Component configuration should follow the pattern x-[configName]-[configValue], and should always be placed on the Component's main element. For example a form field with a labelAlign: 'left' config would result in a CSS class name of x-label-align-left being added to the main element.

CSS class names for boolean configs should generally follow one of two patterns

1. Truthiness causes a new class to be added - for example a checkbox with a checked config would have a x-checked CSS class when the value is true, but would not have the class when false.

2. Falsiness causes a new class to be added. This is sometimes useful when the default value is true, and the component needs needs additional styling only in the falsy state. For example, the List component has a x-no-row-lines CSS class when rowLines is configured as false.

Likewise class names that reflect Component state should follow the pattern x-[state], and should always be placed on the Component's main element . For example, a button that is in pressed state would have the class x-pressed on its main element.

Setting Component state and configuration CSS classes on the main element, rather than on a reference element allows the state or configuration to be scoped to the Component, even if these classes only affect the styling of a child element or elements. This also results in a more stable dom structure as these class names do not change location even if the internal dom structure is modified.

CSS Selectors

Since reference, config, and state CSS classes do not contain xtype info in their name, they must be used in combination with the Component's classCls or baseCls to avoid colliding with other Components that may have the same config or state class name. For example to style the pressed state of a button's main element, one would use the following selector:

.x-button.x-pressed

UI mixins should use UI-specific CSS class names in combination with reference, config, and state CSS classes. For example if the ui of a button is 'foo', one would style the pressed state as follows:

.x-button-foo.x-pressed

Child vs Descendant Selectors

When styling a component's inner elements descendant selectors such as .x-foo .x-bar should be preferred over direct child selectors like .x-foo > .x-bar. This allows for much more flexibility in the markup and allows it to tolerate more change, such as the insertion of a wrapping element in between x-foo and x-bar without potentially breaking the styling. The only exception to this rule is when there is the potential for nesting. For example, a panel might use a selector such as .x-panel > .x-body-el in order to only style its own body element, and not the body elements of other panels nested within it. In some cases when there may be a varying number of dom elements in between the container element and it's child it may be necessary to add UI-specific class names to the child element, but this should be treated as the exception, not the rule. An example of this is Ext.Container. It adds a UI-specific class for each classCls to its bodyElement because there can be a varying number of DOM ancestors in between the bodyElement and the element depending on whether or not the container has docked items.