ExtReact Docs Help

Introduction

The documentation for the ExtReact product diverges somewhat from the documentation of other Sencha products. The sections below describe documentation for all products except where indicated as unique to ExtReact.

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.

ExtReact component classes list the configurable name prominently at the top of the API class doc followed by the fully-qualified class name.

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

Or in the case of an ExtReact component class this indicates a member of type prop

- 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.

ExtReact component classes do not hoist the getter / setter methods into the prop. All methods will be described in the Methods section

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.

ExtReact 6.7.0


top

Ext.Class

NPM Package

@sencha/ext-react

Hierarchy

Ext.Class

Summary

This is a low level factory that is used by Ext.define and should not be used directly in application code.

The configs of this class are intended to be used in Ext.define calls to describe the class you are declaring. For example:

Ext.define('App.util.Thing', {
    extend: 'App.util.Other',

    alias: 'util.thing',

    config: {
        foo: 42
    }
});

Ext.Class is the factory and not the superclass of everything. For the base class that all classes inherit from, see Ext.Base.

No members found using the current filters

configs

Optional Configs

alias : String / String[]

List of short aliases for class names. An alias consists of a namespace and a name concatenated by a period as <namespace>.<name>

  • namespace - The namespace describes what kind of alias this is and must be all lowercase.
  • name - The name of the alias which allows the lazy-instantiation via the alias. The name shouldn't contain any periods.

A list of namespaces and the usages are:

Most useful for defining xtypes for widgets:

Ext.define('MyApp.CoolPanel', {
    extend: 'Ext.panel.Panel',
    alias: ['widget.coolpanel'],
    title: 'Yeah!'
});

// Using Ext.create
Ext.create('widget.coolpanel');

// Using the shorthand for defining widgets by xtype
Ext.widget('panel', {
    items: [
        {xtype: 'coolpanel', html: 'Foo'},
        {xtype: 'coolpanel', html: 'Bar'}
    ]
});

alternateClassName : String / String[]

Defines alternate names for this class. For example:

Ext.define('Developer', {
    alternateClassName: ['Coder', 'Hacker'],
    code: function(msg) {
        alert('Typing... ' + msg);
    }
});

var joe = Ext.create('Developer');
joe.code('stackoverflow');

var rms = Ext.create('Hacker');
rms.code('hack hack');

cachedConfig : Object

This configuration works in a very similar manner to the config option. The difference is that the configurations are only ever processed when the first instance of that class is created. The processed value is then stored on the class prototype and will not be processed on subsequent instances of the class. Getters/setters will be generated in exactly the same way as config.

This option is useful for expensive objects that can be shared across class instances. The class itself ensures that the creation only occurs once.

config : Object

List of configuration options with their default values.

Note: You need to make sure Ext.Base#initConfig is called from your constructor if you are defining your own class or singleton, unless you are extending a Component. Otherwise the generated getter and setter methods will not be initialized.

Each config item will have its own setter and getter method automatically generated inside the class prototype during class creation time, if the class does not have those methods explicitly defined.

As an example, let's convert the name property of a Person class to be a config item, then add extra age and gender items.

Ext.define('My.sample.Person', {
    config: {
        name: 'Mr. Unknown',
        age: 0,
        gender: 'Male'
    },

    constructor: function(config) {
        this.initConfig(config);

        return this;
    }

    // ...
});

Within the class, this.name still has the default value of "Mr. Unknown". However, it's now publicly accessible without sacrificing encapsulation, via setter and getter methods.

var jacky = new Person({
    name: "Jacky",
    age: 35
});

alert(jacky.getAge());      // alerts 35
alert(jacky.getGender());   // alerts "Male"

jacky.walk(10);             // alerts "Jacky is walking 10 steps"

jacky.setName("Mr. Nguyen");
alert(jacky.getName());     // alerts "Mr. Nguyen"

jacky.walk(10);             // alerts "Mr. Nguyen is walking 10 steps"

Notice that we changed the class constructor to invoke this.initConfig() and pass in the provided config object. Two key things happened:

  • The provided config object when the class is instantiated is recursively merged with the default config object.
  • All corresponding setter methods are called with the merged values.

Beside storing the given values, throughout the frameworks, setters generally have two key responsibilities:

  • Filtering / validation / transformation of the given value before it's actually stored within the instance.
  • Notification (such as firing events) / post-processing after the value has been set, or changed from a previous value.

By standardize this common pattern, the default generated setters provide two extra template methods that you can put your own custom logics into, i.e: an "applyFoo" and "updateFoo" method for a "foo" config item, which are executed before and after the value is actually set, respectively. Back to the example class, let's validate that age must be a valid positive number, and fire an 'agechange' if the value is modified.

Ext.define('My.sample.Person', {
    config: {
        // ...
    },

    constructor: {
        // ...
    },

    applyAge: function(age) {
        if (typeof age !== 'number' || age < 0) {
            console.warn("Invalid age, must be a positive number");
            return;
        }

        return age;
    },

    updateAge: function(newAge, oldAge) {
        // age has changed from "oldAge" to "newAge"
        this.fireEvent('agechange', this, newAge, oldAge);
    }

    // ...
});

var jacky = new Person({
    name: "Jacky",
    age: 'invalid'
});

alert(jacky.getAge());      // alerts 0

alert(jacky.setAge(-100));  // alerts 0
alert(jacky.getAge());      // alerts 0

alert(jacky.setAge(35));    // alerts 0
alert(jacky.getAge());      // alerts 35

In other words, when leveraging the config feature, you mostly never need to define setter and getter methods explicitly. Instead, "apply" and "update" methods should be implemented where necessary. Your code will be consistent throughout and only contain the minimal logic that you actually care about.

When it comes to inheritance, the default config of the parent class is automatically, recursively merged with the child's default config. The same applies for mixins.

eventedConfig : Object

Config options defined within eventedConfig will auto-generate the setter / getter methods (see config for more information on auto-generated getter / setter methods). Additionally, when an eventedConfig is set it will also fire a before{cfg}change and {cfg}change event when the value of the eventedConfig is changed from its originally defined value.

Note: When creating a custom class you'll need to extend Ext.Evented

Example custom class:

Ext.define('MyApp.util.Test', {
    extend: 'Ext.Evented',

    eventedConfig: {
        foo: null
    }
});

In this example, the foo config will initially be null. Changing it via setFoo will fire the beforefoochange event. The call to the setter can be halted by returning false from a listener on the before event.

var test = Ext.create('MyApp.util.Test', {
    listeners: {
        beforefoochange: function (instance, newValue, oldValue) {
            return newValue !== 'bar';
        },
        foochange: function (instance, newValue, oldValue) {
           console.log('foo changed to:', newValue);
        }
    }
});

test.setFoo('bar');

The before event handler can be used to validate changes to foo. Returning false will prevent the setter from changing the value of the config. In the previous example the beforefoochange handler returns false so foo will not be updated and foochange will not be fired.

test.setFoo('baz');

Setting foo to 'baz' will not be prevented by the before handler. Foo will be set to the value: 'baz' and the foochange event will be fired.

extend : String

The parent class that this class extends. For example:

Ext.define('Person', {
    say: function(text) { alert(text); }
});

Ext.define('Developer', {
    extend: 'Person',
    say: function(text) { this.callParent(["print "+text]); }
});

inheritableStatics : Object

List of inheritable static methods for this class. Otherwise just like statics but subclasses inherit these methods.

mixins : String[] / Object

List of classes to mix into this class. For example:

Ext.define('CanSing', {
     sing: function() {
         alert("For he's a jolly good fellow...")
     }
});

Ext.define('Musician', {
     mixins: ['CanSing']
})

In this case the Musician class will get a sing method from CanSing mixin.

But what if the Musician already has a sing method? Or you want to mix in two classes, both of which define sing? In such a cases it's good to define mixins as an object, where you assign a name to each mixin:

Ext.define('Musician', {
     mixins: {
         canSing: 'CanSing'
     },

     sing: function() {
         // delegate singing operation to mixin
         this.mixins.canSing.sing.call(this);
     }
})

In this case the sing method of Musician will overwrite the mixed in sing method. But you can access the original mixed in method through special mixins property.

override : String

Overrides members of the specified target class.

NOTE: the overridden class must have been defined using Ext.define in order to use the override config.

Methods defined on the overriding class will not automatically call the methods of the same name in the ancestor class chain. To call the parent's method of the same name you must call callParent. To skip the method of the overridden class and call its parent you will instead call callSuper.

See Ext.define for additional usage examples.

privates : Object

The privates config is a list of methods intended to be used internally by the framework. Methods are placed in a privates block to prevent developers from accidentally overriding framework methods in custom classes.

Ext.define('Computer', {
    privates: {
        runFactory: function(brand) {
            // internal only processing of brand passed to factory
            this.factory(brand);
        }
    },

    factory: function (brand) {}
});

In order to override a method from a privates block, the overridden method must also be placed in a privates block within the override class.

Ext.define('Override.Computer', {
    override: 'Computer',
    privates: {
        runFactory: function() {
            // overriding logic
        }
    }
});

requires : String[]

List of classes that have to be loaded before instantiating this class. For example:

Ext.define('Mother', {
    requires: ['Child'],
    giveBirth: function() {
        // we can be sure that child class is available.
        return new Child();
    }
});

singleton : Boolean

When set to true, the class will be instantiated as singleton. For example:

Ext.define('Logger', {
    singleton: true,
    log: function(msg) {
        console.log(msg);
    }
});

Logger.log('Hello');

statics : Object

List of static methods for this class. For example:

Ext.define('Computer', {
     statics: {
         factory: function(brand) {
             // 'this' in static methods refer to the class itself
             return new this(brand);
         }
     },

     constructor: function() { ... }
});

var dellComputer = Computer.factory('Dell');

uses : String[]

List of optional classes to load together with this class. These aren't neccessarily loaded before this class is created, but are guaranteed to be available before Ext.onReady listeners are invoked. For example:

Ext.define('Mother', {
    uses: ['Child'],
    giveBirth: function() {
        // This code might, or might not work:
        // return new Child();

        // Instead use Ext.create() to load the class at the spot if not loaded already:
        return Ext.create('Child');
    }
});

xtype : String

The xtype configuration option can be used to optimize Component creation and rendering. It serves as a shortcut to the full component name. For example, the component Ext.button.Button has an xtype of button.

You can define your own xtype on a custom Ext.Component by specifying the alias config option with a prefix of widget. For example:

Ext.define('PressMeButton', {
    extend: 'Ext.button.Button',
    alias: 'widget.pressmebutton',
    text: 'Press Me'
});

Any Component can be created implicitly as an object config with an xtype specified, allowing it to be declared and passed into the rendering pipeline without actually being instantiated as an object. Not only is rendering deferred, but the actual creation of the object itself is also deferred, saving memory and resources until they are actually needed. In complex, nested layouts containing many Components, this can make a noticeable improvement in performance.

Defaults to:

"component"

properties

methods

ExtReact 6.7.0