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.

Cmd 6.6.0


top

Fashion

Introduction

With Sencha Cmd 6.0, we are excited to introduce a new and rapid tool for developing themes for Ext JS 6.0 called "Fashion". Combining Fashion and sencha app watch creates a new mode for theme development we call "Live Update".

Live Update uses Fashion to compile and then inject up-to-date CSS into your running page. This means you don't have to reload to see theme changes and you instead see these updates in near real-time directly in the browser.

Sencha Cmd 6 also uses Fashion when compiling themes for Ext JS 6 applications. Since Fashion is implemented in JavaScript, Ruby is no longer required.

What is Fashion?

Fashion is a compiler for .scss files used to generate CSS. Fashion also adds some new features not available in Sass that allow tools like Sencha Inspector to visually inspect and edit the variables defined by the theme (or your application).

JavaScript Extensions

Users can extend Fashion's functionality by writing JavaScript modules. Generally speaking, Ext JS users are probably most familiar with JavaScript, so extending behavior should be much simpler than extending Compass. We'll talk more about extending Fashion below.

Now that the introductions are out of the way, let's talk about Fashion!

Compatibility

Fashion is compatible with CSS3 syntax as well as the majority of the sass-spec validation suite. Because Fashion does understand the majority of Sass code, getting existing .scss code to compile using Fashion should not be difficult.

Due to the additional features discussed later, however, it is not correct to say that Fashion "is an implementation of Sass" or that the language Fashion compiles "is Sass". There are many places where the word "sass" is used as a name for configuration options or folders on disk. For compatibility reasons, these config options are still named "sass" even though the language underneath is not strictly "Sass".

Using Live Updates

You can open an application in a (modern) browser and the Sass files will be loaded instead of the generated CSS. Fashion can then react to file changes and recompile the Sass and update the CSS without reloading the page.

There are two ways to enable Fashion for use in sencha app watch.

You may enable Fashion by editing the "development" object found in app.json:

...
"development": {
    "tags": [
        "fashion"
    ]
},
...

Alternatively, you can add "?platformTags=fashion:1" to your URL as you load the page.

Now we are ready to launch:

  • Execute "sencha app watch" from your application's root folder.
  • Navigate the browser to your application (for example, http://localhost:1841/app).

You should now be able to modify your theme variables and see changes almost instantly.

Note: Live Update will only work when viewing the page from the Cmd web server. In Ext JS classic toolkit, some Sass changes may require a layout or a full page reload. This will be less of an issue in the modern toolkit since it is more heavily based on CSS3 and will reflow to accommodate more aggressive changes.

Language Extensions

Dynamic Variables

Dynamic variables play a very important part in Fashion. Dynamic variables are similar to normal variables, but their value is wrapped in "dynamic()". What makes dynamic variables different from normal variables is how they interact with each other. Consider

$bar: dynamic(blue);

$foo: dynamic($bar);  // Notice $foo depends on $bar

$bar: dynamic(red);

@debug $foo;  // red

Notice that $foo is calculated from $bar. This dependency is treated specially by Fashion and the computation of $foo is deferred until the final value of $bar is known.

In other words, dynamic variables are processed in two passes: assignment and evaluation.

Assignment

Dynamic variables, like normal variables, are assigned in normal "cascade" order (unlike !default):

$bar: dynamic(blue);

$bar: dynamic(red);

@debug $bar;  // red

This allows tooling to append custom values to any block of code and take control of its dynamic variables.

Assignment to dynamic variables can only occur at file scope and outside any control structure. For example, this is illegal:

$bar: dynamic(blue);

@if something {
    $bar: dynamic(red); // ILLEGAL
}

Instead of the above, this form should be used:

$bar: dynamic(if(something, red, blue));

This requirement is necessary to enable the evaluation and hoisting behaviors discussed below.

Dynamic variables can be assigned after their declaration with or without using the dynamic() wrapper.

$bar: dynamic(blue);

$bar: red;  // reassigns $bar to red

$bar: green !default;  // reassigns $bar to green

@debug $bar;  // green

There is no such thing as "default dynamic".

Evaluation

Dynamic variables are evaluated in dependency order, not declaration order. Declaration order only applies to the cascade of individual variable assignment. This can be seen in the above example. This ordering also means we could even remove the first setting of $bar and the code would have the same result.

Consider the more elaborate example:

$bar: dynamic(mix($colorA, $colorB, 20%));

$bar: dynamic(lighten($colorC, 20%));

The original expression for $bar used $colorA and $colorB. Had that been the only assignment to $bar, then $bar would have depended on these two variables and been evaluated after them. Since $bar was reassigned and subsequently only used $colorC, in the final analysis, $bar depends only on $colorC. The original assignment to $bar might as well never have occurred.

Hoisting

To accomplish all of this, Fashion gathers all dynamic variables and evaluates them prior to any other execution of the Sass code. In other words, similar to JavaScript variables, dynamic variables are "hoisted" to the top.

Elevation

When variables are used to assign dynamic variables, these variables are elevated to dynamic.

$foo: blue;

$bar: dynamic($foo);

Even though $foo was declared as a normal variable, because $bar uses $foo, Fashion will elevate $foo to be dynamic.

NOTE: This implies that $foo must now follow the rules for dynamic variables.

This behavior is supported to maximize portability from previous versions of Sencha Cmd. When variables are elevated, a warning will be generated. In future releases, this warning will become an error. We recommend correcting this code to properly declare required variables as dynamic().

Extensions - Requiring JavaScript

You can extend Fashion by writing code in JavaScript. To require this code from the Sass code that needs it, use require(). For example:

require("my-module");

// or

require("../path/file.js"); // relative to scss file

Internally, Fashion uses the ECMAScript 6 (ES6) System.import API (or its polyfill via SystemJS) to support loading standard JavaScript modules.

A module can be written in pre-ES6 syntax like so:

exports.init = function(runtime) {
    runtime.register({
        magic: function (first, second) {
            // ...
        }
    });
};

Using SystemJS, you can enable "transpilers" to write ES6 code in any browser. The above would look like this in ES6:

module foo {
    export function init (runtime) {
        runtime.register({
            magic: function (first, second) {
                // ...
            }
        });
    }
}

Upgrading

Dynamic Variables

When upgrading to Ext JS 6, the internal use of dynamic variables could impact how these variables are assigned in applications and custom themes. Although not necessary, we recommended you change variable assignments to use dynamic(). In most cases this will be mechanically replacing !default (the approach taken in previous releases) with dynamic():

// before:

$base-color: green !default;

// after:

$base-color: dynamic(green);

This will make it more obvious if an error is generated based on the more restrictive nature of assignment to dynamic variables.

Compass Extensions

Compass functionality depending on Ruby code will be unavailable since Ruby is no longer being utilized. An equivalent will have to be created using JavaScript. This can be provided in many cases using require() to implement the missing functionality in JavaScript. The Sass code from Compass, however, is included in Fashion, so not all Compass functionality is impacted. Generally speaking, if you have not used any custom or Ruby based Compass functionality, you will most likely not need to make any changes.

Conclusion

We are very excited about Fashion we hope you are too! Quickly theming your application has never been easier, and extending Sass can now be done in the same language as the framework. Please be sure to leave us any feedback on the forums.

Cmd 6.6.0