Docs Help

Terms, Icons, and Labels

Many classes have shortcut names used when creating (instantiating) a class with a configuration object. The shortcut name is referred to as an alias (or xtype if the class extends Ext.Component). The alias/xtype is listed next to the class name of applicable classes for quick reference.

Access Levels

Framework classes or their members may be specified as private or protected. Else, the class / member is public. Public, protected, and private are access descriptors used to convey how and when the class or class member should be used.

Member Types

Member Syntax

Below is an example class member that we can disect to show the syntax of a class member (the lookupComponent method as viewed from the Ext.button.Button class in this case).

lookupComponent ( item ) : Ext.Component
protected

Called when a raw config object is added to this container either during initialization of the items config, or when new items are added), or {@link #insert inserted.

This method converts the passed object into an instanced child component.

This may be overridden in subclasses when special processing needs to be applied to child creation.

Parameters

item :  Object

The config object being added.

Returns
Ext.Component

The component to be added.

Let's look at each part of the member row:

Member Flags

The API documentation uses a number of flags to further commnicate the class member's function and intent. The label may be represented by a text label, an abbreviation, or an icon.

Class Icons

- Indicates a framework class

- A singleton framework class. *See the singleton flag for more information

- A component-type framework class (any class within the Ext JS framework that extends Ext.Component)

- Indicates that the class, member, or guide is new in the currently viewed version

Member Icons

- Indicates a class member of type config

- Indicates a class member of type property

- Indicates a class member of type method

- Indicates a class member of type event

- Indicates a class member of type theme variable

- Indicates a class member of type theme mixin

- Indicates that the class, member, or guide is new in the currently viewed version

Class Member Quick-Nav Menu

Just below the class name on an API doc page is a row of buttons corresponding to the types of members owned by the current class. Each button shows a count of members by type (this count is updated as filters are applied). Clicking the button will navigate you to that member section. Hovering over the member-type button will reveal a popup menu of all members of that type for quick navigation.

Getter and Setter Methods

Getting and setter methods that correlate to a class config option will show up in the methods section as well as in the configs section of both the API doc and the member-type menus just beneath the config they work with. The getter and setter method documentation will be found in the config row for easy reference.

History Bar

Your page history is kept in localstorage and displayed (using the available real estate) just below the top title bar. By default, the only search results shown are the pages matching the product / version you're currently viewing. You can expand what is displayed by clicking on the button on the right-hand side of the history bar and choosing the "All" radio option. This will show all recent pages in the history bar for all products / versions.

Within the history config menu you will also see a listing of your recent page visits. The results are filtered by the "Current Product / Version" and "All" radio options. Clicking on the button will clear the history bar as well as the history kept in local storage.

If "All" is selected in the history config menu the checkbox option for "Show product details in the history bar" will be enabled. When checked, the product/version for each historic page will show alongside the page name in the history bar. Hovering the cursor over the page names in the history bar will also show the product/version as a tooltip.

Search and Filters

Both API docs and guides can be searched for using the search field at the top of the page.

On API doc pages there is also a filter input field that filters the member rows using the filter string. In addition to filtering by string you can filter the class members by access level, inheritance, and read only. This is done using the checkboxes at the top of the page.

The checkbox at the bottom of the API class navigation tree filters the class list to include or exclude private classes.

Clicking on an empty search field will show your last 10 searches for quick navigation.

API Doc Class Metadata

Each API doc page (with the exception of Javascript primitives pages) has a menu view of metadata relating to that class. This metadata view will have one or more of the following:

Expanding and Collapsing Examples and Class Members

Runnable examples (Fiddles) are expanded on a page by default. You can collapse and expand example code blocks individually using the arrow on the top-left of the code block. You can also toggle the collapse state of all examples using the toggle button on the top-right of the page. The toggle-all state will be remembered between page loads.

Class members are collapsed on a page by default. You can expand and collapse members using the arrow icon on the left of the member row or globally using the expand / collapse all toggle button top-right.

Desktop -vs- Mobile View

Viewing the docs on narrower screens or browsers will result in a view optimized for a smaller form factor. The primary differences between the desktop and "mobile" view are:

Viewing the Class Source

The class source can be viewed by clicking on the class name at the top of an API doc page. The source for class members can be viewed by clicking on the "view source" link on the right-hand side of the member row.

Ext JS 6.7.0 - Modern Toolkit


top
Guide applies to: modern

Ext JS Modern Toolkit Theming Guidelines

In this guide, we're going to walk through the changes to theming introduced with the modern toolkit in Ext JS 6.2. There are a lot of exciting new changes that provide for easier theming, dynamic updating, and much more! Along with these updates come some new concepts that you should be aware of.

Let's talk about the conventions and best practices for theming in the modern toolkit.

Dynamic Variables

All variables are defined using the dynamic() indicator. This ensures that the last variable declaration wins and remains valid throughout the entire scope. Additionally, variables may then derive from one another without concern for ordering.

For example:

$calendar-days-time-color: dynamic($color);

File Naming

All non-rule-generating code are placed in the theme's sass/var/ directory in a file matching the Component's class name. This is generally going to include all component variable and UI mixin declarations.

Since all var files are included in the build regardless of whether or not the corresponding class is actually required, 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 is located in the theme's sass/src/ directory in a file matching the Component's class name. This includes calls to UI mixins and rules not contained inside the body of a mixin.

At build time, src files are only included if the corresponding Component is required. This ensures that only the rules needed are included in the CSS output.

Base Styles vs. Configurable Styles

Layout-specific styles and styles related to the core functionality of a Component are placed in the theme-base/sass/src/ folder in a file matching the Component's class name. The properties set in these rules are not configurable using variables, as changing them would likely break the functionality or layout of the Component.

Examples of CSS properties that are generally not configurable are:

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

Configurable styles not related to the core functionality or layout of a component are controlled using variables. These variables are defined in an scss file matching the component's class name in the theme-neptune/sass/var directory. The rules that use these variables are 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 contains the theming capabilities supported by the framework even though it may not utilize them all itself.

Themes derived from theme-neptune do not typically define new UI mixins or create their own CSS rules. Instead, they simply set the values of variables defined in theme-neptune.

Variable Naming Conventions

Component variables 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 comes 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 are 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 the "state" refers to a sub-element's state, it comes 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 have separate variables for border-width, border-color, and border-style, and all three properties accept either a single value or a list of values so that 4 sides can be specified separately if needed:

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

Variables 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 provide variables that indicate a combination of states, for example:

$button-focused-pressed-border-color

Normal and Big Modes

Each theme has two 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'soverrides/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, otherwise, it uses normal mode.

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

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

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

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

.#{$prefix}button {
    padding: $padding;

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

Component UIs

Most components have a UI mixin for generating multiple visual renditions of that component. These mixins are named [xtype]-ui. For example button-ui or panel-ui.

UI mixins have a parameter for each of the component's global variables. Additionally, the parameter names are the same as the global variable names. The only exception is that the mixin parameters do 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 default to null and do not produce any output if unspecified by the caller. This means that when the mixin is invoked, it produces 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 is 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. For instance, 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.

To generate additional UIs, invoke the mixin 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 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

Subclasses of Components that have UI mixins typically have their own UI mixin and a complete set of global variables for configuring that mixin.

Subclass variables that do not have different default values from the superclass variables will be null. This ensures that they will inherit the proper values via the parent CSS class rather than redefining a redundant value.

Components use classCls set to x-[xtype] to accomplish this inheritance (See section below on CSS class names).

An example of this pattern is the grid pagingtoolbar component that 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

Additional UIs provided by a theme are typically not configurable via global variables or at least not overly configurable. 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 provide a single variable for each additional UI that defaults to "true" but can be overridden to "false" to disable generation of the UI. This variable will have the same name as the corresponding mixin:

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

Composable UIs

UIs are generally composable. For example if two 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'

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. Composable UIs 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. Any UI can be combined with the "round" UI to add roundness.

CSS Class Names

It is important to maintain consistency in naming CSS classes since 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 API, it provides a clear and understandable DOM structure for styling.

Main Element and UI CSS Classes

Components have a class name of x-[xtype] on its main element. For example, a Text Field component will 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, though 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. The classCls and baseCls configs 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, an Ext.field.Password component with a "ui" set to foo would have the following UI classes:

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

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 edge cases where inheriting styling is not desired Components may set classClsRoot:true to prevent inheritance of classCls from ancestors.

Reference Element CSS Classes

Reference elements follow the pattern x-[referencePrefix]-el. For example the bodyElement reference element of a form field will have the CSS class x-body-el. For consistency, element references will 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 follow the pattern x-[configName]-[configValue], and are placed on the Component's main element. For example a form field with a labelAlign: 'left' config has a CSS class name of x-label-align-left added to the main element.

CSS class names for boolean configs 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 an 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 falsey state. For example, the List component has an x-no-row-lines CSS class when rowLines is configured as false.

Likewise, class names that reflect Component state follow the pattern x-[state], and are 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. This is true even if the 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 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 are a varying number of dom elements in between the container element and it's child, UI-specific class names are added to the child element.

An example of this is Ext.Container. It adds a UI-specific class for each classCls to its innerElement because there can be a varying number of DOM ancestors in between the innerElement and the element depending on whether or not the container has docked items.

Ext JS 6.7.0 - Modern Toolkit