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.
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.
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.
Public classes and class members are available for use by any other class or application code and may be relied upon as a stable and persistent within major product versions. Public classes and members may safely be extended via a subclass.
Protected class members are stable public members intended to be used by the
owning class or its subclasses. Protected members may safely be extended via a subclass.
Private classes and class members are used internally by the framework and are not intended to be used by application developers. Private classes and members may change or be omitted from the framework at any time without notice and should not be relied upon in application logic.
ExtReact component classes display
configuration options as props
ExtReact component classes do not list
properties as a dedicated member type, but rather as
read only props
static label next to the
method name. *See Static below.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).
Let's look at each part of the member row:
lookupComponent in this example)( item ) in this example)Ext.Component in this case). This may be omitted for methods that do not
return anything other than undefined or may display as multiple possible values
separated by a forward slash / signifying that what is returned may depend on the
results of the method call (i.e. a method may return a Component if a get method calls is
successful or false if unsuccessful which would be displayed as
Ext.Component/Boolean).PROTECTED in
this example - see the Flags section below)Ext.container.Container in this example). The source
class will be displayed as a blue link if the member originates from the current class
and gray if it is inherited from an ancestor or mixed-in class.view source in the example)item : Object in the example).undefined a "Returns" section
will note the type of class or object returned and a description (Ext.Component in the
example)Available since 3.4.0 - not pictured in
the example) just after the member descriptionDefaults to: false)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.
All ExtReact props are bindable
unless decorated as immutable
Immutable ExtReact props may not be use as a configurable prop when instantiating a component
classInstance.method1().method2().etc();false is returned from
an event handler- 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
- 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
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.
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
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.
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.
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:
Ext.button.Button class has an alternate class name of Ext.Button). Alternate class
names are commonly maintained for backward compatibility.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.
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:
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.
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.
List of short aliases for class names. An alias consists of a namespace and a name concatenated by a period as <namespace>.<name>
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'}
]
});
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');
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.
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 My.sample.Person({
name: "Jacky",
age: 35
});
alert(jacky.getAge()); // alerts 35
alert(jacky.getGender()); // alerts "Male"
jacky.setName("Mr. Nguyen");
alert(jacky.getName()); // alerts "Mr. Nguyen"
Notice that we changed the class constructor to invoke this.initConfig() and pass in the provided config object. Two key things happened:
Beside storing the given values, throughout the frameworks, setters generally have two key responsibilities:
By standardize this common pattern, the default generated setters provide two extra template methods that you can put your own custom logic 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 My.sample.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.
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.
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]); }
});
List of inheritable static methods for this class. Otherwise just like statics but subclasses inherit these methods.
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.
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.
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
}
}
});
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();
}
});
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');
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');
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');
}
});
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 <ExtComponent/> like so:
Ext.define('PressMeButton', {
extend: 'Ext.button.Button',
xtype: '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.
// Explicit creation of contained Components:
var panel = new Ext.Panel({
// ...
items: [
Ext.create('Ext.button.Button', {
text: 'OK'
})
]
});
// Implicit creation using xtype:
var panel = new Ext.Panel({
// ...
items: [{
xtype: 'button',
text: 'OK'
}]
});
In the first example, the button will always be created immediately during the panel's initialization. With many added Components, this approach could potentially slow the rendering of the page. In the second example, the button will not be created or rendered until the panel is actually displayed in the browser. If the panel is never displayed (for example, if it is a tab that remains hidden) then the button will never be created and will never consume any resources whatsoever.
Create a new anonymous class.
Class : Object
data : Object
An object represent the properties of this class
onCreated : Function
Optional, the callback function to be executed when this class is fully created. Note that the creation process can be asynchronous depending on the pre-processors used.
The newly created class
Retrieve the array stack of default pre-processors
defaultPreprocessors
Retrieve a pre-processor callback function by its name, which has been registered before
name : String
preprocessor
Register a new pre-processor to be used during the class creation process
name : String
The pre-processor's name
fn : Function
The callback function to be executed. Typical format:
function(cls, data, fn) {
// Your code here
// Execute this when the processing is finished.
// Asynchronous processing is perfectly ok
if (fn) {
fn.call(this, cls, data);
}
});
properties : Object
position : Object
relativeTo : Object
this
Insert this pre-processor at a specific position in the stack, optionally relative to any existing pre-processor. For example:
Ext.Class.registerPreprocessor('debug', function(cls, data, fn) {
// Your code here
if (fn) {
fn.call(this, cls, data);
}
}).setDefaultPreprocessorPosition('debug', 'last');
name : String
The pre-processor name. Note that it needs to be registered with registerPreprocessor before this
offset : String
The insertion position. Four possible values are: 'first', 'last', or: 'before', 'after' (relative to the name provided in the third argument)
relativeName : String
this
Set the default array stack of default pre-processors
preprocessors : Array
this
ExtAngular | Terms of Use