Ext JS 4 Web Application Development Cookbook

The Ext.define method is used to define new classes. It uses a string-based definition, leaving the framework to take care of the namespacing and concrete defining of the class:

At this point our class is fully created, and all that is left to do is to execute the callback function (defined as the third parameter to Ext.define) to signal the class definition being complete. The full process can be seen in the following diagram:

This model is extremely flexible and allows you to include your own pre or post processor at any stage in the sequence by using the registerPreProcessor and registerPostProcessor methods.

All Ext JS 4 classes inherit from a common base class, named Ext.Base. This class contains several methods that provide basic functionality to all created subclasses, for example override and callParent. When we define a new class using the Ext.define method, and don't specify an explicit base class, then the framework will automatically use Ext.Base as its base inside the Extend preprocessor. If we do specify a base class then that class will, at the root of its inheritance tree, extend Ext.Base. The following diagram shows how our custom class fits into this structure:

The new Ext JS class system also takes care of a lot of the heavy lifting for you when it comes to defining your properties, configuration options, and their associated getter and setter methods.

If you define these configuration options within a config object, the class system (inside its Config pre-processor) will automatically generate get, set, reset, and apply methods. This reduces the amount of code that needs to be maintained and downloaded.

The following code sample utilizes this config option and takes advantage of the free code that the framework will create. This code is initialized by calling the initConfig method within the constructor, which is executed when your class is instantiated.

Ext.define('Cookbook.Vehicle', {
    config: {
        Manufacturer: 'Aston Martin',
        Model: 'Vanquish'
    },

    constructor: function(config){
        // initialise our config object
        this.initConfig(config);
    },

    getDetails: function(){
        alert('I am an ' + this.Manufacturer + ' ' + this.Model);
    }
});

// create a new instance of Vehicle class
var vehicle = Ext.create('Cookbook.Vehicle');

// display its details
vehicle.getDetails();

// update Vehicle details
vehicle.setManufacturer('Volkswagen');
vehicle.setModel('Golf');

// display its new details
vehicle.getDetails();

By using this approach it is the equivalent of defining your class with the explicit methods shown as follows:

Ext.define('Cookbook.Vehicle', {
    Manufacturer: 'Aston Martin',
    Model: 'Vanquish',

    getManufacturer: function(){
        return this.Manufacturer;
    },
    setManufacturer: function(value){
        this.Manufacturer = value;
    },
    resetManufacturer: function(){
        this.setManufacturer('Aston Martin');
    },
    applyManufacturer: function(manufacturer){
        // perform some action to apply the value (e.g. update a DOM element)
        return manufacturer;
    },

    getModel: function(){
        return this.Model;
    },
    setModel: function(value){
        this.Model = value;
    },
    resetModel: function(){
        this.setModel('Vanquish');
    },
    applyModel: function(model){
        // perform some action to apply the value (e.g. update a DOM element)
        return model;
    },

    getDetails: function(){
        alert('I am an ' + this.Manufacturer + ' ' + this.Model);
    }
});

Sometimes we will want to perform some extra actions when calling these generated methods. We can do this by explicitly defining our own version of the method that will override the generated one. In our example, when calling the apply method, we want to update a DOM element that contains the Vehicle's name, so the change is reflected on the screen. First we add some markup to hold our Vehicle's data:

<span id="manufacturer"></span>
<span id="model"></span>

Now we override the applyManufacturer and applyModel methods to perform an update of each DOM element when the properties are changed:

Ext.define('Cookbook.Vehicle', {
    config: {
        Manufacturer: 'Aston Martin',
        Model: 'Vanquish'
    },

    constructor: function(config){
        // initialise our config object
        this.initConfig(config);
    },

    getDetails: function(){
        alert('I am an ' + this.getManufacturer() + ' ' + this.getModel());
    },

    applyManufacturer: function(manufacturer){
        Ext.get('manufacturer').update(manufacturer);
        return manufacturer;
    },
    applyModel: function(model){
        Ext.get('model').update(model);
        return model;
    }
});
// create a Vehicle and set its Manufacturer and Model
var vehicle = Ext.create('Cookbook.Vehicle');
vehicle.setManufacturer('Volkswagen');
vehicle.setModel('Golf');

Alerts The Boeing 747 travelled 800 miles at 500mph (inherited from the Vehicle class)

alert('Max Altitude: ' + plane.getMaxAltitude() + ' feet');

Alerts 'MaxAltitude: 30000 feet' (defined in the Plane class)

The extend configuration option, used when defining your new subclass, tells the Ext.Class' Extend preprocessor (which we talked about in the previous recipe) what class your new one should be inherited from. The preprocessor then merges all of the parent class' members into the new class' definition, giving us our extended class.

By extending the Vehicle class in this way our class diagram will look like the one shown as follows. Notice that the Plane class still inherits from the Ext.Base class through the Vehicle class' extension of it:

The callParent method is a very quick way of executing the parent class' version of the method. This is important to ensure that the parent class is constructed correctly and will still function as we expect. In previous versions of Ext JS, this was achieved by using the following syntax:

Plane.superclass.constructor.apply(this, arguments);

The new callParent method effectively still does this but it is hidden from the developer, making it much easier and quicker to call.

We can expand on this idea by adding new functionality to the Plane class and override the base class' travel method to incorporate this new functionality.

A plane's travel method is a little more complicated than a generic vehicle's so we're going to add takeOff and land methods to the class:

Ext.define('Cookbook.Plane', {
    ...

    takeOff: function(){
        alert('The ' + this.getManufacturer() + ' ' + this.getModel() + ' is taking off.');
    },

    land: function(){
        alert('The ' + this.getManufacturer() + ' ' + this.getModel() + ' is landing.');
    }

    ...
});

We can then override the travel method of the Vehicle class to add in the takeOff and land methods into the Plane's travel procedure:

Ext.define('Cookbook.Plane', {
    ...

    travel: function(distance){
        this.takeOff();

        // execute the base class’ generic travel method
        this.callParent(arguments);
        alert('The ' + this.getManufacturer() + ' ' + this.getModel() + ' flew at an altitude of ' + this.getMaxAltitude() + 'feet');

        this.land();
    }

    ...
});

This method extends the travel functionality given to us by the Vehicle class by alerting us to the fact that the plane is taking off, flying at a specific altitude, and then landing again.

The important part of this method is the call to the callParent method. This executes the base class' travel method, which runs the Vehicle's implementation of the travel method. Notice that it passes in the arguments variable as a parameter. This variable is available in all JavaScript functions and contains an array of all the parameters that were passed into it.

We can see this in action by creating a new Plane object and calling the travel method:

var plane = Ext.create('Cookbook.Plane', 'Boeing', '747', 500, 30000);

plane.travel(800); // alerts 'The Boeing 747 is taking off'
             // 'The Boeing 747 travelled 800 miles at 500mph'
             // 'The Boeing 747 flew at an altitude of 30000 feet'
             // 'The Boeing 747 is landing.'

By using the mixins configuration option we tell the class defining process to use the mixins preprocessor to merge all of the mixin class' members into the main class. This now means that all of the methods and properties defined as part of the HasCamera class can be accessed directly from the parent class' instance.

The name we give to our mixin in this configuration object allows us to reference it within our class' code. We will explore this later in the recipe.

Step 4, shows how we can access the HasCamera class' methods from the parent class by simply calling them as if they are part of the Smartphone class itself.

We might be required to override the functionality provided by our mixins class as we often would when using traditional inheritance.

In our example, we might want to introduce a focus routine into the takePhoto process to ensure that our subject is in focus before taking a photo. As we have done in previous recipes, we declare a method called takePhoto that will override the one added by the HasCamera Mixin, and another method to perform our focus operation:

Ext.define('Cookbook.Smartphone', {
    mixins: {
        camera: 'HasCamera'
    },

    useCamera: function(){
        this.takePhoto();
    },

    takePhoto: function(){
        this.focus();

        this.takePhoto();
    },

    focus: function(){
        alert('Focusing Subject...');
    }
});

At this point we are in trouble because our new takePhoto method needs to reference the original takePhoto method defined in the HasCamera class. However, at the moment it is pointing back to itself and will cause an infinite loop.

We get around this by calling the mixins method directly from its prototype, which can be accessed using the name we assigned it in Step 3. Our takePhoto method now becomes:

takePhoto: function(){
    this.focus();

    this.mixins.camera.takePhoto.call(this);
}

Scope refers to the context that a piece of code is executing in and decides what variables are available to it. JavaScript has two types of scope: global scope and local scope. Variables and functions declared in the global scope are available to code everywhere. Common examples are the document and window variables. Local Scope refers to variables and functions that have been declared within a function, and so are contained by that function. Therefore, they can't be accessed from code above it in the scope chain.

We will explore a couple of examples to demonstrate how this works.

When dealing with scope in Ext JS we are generally concerned with making sure our functions are executing in the scope of the correct class (whether it is a component, store, or controller). For example, by default an Ext.button.Button's click event will execute its handler function in the scope of itself (that is, this refers to the Ext.button.Button instance). It's likely that we want the button's handler to execute in the scope of the parent class (for example, a grid panel) and so we must force a different scope upon it.

We will now explore ways in which we can change the scope a function executes in using Ext JS' in-built functionality. By following these steps we will see how Ext JS makes it easy to ensure this refers to what you want it to!

Ext JS provides us with a method that allows us to force a function to execute in the scope we specify, meaning we can specify what the this keyword refers to within the function.

The Ext.bind method creates a wrapper function for the speak method that will force it to have its scope set to the object that is passed in, overriding the default scope value. This new function can be executed immediately (as our example did) or stored in a variable to be executed at a later point.

By using it we redefine the this keyword used within the function to refer to what was passed in as the second parameter. This is the reason that in Step 2 the alert displayed the value stored in the cat's sound property rather than the dog's.

Getting the scope of a function correct is especially important within event handlers. Ext JS provides a scope config option that can be used to explicitly set the scope an event handler is executed in.

Consider the following example where we define a button and attach a handler to its click event, which will show an alert of the current scope's text property:

var button = Ext.create('Ext.button.Button', {
    text: 'My Test Button',
    listeners: {
        click: function(button, e, options){
            alert(this.text);
        }
    },
    renderTo: Ext.getBody()
});

button.show();

By default, this refers to the button itself and displays My Test Button. But what if we want to execute the function in the scope of another object, like this one?

var exampleObject = {
    text: 'My Test Object'
};

Our initial reaction would be to use the Ext.bind method, which we looked at earlier in the recipe, and would look something like this:

listeners: {
    click: Ext.bind(function(button, e, options){
        alert(this.text);
    }, exampleObject)
}

This technique works well and functions correctly. However, there is a more succinct method in the form of the scope config option, which can be added as shown in the following code:

listeners: {
    click: function(button, e, options){
        alert(this.text);
    },
    scope: exampleObject
}

The scope object is effectively a short hand way of using Ext.bind and gives us the same outcome with less code.

If you were to include multiple event handlers within the listeners property the scope value would be applied to them all. If you want to specify a different scope value for each event, you can use the following syntax:

listeners: {
    click: {
        fn: function(button, e, options){
            alert(this.text);
        },
        scope: this
    },
    afterrender: {
        fn: function(button, options){
            // do something...
        },
        scope: otherObject 
    }
}

We are going to use the Vehicle and Plane classes that we created in the Using inheritance recipe earlier to demonstrate dynamic loading.

The initial configuration of the Ext.Loader class is vital for our classes to be loaded correctly, as it defines how class names are mapped to file locations so the Loader class knows where to find each class it is required to load. It also highlights the need for strict naming conventions when it comes to creating your files.

In our example, the paths configuration tells the Loader that any required classes within the Cookbook namespace should be loaded from the src/Cookbook directory.

We then call the Ext.require method, (an alias of the Ext.Loader.require method) which takes the class name specified and resolves its URL based on the paths configuration, and if it hasn't already been loaded previously, injects a script tag into the HTML page to load it. Once this load has happened the specified callback function is executed where you can create instances of the class with the knowledge that it has been fully loaded.

The Ext.require method accepts either a single or array of string values that will all be loaded prior to the callback being executed.

One of the great things about the Ext.Loader class is that it is recursive and won't stop until all the files needed by the original required classes are loaded. This means that it will load all classes referenced in the extend, mixins, and requires configuration objects.

We will demonstrate this by creating an instance of Cookbook.Plane , which extends the Cookbook.Vehicle class. If we execute the following code, and monitor your developer tool as we did before, we will see both classes being loaded and created:

Ext.require('Cookbook.Plane', function(){
   var plane = new Ext.create('Cookbook.Plane', 'Boeing', '747', 500, 35000);
   plane.travel(200);
});

Ext.reg() doesn't exist in Ext JS 4, instead we register aliases with the alias config option.

When the application is first loaded, the class definitions are parsed and a dictionary of class aliases is created. This is contained within the framework's component manager (Ext.ComponentManager).

We're required to name our aliases with a prefix, "widget." However, when using the alias the prefix is not required.

The aliases are, as you would expect, simply a reference to the class. As we haven't instantiated the class (yet) we're able to save memory and resources. This is particularly helpful when our widgets are nested deeply as resources are not wasted on components that are not required or even rendered.

As we destroy our components, the framework releases the resources, but keeps the alias reference in the component manager, so that we can re-create the same component time and time again.

Calling the alias is done using the xtype config option, which is where you provide the alias name.

There are other ways to define aliases for your components.

We will start by creating a simple application, which consists of a simple Ext.panel.Panel with a toolbar, buttons, a form, and a grid. This will form the basis of our examples as it has a number of components that we can query for.

var panel = Ext.create('Ext.panel.Panel', {

    height: 500,
    width: 500,
    renderTo: Ext.getBody(),
    layout: {
        type: 'vbox',
        align: 'stretch'
    },
    items: [{
        xtype: 'tabpanel',
        itemId: 'mainTabPanel',
        flex: 1,
        items: [{
            xtype: 'panel',
            title: 'Users',
            id: 'usersPanel',
            layout: {
                type: 'vbox',
                align: 'stretch'
            },
            tbar: [{
                xtype: 'button',
                text: 'Edit',
                itemId: 'editButton'
            }],
            items: [{
                xtype: 'form',
                border: 0,
                items: [{
                    xtype: 'textfield',
                    fieldLabel: 'Name',
                    allowBlank: false
                }, {
                    xtype: 'textfield',
                    fieldLabel: 'Email',
                    allowBlank: false
                }],
                buttons: [{
                    xtype: 'button',
                    text: 'Save',
                    action: 'saveUser'
                }]
            }, {
                xtype: 'grid',
                flex: 1,
                border: 0,
                columns: [{
                    header: 'Name',
                    dataIndex: 'Name',
                    flex: 1
                }, {
                    header: 'Email',
                    dataIndex: 'Email'
                }],
                store: Ext.create('Ext.data.Store', {
                    fields: ['Name', 'Email'],
                    data: [{
                        Name: 'Joe Bloggs',
                        Email: 'joe@example.com'
                    }, {
                        Name: 'Jane Doe',
                        Email: 'jane@example.com'
                    }]
                })
            }]
        }]
    }, {
        xtype: 'component',
        itemId: 'footerComponent',
        html: 'Footer Information',
        extraOptions: {
            option1: 'test',
            option2: 'test'
        },
        height: 40
    }]
});

The main method of the Ext.ComponentQuery class is the query method. As we have mentioned, it accepts a CSS/XPath style selector string and returns an array of Ext.Component (or subclasses of the Ext.Component class) instances that match the specified selector.

The Ext.ComponentQuery is a singleton class that encapsulates the query logic used in our examples. We have used the query method, which works by parsing each part of the selector and using it in conjunction with the Ext.ComponentManager class. This class is responsible for keeping track of all the existing Ext.Component instances, and is used to find any matching components.

There is one other method of the Ext.ComponentQuery class to introduce and a further four methods that are part of the Ext.container.AbstractContainer class.

var isPanel = Ext.ComponentQuery.is(panel, 'panel');

var lastTextfield = Ext.ComponentQuery.query('textfield:last');

Ext.ComponentQuery.pseudos.visible = function(items) {
    var result = [];

    for (var i = 0; i < items.length; i++) {

        if (items[i].isVisible()) {
            result.push(items[i]);
        }
    }

    return result;
};

var visibleComponents = Ext.ComponentQuery.query('component:visible');

We will define an extension of the Ext.panel.Panel class to create a simple display panel.

Our first step creates our new class definition and tells the framework to give our new class all the functionality that the Ext.panel.Panel has, through the use of the extend config option.

We then introduce an override for the initComponent method, which is used by each component to add its own configuration and perform any actions that are needed to set the component up. In order to ensure that this component behaves as it should, we call the parent class' initComponent method (in this case, Ext.panel.Panel) using the callParent method.

Next, we give our new class the configuration we want. We do this by using the Ext.apply method, which merges our configuration object into the class itself.

We are now able to instantiate our new class using its defined name and it will automatically be configured with all the properties we applied in the initComponent method. This means we can create a DisplayPanel anywhere in our code and only have to define it once.

We can take this idea further by integrating our own functionality into an extended component by overriding its functions. We are going to create a custom TextField that includes some information text below the field to help the user complete the form field correctly:

The override method of Ext.Base takes the original class and loops around the new functions that you've created by adding them to the prototype of the existing class and replacing any existing ones with the new definitions.

There are a number of other features in the framework that help you override and perform similar tasks.

Ext.define('Cookbook.overrides.TextField', {
    override: 'Ext.form.field.Text',

    onRender: function(){
        this.callParent(arguments);

        Ext.core.DomHelper.append(this.el, '<div>' + this.infoText + '</div>');
    }
});

Ext.application({
    launch: function(){
        Ext.create('Ext.container.Viewport', {
            layout: 'fit',
            items: [{
                xtype: 'form',
                defaultType: 'textfield',
                items: [{
                    fieldLabel: 'Security Question',
                    name: 'securityQuestion',
                    allowBlank: false,
                    infoText: 'You are required to write a security question for your account.'
                }, {
                    fieldLabel: 'Security Answer',
                    name: 'securityAnswer',
                    allowBlank: false,
                    infoText: 'Please provide the answer to your security
                }]
            }]
        });
    }
});