I have recently run across one of the the Jay Garcia’s excellent screencasts Abstract classes with Ext JS. (Thank you Jay for your effort of educating Ext JS community.)

I’ve been consulting in a company at that time – developers of the client, after seeing the screencast, immediately asked me: “So what should we use? The ‘xtype’ style or Abstract classes?”

The curt answer would be: “Use whatever you prefer.” or “Use both”.

However, decisions based on mere “preference” or on “I use it because it is available” are often not fully rational and can lead to troubles as the application grows. Thus, let’s take a deeper look to see if there are any pitfalls and to find how can we get most of both methods.

Note: Before you continue, read “Writing a big application in Ext”, watch the Jay’s screencast and understand both, otherwise, the following text won’t make any sense to you.

Abstract ExtJS Class

Abstract classes are not to be used directly but they serve more like templates that specify methods and properties to be implemented in classes derived from them. They are very useful in object oriented programming because they force developers to implement all mandatory methods with same signature (signature = arguments the method or function accepts) and return values so there is a greater chance to develop a bug free code.

However, in ExtJS (and JavaScript that is scripting language where source is not compiled but directly interpreted), there is no mechanism to warn developer “you haven’t implemented method XY” or “your implementation has wrong signature” so we need to take care ourselves.

Nevertheless, the idea of abstract classes is useful also in JavaScript/ExtJS environment because:

1. logic and configuration common to all expected descendants can be put in the abstract base class that eliminates the code duplication, speeds up development and debugging, and increases future code maintainability greatly
2. abstract classes tell us which methods to implement
3. it increases the human readability of the code (Remember, we always try to write the code to be readable and understandable by us and others in the future.)

The Basic Idea

The basic idea Jay presents in his great screencast is to extend an Ext Component, FormPanel for example, and add stub methods to it:

Ext.ns('MyApp');
 
MyApp.AbstractFormPanel = Ext.extend(Ext.form.FormPanel, {
     submitUrl:null
    ,initComponent:function() {
        Ext.apply(this, {
             items:this.buildItems()
            ,buttons:this.buildButtons()
        });
 
        MyApp.AbstractFormPanel.superclass.initComponent.call(this);
 
    } // eo function initComponent
 
    ,buildItems:function() {
        return [];
    } // eo function buildItems
 
    ,buildButtons:function() {
        return [];
    } // eo function buildButtons
 
}); // eo extend

The empty “buildXxx” methods will be implemented in the abstract class extension.

Tweaking the Abstract Class example

While perfect for the educational purposes, we need to tweak this code if want to use it in the production quality application. I shall walk you through recommended improvements.

initialConfig

Ext.Component takes the config object passed to its constructor and saves it in the object variable initialConfig when it instantiates. Although items and buttons in combination with the FormPanel in the above example do not rely on it, so the example runs as expected, initialConfig is used on the Ext.Component level so it may be used by any of Component descendants.

Let’s take care of it and modify initComponent as follows:

    ,initComponent:function() {
        // create config object
        var config = {};
 
        // build config properties
        Ext.apply(config, {
             items:this.buildItems()
            ,buttons:this.buildButtons()
        });
 
        // apply config
        Ext.apply(this, Ext.apply(this.initialConfig, config));
 
        // call parent
        MyApp.AbstractFormPanel.superclass.initComponent.call(this);
 
    } // eo function initComponent

Return Values

Abstract methods in the example return empty arrays. That is no problem for items or buttons but if we want to have also buildTbar or buildBbar factory functions that return empty arrays [] then top and bottom toolbars are always created, but empty, if methods are not implemented in derived classes. (Empty toolbars are quite ugly when rendered.)

Therefore, always return undefined from the abstract methods. For now, the class could look like this:

Ext.ns('MyApp');
 
MyApp.AbstractFormPanel = Ext.extend(Ext.form.FormPanel, {
     submitUrl:null
    ,initComponent:function() {
        // create config object
        var config = {};
 
        // build config properties
        Ext.apply(config, {
             items:this.buildItems()
            ,buttons:this.buildButtons()
            ,tbar:this.buildTbar()
            ,bbar:this.buildBbar()
        });
 
        // apply config
        Ext.apply(this, Ext.apply(this.initialConfig, config));
 
        // call parent
        MyApp.AbstractFormPanel.superclass.initComponent.call(this);
 
    } // eo function initComponent
 
    ,buildItems:function() {
        return undefined;
    } // eo function buildItems
 
    ,buildButtons:function() {
        return undefined;
    } // eo function buildButtons
 
    ,buildTbar:function() {
        return undefined;
    } // eo function buildTbar
 
    ,buildBbar:function() {
        return undefined;
    } // eo function buildBbar

Passing config to Abstract Factory Methods

If we pass config object to abstract methods then we can apply the created items, buttons, toolbar items directly to it. That has no great benefit in itself, however, if we create a sequence or interceptor of these methods we can use the config object directly.

So now we have:

Ext.ns('MyApp');
 
MyApp.AbstractFormPanel = Ext.extend(Ext.form.FormPanel, {
     submitUrl:null
    ,initComponent:function() {
        // create config object
        var config = {};
 
        // build config properties
        this.buildItems(config);
        this.buildButtons(config);
        this.buildTbar(config);
        this.buildBbar(config);
 
        // apply config
        Ext.apply(this, Ext.apply(this.initialConfig, config));
 
        // call parent
        MyApp.AbstractFormPanel.superclass.initComponent.call(this);
 
    } // eo function initComponent
 
    ,buildItems:function(config) {
        config.items = undefined;
    } // eo function buildItems
 
    ,buildButtons:function(config) {
        config.buttons = undefined;
    } // eo function buildButtons
 
    ,buildTbar:function(config) {
        config.tbar = undefined;
    } // eo function buildTbar
 
    ,buildBbar:function(config) {
        config.bbar = undefined;
    } // eo function buildBbar
 
}); // eo extend

The Final Touch

If you look in the initComponent now you see that we call a series of “build” functions in it. Let’s move it into another factory method:

Ext.ns('MyApp');
 
MyApp.AbstractFormPanel = Ext.extend(Ext.form.FormPanel, {
     submitUrl:null
    ,initComponent:function() {
        // create config object
        var config = {};
 
        // build config
        this.buildConfig(config);
 
        // apply config
        Ext.apply(this, Ext.apply(this.initialConfig, config));
 
        // call parent
        MyApp.AbstractFormPanel.superclass.initComponent.call(this);
 
    } // eo function initComponent
 
    ,buildConfig:function(config) {
        this.buildItems(config);
        this.buildButtons(config);
        this.buildTbar(config);
        this.buildBbar(config);
    } // eo function buildConfig
 
    ,buildItems:function(config) {
        config.items = undefined;
    } // eo function buildItems
 
    ,buildButtons:function(config) {
        config.buttons = undefined;
    } // eo function buildButtons
 
    ,buildTbar:function(config) {
        config.tbar = undefined;
    } // eo function buildTbar
 
    ,buildBbar:function(config) {
        config.bbar = undefined;
    } // eo function buildBbar
 
}); // eo extend

The above gives you the flexibility of implementing or overriding of the whole buildConfig function or individual items, buttons, bars functions. It also takes care of initialConfig problem.

It’s a kind of a “pattern” and I will publish it in my “file patterns” series on this blog with more code comments.

Example

If we build upon Jay’s example, using the pattern above, we get:

AbstractFormPanel.js:

Ext.ns('MyApp');
 
MyApp.AbstractFormPanel = Ext.extend(Ext.form.FormPanel, {
     defaultType:'textfield'
    ,frame:true
    ,width:300
    ,height:200
    ,labelWidth:75
    ,submitUrl:null
    ,submitT:'Submit'
    ,cancelT:'Cancel'
    ,initComponent:function() {
 
        // create config object
        var config = {
            defaults:{anchor:'-10'}
        };
 
        // build config
        this.buildConfig(config);
 
        // apply config
        Ext.apply(this, Ext.apply(this.initialConfig, config));
 
        // call parent
        MyApp.AbstractFormPanel.superclass.initComponent.call(this);
 
    } // eo function initComponent
 
    ,buildConfig:function(config) {
        this.buildItems(config);
        this.buildButtons(config);
        this.buildTbar(config);
        this.buildBbar(config);
    } // eo function buildConfig
 
    ,buildItems:function(config) {
        config.items = undefined;
    } // eo function buildItems
 
    ,buildButtons:function(config) {
        config.buttons = [{
             text:this.submitT
            ,scope:this
            ,handler:this.onSubmit
            ,iconCls:'icon-disk'
        },{
             text:this.cancelT
            ,scope:this
            ,handler:this.onCancel
            ,iconCls:'icon-undo'
        }];
    } // eo function buildButtons
 
    ,buildTbar:function(config) {
        config.tbar = undefined;
    } // eo function buildTbar
 
    ,buildBbar:function(config) {
        config.bbar = undefined;
    } // eo function buildBbar
 
    ,onSubmit:function() {
        Ext.MessageBox.alert('Submit', this.submitUrl);
    } // eo function onSubmit
 
    ,onCancel:function() {
        this.el.mask('This form is canceled');
    } // eo function onCancel
 
}); // eo extend

Mention please that I moved hard-wired button texts to class properties. The reason is that this way we can easily localize (translate) these texts to another languages. I didn’t take care of messages of handlers though. You will do in your localizable applications, won’t you?

AddressFormPanel.js:

Ext.ns('MyApp');
 
MyApp.AddressFormPanel = Ext.extend(MyApp.AbstractFormPanel, {
     title:'Edit address data'
    ,submitUrl:'addressAction.asp'
    ,buildItems:function(config) {
        config.items = [{
             name:'address1'
            ,fieldLabel:'Address 1'
        },{
             name:'address2'
            ,fieldLabel:'Address 2'
        },{
             name:'city'
            ,fieldLabel:'city'
        },{
             xtype:'combo'
            ,name:'state'
            ,fieldLabel:'State'
            ,store:['MD', 'VA', 'DC']
        },{
             xtype:'numberfield'
            ,name:'zip'
            ,fieldLabel:'Zip Code'
        }];
    } // eo function buildItems
 
});
 
// eof

NameFormPanel.js:

Ext.ns('MyApp');
 
MyApp.NameFormPanel = Ext.extend(MyApp.AbstractFormPanel, {
     title:'Edit name data'
    ,submitUrl:'nameAction.asp'
    ,okT:'OK'
 
    ,buildItems:function(config) {
        config.items = [{
             name:'firstName'
            ,fieldLabel:'First Name'
        },{
             name:'lastName'
            ,fieldLabel:'Last Name'
        },{
             name:'middleName'
            ,fieldLabel:'Middle Name'
        },{
             xtype:'datefield'
            ,name:'dob'
            ,fieldLabel:'DOB'
        }];
    } // eo function buildItems
 
    //Extension
    ,buildButtons:function(config) {
 
        // let parent build buttons first
        MyApp.NameFormPanel.superclass.buildButtons.apply(this, arguments);
 
        // tweak the submit button
        config.buttons[0].text = this.okT;
        config.buttons[0].handler = this.onOkBtn;
 
    } // eo function buildButtons
 
    //Override
    ,onOkBtn:function() {
        console.info('OK btn pressed');
    } // eo function onOkBtn
 
}); // eo extend
 
// eof

With this setup, we can even create instance of AbstractForm panel directly passing some/all build functions inline:

var nameForm = new MyApp.AbstractFormPanel({
     title:'Name Form Panel configured inline'
    ,width:300
    ,height:200
    ,renderTo:Ext.getBody()
    ,buildItems:function(config) {
        config.items = [{
             name:'firstName'
            ,fieldLabel:'First Name'
        },{
             name:'lastName'
            ,fieldLabel:'Last Name'
        },{
             name:'middleName'
            ,fieldLabel:'Middle Name'
        },{
             xtype:'datefield'
            ,name:'dob'
            ,fieldLabel:'DOB'
        }];
    } // eo function buildItems
});

Note: Although the above works, it violates the rule of not instantiating an abstract class directly. It’s up to you if you will do it or not.

Combining with “xtypes”

Now, do not succumb to the temptation of “putting everything” in factory functions. Abstract classes are just a programming style, not an universal solvent.

Imagine, you have your own carefully crafted Submit and Cancel buttons so if you would “put everything” in the factory functions you would need to copy buttons configurations many times because also toolbars, grids, data views, etc can contain them.

Create extensions (xtypes) for those buttons instead. The following illustrates the approach:

SubmitButton.js

Ext.ns('MyApp');
 
MyApp.SubmitButton = Ext.extend(Ext.Button, {
     text:'Submit'
    ,iconCls:'icon-disk'
    ,initComponent:function() {
        MyApp.SubmitButton.superclass.initComponent.apply(this, arguments);
    } // eo function initComponent
}); // eo extend
 
Ext.reg('submitbutton', MyApp.SubmitButton);
 
// eof

CancelButton.js:

Ext.ns('MyApp');
 
MyApp.CancelButton = Ext.extend(Ext.Button, {
     text:'Cancel'
    ,iconCls:'icon-undo'
    ,initComponent:function() {
        MyApp.CancelButton.superclass.initComponent.apply(this, arguments);
    } // eo function initComponent
}); // eo extend
 
Ext.reg('cancelbutton', MyApp.CancelButton);
 
// eof

and AbstractFormPanel.js:

Ext.ns('MyApp');
 
MyApp.AbstractFormPanel = Ext.extend(Ext.form.FormPanel, {
     defaultType:'textfield'
    ,frame:true
    ,width:300
    ,height:200
    ,labelWidth:75
    ,submitUrl:null
    ,initComponent:function() {
 
        // create config object
        var config = {
            defaults:{anchor:'-10'}
        };
 
        // build config
        this.buildConfig(config);
 
        // apply config
        Ext.apply(this, Ext.apply(this.initialConfig, config));
 
        // call parent
        MyApp.AbstractFormPanel.superclass.initComponent.call(this);
 
    } // eo function initComponent
 
    ,buildConfig:function(config) {
        this.buildItems(config);
        this.buildButtons(config);
        this.buildTbar(config);
        this.buildBbar(config);
    } // eo function buildConfig
 
    ,buildItems:function(config) {
        config.items = undefined;
    } // eo function buildItems
 
    ,buildButtons:function(config) {
        config.buttons = [{
             xtype:'submitbutton'
            ,scope:this
            ,handler:this.onSubmit
        },{
             xtype:'cancelbutton'
            ,scope:this
            ,handler:this.onCancel
        }];
    } // eo function buildButtons
 
    ,buildTbar:function(config) {
        config.tbar = undefined;
    } // eo function buildTbar
 
    ,buildBbar:function(config) {
        config.bbar = undefined;
    } // eo function buildBbar
 
    ,onSubmit:function() {
        Ext.MessageBox.alert('Submit', this.submitUrl);
    } // eo function onSubmit
 
    ,onCancel:function() {
        this.el.mask('This form is canceled');
    } // eo function onCancel
 
}); // eo extend
 
// eof

Note: The above buttons are far too simple to be extended in the real world but you get the point, right?

Conclusion

Abstract classes, as Jay Garcia defines and presents them, are a very useful ExtJS programming technique and if you use them in the information provided in this post your code will be clean, flexible and maintainable. That is what all we developers want.

Happy coding!

Further reading:

1. Writing a Big Application in Ext
2. Abstract classes with Ext JS

I’ve run across the following code in some of Ext 3.x examples:

this.mon(toolsUl, 'click', this.onClick, this);

Looks like event handler installation but what it really does anyway?

So I delved into the code and remembered ExtJS Conference and now it is clear to me.

Imagine you create a component and then you need to install an event handler, for example, on its body. Something like:

var handler = function() {
    alert('You clicked my body');
};
var p = new Ext.Panel({
     renderTo:Ext.getBody()
    ,title:'Panel with a listener on the body'
});
p.body.on('click', handler);

Easy enough, we’ve done something like this many times. But, if the panel is ever to be destroyed we need to remove this listener ourselves as Ext knows nothing about it.

Something like:

var p = new Ext.Panel({
     renderTo:Ext.getBody()
    ,title:'Panel with a listener on the body'
    ,beforeDestroy:function() {
        this.body.un('click', handler);
    }
});

If we install our listener as inline function, such as:

p.on('click', function() {alert('You clicked my body')});

then it is impossible to remove this listener selectively, you would need to use

p.body.removeAllListeners();

to remove all body listeners.

Now, if we use mon (m stands for “managed”) this way

p.mon(p.body, 'click', handler);

then the listener is automatically removed by Ext on panel destroy. Nice, isn’t it? Saves a lot of our work and also handles our laziness or forgetfulness about destroying and cleanups of components.

Mind the first argument, that is the element to install the listener to. It can, but not necessarily have to be within the component. Also remember that when you destroy p Ext only removes listener from the element so if the element is outside of p you need to remove it yourself if it is not necessary anymore.

Should you ever need to remove the listener installed by mon you use mun with same arguments. You cannot selectively remove inline listeners.

mon and mun are defined in Component so you can use them from Component down the descendant classes chain.

Warning! mon and mun are not documented (yet?) so there is still (a little) risk that they will change or will be removed.

<<< Mastering Ext.Direct, Part 2

Processing responses

As I’ve already said, you cannot use the return value of an API function call as result is not know at the moment of the call return. It is never stressed enough that

Ext.Direct calls are ASYNCHRONOUS.

Therefore, all Ext.Direct created API functions, for example Example.Car.go() take one extra argument in addition to arguments you have specified in server-side class definition. That argument is callback function.

In our example, Example.Car.go() takes one argument, speed per server side method definition, however, it takes two in fact: Example.Car.go(speed, callback)

Let’s call it with a callback to test it. Type in the Firebug console:

Example.Car.go(80, console.info);

console.info is a function that prints its arguments in a human readable form. We use it as the callback so we see:

• that it really gets called when the response arrives
• which arguments Ext.Direct passes to the callback

As you can see, the callback is called with two arguments:

• response – it is that what is returned by the server-side Car.go() method. It can be string (as in our example), boolean, object, array or void (nothing).
• e – it is Ext.Direct.Event object or, being more specific, Ext.Direct.RemotingEvent.

The event e has some useful properties and methods, most important of them are:

• status is true if the call was successful, false if the call failed
• result contains same value as the first argument – it is server response data
• type is rpc in our example but it also can be exception or others
• action is the class name
• method is name of the method called
• getTransaction() is method to retrieve the transaction used in this server round trip. You would use it if you want more data on the transaction.

Processing exceptions

Let’s call go method again:

Example.Car.go(300, console.info);

The callback is called as before but the arguments differ:

• response is undefined – no data from server
• e has type exception and has property message that contains error message text

An example application

That is almost all we need to know to start using Ext.Direct in an application. I’ve written a simple one so you have something to play with.

First, create file example.js with the following content:

/**
 * Mastering Ext.Direct example script
 *
 * @author     Ing. Jozef Sakalos
 * @copyright  (c) 2009, by Ing. Jozef Sakalos
 * @date       16. September 2009
 * @version    1.0
 * @revision   $Id$
 */
 
Ext.BLANK_IMAGE_URL='ext/resources/images/default/s.gif';
 
Ext.onReady(function() {
    /**
     * This function is called when Ext.Direct request
     * response arrives from the server.
     *
     * @param {String/Object/Array/Null} response 
     * That what is returned by server method
     * @param {Ext.Direct.RemotingEvent/Ext.Direct.ExceptionEvent} e 
     */
    var callback = function(response, e) {
 
        // uncomment if you want to inspect arguments in Firebug Console
//        console.log(response, e);
 
        var status = '<b>Success</b>'
        var text = '';
 
        // success handling - e.status is success flag: 
        // true is success, false is failure
        if(true === e.status) {
            // response argument is same as e.result
            text = response;
        }
 
        // failure handling
        else {
            status = '<b><i>Failure</i></b>'
 
            // in the case of an exception, we don't have response but message
            text = e.message;
        }
 
        // grab the center body
        var body = win.items.itemAt(1).body;
 
        // display the response
        body.createChild({
             tag:'div'
            ,cls:'response'
            ,html:status + ': ' + text
        });
 
        // scroll down
        body.scrollTo('top', 100000, true);
    };
 
 
    // create Ext.Direct test window
    var win = new Ext.Window({
         title:'Mastering Ext.Direct by Saki'
        ,width:600
        ,height:400
        ,closable:false
        ,layout:'border'
        ,border:false
        ,items:[{
            // west region with buttons
             region:'west'
            ,width:160
            ,minSize:160
            ,split:true
            ,defaults:{minWidth:120}
            ,layout:'table'
            ,bodyStyle:'padding:20px'
            ,layoutConfig:{columns:1, tableAttrs:{style:{width:'100%'}}}
            ,items:[{
                 xtype:'button'
                ,text:'Car.start()'
 
                // a delegate is needed if we want to pass arguments
                ,handler:Example.Car.start.createDelegate(null, [callback])
            },{
                 xtype:'button'
                ,text:'Car.go(80)'
 
                // a delegate is needed if we want to pass arguments
                ,handler:Example.Car.go.createDelegate(null, [80, callback])
            },{
                 xtype:'button'
                ,text:'Car.go(250)'
 
                // a delegate is needed if we want to pass arguments
                ,handler:Example.Car.go.createDelegate(null, [250, callback])
            },{
                 xtype:'button'
                ,text:'Car.stop()'
 
                // a delegate is needed if we want to pass arguments
                ,handler:Example.Car.stop.createDelegate(null, [callback])
            },{
                 xtype:'button'
                ,text:'Send All'
 
                // another option is inline function that executes calls
                ,handler:function() {
 
                    // the following calls will be combined in one request
                    Example.Car.start(callback);
                    Example.Car.go(80, callback);
                    Example.Car.go(250, callback);
                    Example.Car.stop(callback);
                }
            }]
        },{
            // responses are displayed here
             region:'center'
            ,autoScroll:true
            ,tbar:['->', {
                text:'Clear'
               ,handler:function(){win.items.itemAt(1).body.update('')}
            }]
        }]
    });
    win.show();
 
});
 
// eof

Then tune your index.php so that it reads:

<?require_once("config.php");?>
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <link rel="stylesheet" type="text/css" href="ext/resources/css/ext-all.css">
  <script type="text/javascript" src="ext/adapter/ext/ext-base.js"></script>
  <script type="text/javascript" src="ext/ext-all-debug.js"></script>
  <title id="page-title">Mastering Ext.Direct by Saki</title>
  <style type="text/css">
      .x-table-layout-cell {
        height:40px;
        text-align:center;
        vertical-align:middle;
    }
    .x-table-layout-cell table {
        margin:auto
    }
    .response {
        padding:4px 0 4px 20px;
        font-size:13px;
    }
  </style>
  <script type="text/javascript" src="api.php"></script>
  <script type="text/javascript">
      Ext.Direct.addProvider(Example.API);
  </script>
  <script type="text/javascript" src="example.js"></script>
</head>
<body>
</body>
</html>

Conclusion

Good! Play with Ext.Direct and let me know what you would like to have in next parts.

<<< Mastering Ext.Direct, Part 1

Adding server-side classes

After completing part 1, we have the basic setup running. Although Ext.Direct PHP stack example classes are fine for demonstrating the functionality we will need our own PHP classes in the real life. I’m not going to explain basics of PHP object oriented programming, anyway, there is a couple of things to point out.

Let’s create (useless) class Car from part1. For that, create file classes/Car.php with the following content:

<?php
// vim: sw=4:ts=4:fdc=4:nospell
    class Car {
        /**
          * @remotable
          */
        public function start() {
            return "Started";
        } // eo function start
 
        /**
          * @remotable
          */
        public function go($speed) {
            return "The speed is $speed";
        } // eo function go
 
        /**
          * @remotable
          */
        public function stop() {
            return "Stopped";
        } // eo function stop
 
        public function repair() {
            return "Done";
        } // eo function repair
 
    } // eo class car
// eof

Then edit api.php and add Car to $api->add() call so that it reads:

// ...
$api->add(
    array(
        'Echo' => array('prefix' => 'Class_'),
        'Exception' => array('prefix' => 'Class_'),
        'Time',
        'File',
        'Car'
    )
);
// ...

Reload index.php and type in Firebug console:

Example.Car.start();

You should get the following response:

{"type":"rpc","tid":2,"action":"Car","method":"start","result":"Started"}

Now type:

Example.Car.repair();

Error, yes? Why? Take a deeper look at Car source code. Some methods have comments

        /**
          * @remotable
          */

but repair does not have it. And that is the single reason why it is not exported to API so it is not known to the client application. You can verify it by typing:

Example.API.actions.Car;

in Firebug console.

If you want to know how is it done study ExtDirect_API PHP class in classes/API.php file and ReflectionClass documentation. In any case, it makes our life very easy as we only need to:

• write server side classes
• add the above comment to the methods that can be called remotely

Can it be simpler?

Returning values

Type in Firebug console:

console.log(Example.Car.start());

Now you see that the return value of the call is undefined despite of the fact that server side method returns string "Started". This leads us to a very important note:

Ext.Direct calls are ASYNCHRONOUS.

That means that the code execution does NOT wait until the call is finished but it immediately continues. So never try to use the return value, neither assume that you have data available at the line that follows the call.

The value returned from the server side method call is wrapped in the request response and it arrives when it arrives. It can take milliseconds or seconds depending on the connection speed, server execution time and other factors.

I will discuss response processing in the next part

Exceptions

Edit go method of our Car class so that it reads:

        /**
          * @remotable
          */
        public function go($speed) {
            if(0 >= $speed || 200 < $speed) {
                throw new Exception("Speed must be between 0 and 200");
            }
            return "The speed is $speed $unit";
        } // eo function go

and execute:

Example.Car.go(300);

You get the following response:

{"type":"exception","tid":3,
"message":"Speed must be between than 0 and 200",
"where":
"#0 [internal function]: Car->go(300)\n
#1 \/ddata1\/devel\/extjs.eu\/direct\/ExtDirect\/Router.php(176): call_user_func_array(Array, Array)\n
#2 \/ddata1\/devel\/extjs.eu\/direct\/ExtDirect\/Router.php(62): ExtDirect_Router->rpc(Object(stdClass))\n
#3 \/ddata1\/devel\/extjs.eu\/direct\/router.php(23): ExtDirect_Router->dispatch()\n
#4 {main}"}

You see that the response type changed from rpc (remote procedure call) to exception and the response contains member message that is the text of the Exception we’ve thrown at server side. So far so good, however, where member contains debugging data that, while useful for debugging, shouldn’t be disclosed in a production environment.

You can freely throw exceptions while debugging your Ext.Direct application but you should consider another method(s) of handling errors for production systems. I will tackle it again later in this series.

Combining requests

Type the following:

Example.Car.start();Example.Car.go(80);Example.Car.stop();

The request is:

[
{"action":"Car","method":"start","data":null,"type":"rpc","tid":4},
{"action":"Car","method":"go","data":[80],"type":"rpc","tid":5},
{"action":"Car","method":"stop","data":null,"type":"rpc","tid":6}
]

and the response is:

[
{"type":"rpc","tid":4,"action":"Car","method":"start","result":"Started"},
{"type":"rpc","tid":5,"action":"Car","method":"go","result":"The speed is 80"},
{"type":"rpc","tid":6,"action":"Car","method":"stop","result":"Stopped"}
]

Ext.Direct combines requests that come within a configurable time frame into one to minimize the server round trips count.

Conclusion

Now we know a couple of basics:

• we need to export API from server to client – Ext.Direct stack does a lot of dirty work for us
• we can call server side methods directly at client prefixed with a configurable namespace (Example in our case)
• we cannot use return values of client calls because calls are asynchronous
• to add classes we need to add them to $api->add() call and add /** @remotable */ comments to methods
• multiple requests and responses are combined in one if they come fast enough

Mastering Ext.Direct, Part 3 >>>

Preface

My first idea how to the name this article was “Ext.Direct for Dummies” just because I feel as a one as long as Ext.Direct is concerned. I’ve first heard about it during Ext Conference in April and I think that it is one of the brightest ideas of Ext 3.x release. Nevertheless, I had no time do dig into into it and to understand the concepts fully.

Now I’ve decided to take a journey of discovering what is under hood, how to setup client and server side and how to use Ext.Direct effectively in applications. If you want, I invite you to travel with me.

Who is this article for

It is for developers who are familiar (at least) with basic javascript and Ext object oriented programming, who are able to setup a web page and have it running from a http server and who can code in a server-side programming language. (I will use PHP in this article so PHP developers will have a slight advantage.)

What is Ext.Direct anyway

Rich Internet Applications (RIA) consist of two parts: client side and server side. Client cannot call server functions directly but sends requests, server processes them calling the appropriate functions and returns results back to client.

Let’s say we have a server side class Car that has methods start, go and stop. From the client viewpoint, we need to ask server: Please, start the Car, then go with it and then stop it.

Now, imagine that we could directly call

Car.start();
Car.go();
Car.stop();

and these would call server side methods of server side class Car. Nice, isn’t it? You need to remember only one set of class names and their methods, code is neat and less bug prone.

And that is what Ext.Direct does. You export list of server side classes and their methods that should be made available for client to call and Ext.Direct takes care of the rest so that you can really use Car.start() in your code.

What we need

1. a working http server we have an access to. It can be installed on the local computer but it must be present. file:///something links will not work
2. a server side (scripting) language enabled in the above server. If you will use PHP, you need 5+ version to take advantage of ReflectionClass
3. Ext JS 3.0.0 library or latest Ext version built from SVN, if you have purchased Ext Premium Membership
4. Ext.Direct Pack
5. Firefox with Firebug installed
6. If you use PHP, FirePHP is strongly recommended

Initial setup

1. create directory direct under your http server document root. Name does not matter in fact but I will use direct as the root for testing in this article.
2. extract ExtJS into ext subdirectory under direct
3. extract content of php subdirectory from Ext.Direct Pack under direct
4. extract content of FirePHPCore-x.x.x into firephp subdirectory under direct

At this point, your direct directory listing should read the following:

+ cache/
+ classes/
+ data/
+ ext/
+ ExtDirect/
+ firephp/
  api.php
  router.php

The first test

We still need to do some work before we can see it running. First, create config.php file with the following content:

<?
// vim: sw=4:ts=4:fdc=4:nospell
 
// authentication would come here in the real world
 
// switch it to false if you do not want to use FirePHP
// $useFirePHP would be false also for a production system
$useFirePHP = true;
 
// require FirePHP files
if($useFirePHP) {
	require_once("firephp/lib/FirePHPCore/FirePHP.class.php");
	require_once("firephp/lib/FirePHPCore/fb.php");
}
 
// define empty fb() function so code does not break 
// on any forgotten fb() calls later
else {
	function fb() {};
}
 
// eof
?>

We also need index.php so we have something to run:

<?require_once("config.php");?>
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <link rel="stylesheet" type="text/css" href="ext/resources/css/ext-all.css">
  <script type="text/javascript" src="ext/adapter/ext/ext-base.js"></script>
  <script type="text/javascript" src="ext/ext-all-debug.js"></script>
  <title id="page-title">Mastering Ext.Direct by Saki</title>
  <script type="text/javascript" src="api.php"></script>
  <script type="text/javascript">
  	Ext.Direct.addProvider(Example.API);
  </script>
</head>
<body>
</body>
</html>

Ext.Direct Pack comes with example PHP classes (Echo, Exception, File and Time) and with api.php file. You can leave classes untouched for the moment but edit api.php to read the following:

<?php
require_once("config.php");
 
session_start();
 
// Include ExtDirect PHP Helpers
require_once('ExtDirect/API.php');
require_once('ExtDirect/CacheProvider.php');
 
// disable caching for development, enable for production
//$cache = new ExtDirect_CacheProvider('cache/api_cache.txt');
$api = new ExtDirect_API();
 
$api->setRouterUrl('router.php'); // default
 
// disable caching for development, enable for production
//$api->setCacheProvider($cache);
 
$api->setNamespace('Example');
$api->setDescriptor('Example.API');
$api->setDefaults(array(
    'autoInclude' => true,
    'basePath' => 'classes'
));
 
$api->add(
    // these are example classes from Ext.Direct PHP stack
    array(
        // real class name is Class_Echo, therefore prefix
        'Echo' => array('prefix' => 'Class_'),
 
        // real class name is Class_Exception, therefore prefix
        'Exception' => array('prefix' => 'Class_'),
        'Time',
        'File'
    )
);
$api->output();
 
$_SESSION['ext-direct-state'] = $api->getState();
 
// eof
?>

So far, so good… Now you can navigate to http://yourserver/direct/index.php and if everything went right you will see the blank page and no errors in Firebug.

Open Firebug console and type the following:

Example.Time.get();

You can see that request is sent to server:

{"action":"Time","method":"get","data":null,"type":"rpc","tid":2}

and that response comes back:

{"type":"rpc","tid":2,"action":"Time","method":"get","result":"09-05-2009 19:46:38"}

You can try other classes and methods:

Example.Echo.send("Test to be echoed");
Example.File.list(".");
Example.Time.get();

and you can also put fb($someVariable) statement in various places of php code if you want to know what’s going on here and there.

Conclusion

We have set up very minimum of Ext.Direct server and client side. The main purpose of this part is to get acquainted with basic components of this technology.

Mastering Ext.Direct, Part 2 >>>

You know, I’m not very big fan of factory functions, nevertheless, I’m aware of the fact that they may be necessary in some situations. Here is the file pattern that works (briefly tested).

Keep each factory function in a separate file name of which should be Namespace.Factory.functionName.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

// vim: ts=4:sw=4:nu:fdc=4:nospell
/*global Ext, MyNamespace */
/**
 * @class MyNamespace.Factory
 *
 * A Factory function pattern
 *
 * @author    Ing. Jozef Sakáloš
 * @copyright (c) 2009, by Ing. Jozef Sakáloš
 * @date      17. March 2009
 * @version   0.1
 * @revision  $Id$
 *
 * @license MyNamespace.Factory.myPanel.js is licensed under the terms of
 * the Open Source LGPL 3.0 license. Commercial use is permitted to the extent
 * that the code/component(s) do NOT become part of another Open Source or 
 * Commercially licensed development library or toolkit 
 * without explicit permission.
 * 
 * <p>License details: <a href="http://www.gnu.org/licenses/lgpl.html"
 * target="_blank">http://www.gnu.org/licenses/lgpl.html</a></p>
 */
 
// create namespace
Ext.ns('MyNamespace.Factory');
 
/**
 * @method myPanel
 * @param {Object} config
 * A config object
 * @return {Ext.Panel}
 */
MyNamespace.Factory.myPanel = function(config) {
 
	// pre-instantiation code
	var defaults = {
		// put your defaults here
		// but avoid id, el, contentEl, renderTo, applyTo, or similar
	}; // eo defaults object
 
	// create config object
	var cfg = Ext.apply({}, config, defaults);
 
	// instantiate
	var cmp = new Ext.Panel(cfg);
 
	// post-instantiation code
 
	// return the created component
	return cmp;
 
} // eo function MyNamespace.Factory.myPanel
 
// eof

Important

If you have not already done so, study Writing a Big Application in Ext (Part 1) and Writing a Big Application in Ext (Part 2)before you read this article. It would be very hard, if not impossible, to understand concepts explained here before you fully understand the first and second part.

Introduction

Helping on the forum and reading code of others that failed to extend Ext classes, revealed more errors that users, especially beginners, commonly make. Therefore, I’ve decided to start this article that will collect these errors and will explain why the errors are errors. I mean it as loosely ended as I may discover more errors and ways of avoiding them so I plan just to add them to this article, not endlessly create parts 4, 5, etc…

… continued: Most Common Sources of Troubles

Here we go:

1. Unnecessary Extending
2. Adding Objects to Prototype
3. Hard Coding ids

Unnecessary Extending

The main reasons for extending are:

• re-usability
• adding functionality
• combination of them

so we extend if we need a re-usable component or we need to add a functionality (new methods) or both. If we are after re-usability the extension can be as simple as:

1
2
3
4
5

MyPortlet = Ext.extend(Ext.Panel, {
     anchor:'100%'
    ,draggable:true
    ,defaultType:'mygraph'
});

You see what happens? We are going to use MyPortlet many times so instead of scatter the above configuration in 10,000 lines application code 100 times, we create this simple extension and we save 297 lines of code.

The other aspect is that if we upgrade our ‘mygraph’ to ‘mygraph_new’ the only place where to change it is our extension saving us searching out code for all occurrences of ‘mygraph’ (100 times) and replacing it with ‘mygraph_new’ 100 times.

(Well, 100 is exaggerated, but you get the point, right?)

If we are after adding functionality, which can be also simple, we add some “logic”:

1
2
3
4
5
6

MyPanel = Ext.extend(Ext.Panel, {
    onRender:function() {
        MyPanel.superclass.onRender.apply(this, arguments);
        alert('Rendered');
    }
});

Here we add some logic to Panel, it does more that it did before.

There is no need to extend in all other cases.

Adding Objects to Prototype

Run this code first:

<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <link rel="stylesheet" type="text/css" href="ext/resources/css/ext-all.css">
  <script type="text/javascript" src="ext/adapter/ext/ext-base.js"></script>
  <script type="text/javascript" src="ext/ext-all-debug.js"></script>
  <title id="page-title">Extending Error: Object in prototype</title>
  <script type="text/javascript">
  Ext.BLANK_IMAGE_URL = 'ext/resources/images/default/s.gif';
  Ext.onReady(function() {
    MyPanel = Ext.extend(Ext.Panel, {
         layout:'fit'
        ,panelConfig: {
            bodyBg:'red'
        }
 
        ,initComponent:function() {
            var config = {
                bodyStyle:'background-color:' + this.panelConfig.bodyBg
            }; // eo config object
 
            // apply config
            Ext.apply(this, Ext.apply(this.initialConfig, config));
 
            MyPanel.superclass.initComponent.apply(this, arguments);
        } // eo function initComponent
 
        ,applyBackground:function(color) {
            this.panelConfig.bodyBg = color;
            this.body.applyStyles({'background-color':color});
        } // eo function applyBackground
 
    }); // eo extend
 
    var p1 = new MyPanel({
         title:'Panel with Blue Background'
        ,renderTo:Ext.getBody()
        ,width:240
        ,height:160
    });
 
    p1.applyBackground('blue');
 
    var p2 = new MyPanel({
         title:'Panel with Red Background'
        ,renderTo:Ext.getBody()
        ,width:240
        ,height:160
    });
 
  });
  </script>
</head>
<body></body>
</html>

What do we expect? It is written in titles of panels: Top panel (p1) should have blue body background because we set it to it after it is created. And bottom panel (p2) should have red because we just create default MyPanel.

But it is blue too!!! Why? The reason is simple: panelConfig is object that is created during class definition and it is added to MyPanel prototype. Objects (arrays too) are accessed by reference so p1 and p2 share the same instance of panelConfig. Setting bodyBg property in applyBackground method changes this single instance of panelConfig object. So we create p2 with blue background too.

You see, here it is clearly and immediately visible that something went wrong but making this error can lead to weeks of wasted debugging time in real applications. Imagine you have a store in prototype…

Hard Coding ids

Very simple, but deadly mistake is to set ids in the extension either to the main extension object or on its items, toolbars, buttons, etc. If a hard coded ids are set we cannot create two or more instances of our extension, can we?

Loose End

That’s all for now but if I discover more errors I will add them above.

Stay tuned!

Do not forget to read Part 1 and Part 2 of this article.

Follow up: Factory Functions in Ext Extensions (Abstract Classes)

Suppose we want to remove all children of the node node:

while(node.firstChild) {
    node.removeChild(node.firstChild);
}

That’s all there is to it

Important

If you have not already done so, study Writing a Big Application in Ext (Part 1) before you read this article. It would be very hard, if not impossible, to understand concepts explained here before you fully understand the first part.

Introduction

It has been almost one year since I have published the first part of this article. I have been successfully using the concept of pre-configured classes personally to write a really big application (~150 javascript files, ~60,000 lines of code, plus server-side and css). The application is fully modularized, each class in separate file and it has proven that it can be easily developed, managed and debugged.

Unfortunately, the same has not been always true for other users, they were hitting various problems and Ext Support Team have had to handle may questions and help requests. These accumulated to the degree where the concept has been called “absolute abomination” (read absolutely hated) and it was stated that “it causes problems”.

Note: As “fast cars” do not cause accidents but “slow drivers driving fast cars” do, the concept itself cannot be a cause of the problems but its application can.

In any case, there must be some illogic if I can use the concept but others cannot.

Thus, I have looked deeper in it and I have isolated some pitfalls the users can run into on the course of development. I will also write on “dos” and “don’ts” and on when to use a pre-configured class and when not. I will not compare this concept to another application design concepts (factory functions, in-line configuration, on-demand load, or other) because 1) I do not use them and 2) I do not want to turn this article into a Linux versus Windows discussion.

It is fully up to you which application design concept you choose. However, if you do choose this one then follow the rules I’m going to lay down.

Most Common Sources of Troubles

• Dull Copy&Paste
• Extending a non-Ext.Component class
• Not calling parent methods
• initialConfig
• listeners

Dull Copy&Paste

Do you know such people? They post on a forum:

I need to drag from tree to qrid, gimme plz complete codez

And if somebody altruistic writes a fragment of “codez” for him in a sheer attempt to help the response is going to be:

Your codez don’t work. Help me plz my manager wants it working

Do you see what happened? A dull “developer” ordered a code on the forum, he’s got some, copied&pasted it to his application without a clue what the code does, maybe hasn’t even changed url that still points to your server and the result is: it doesn’t work.

Well, this is an extreme (but not so rare as you would think), nevertheless, copying&pasting without understanding of what the copied&pasted code does can lead only to frustrations.

I am not against Copy&Paste in general, it can save a lot of time and I also occasionally do it, but I am against not-understanding or mis-understanding not only of coding but also of life.

The Rule: Do Copy&Paste but always with full understanding of what the code does.

Extending a non-Ext.Component class

If an Ext class does not inherit from Ext.Component the initComponent is never called so the code you have written there is never executed. This is fragment from Ext.Component constructor:

1
2
3
4
5
6
7
8
9

    this.getId();
    Ext.ComponentMgr.register(this);
    Ext.Component.superclass.constructor.call(this);
 
    if(this.baseAction){
        this.baseAction.addComponent(this);
    }
 
    this.initComponent();

Ext classes that do not inherit from Ext.Component do not have this.initComponent(); line in their constructors.

The Rule: Always check if the Ext class you are going to pre-configure inherits from Ext.Component. You have to use an another approach if it does not.

Not calling parent methods

It happens very often that you do not only add some methods in your extended class but that you modify existing ones. initComponent being the first example. onRender, afterLayout are other (but not only) frequently overriden methods.

These methods are already implemented in the class you are extending and its parents so if you forget the line:

// in initComponent override
YourExtension.superclass.initComponent.apply(this, arguments);
 
// or in onRender override
YourExtension.superclass.onRender.apply(this, arguments);
 
// or in afterLayout override
YourExtension.superclass.afterLayout.apply(this, arguments);

your class will not work.

The Rule: Never forget to call the parent method, unless you exactly know what you are doing.

initialConfig

The constructor of Ext.Component saves the config passed to it as initialConfig:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

    /**
     * This Component's initial configuration specification. Read-only.
     * @type Object
     * @property initialConfig
     */
    this.initialConfig = config;
 
    Ext.apply(this, config);
    this.addEvents(/* abbreviated for clarity */);
    this.getId();
    Ext.ComponentMgr.register(this);
    Ext.Component.superclass.constructor.call(this);
 
    if(this.baseAction){
        this.baseAction.addComponent(this);
    }
 
    this.initComponent();

You see what happens? The constructor saves initialConfig before initComponent is executed. Thus, all configuration you write in initComponent is not saved. I have overlooked this in first versions of my templates and examples mainly because there is only a couple of classes that refer to initialConfig and even in these classes the absence of properly saved initialConfig causes problems very rarely. These Ext classes refer to initialConfig:

• AnchorLayout
• BorderLayout
• Action
• GridPanel
• Tip
• Combo
• Form

Now, I have updated all my examples, extensions, templates and main site to include this “magic” pattern:

1
2
3
4
5
6
7
8
9
10

// create config
var config = {
    // put your config here
}; // eo config object
 
// apply config
Ext.apply(this, Ext.apply(this.initialConfig, config));
 
// call parent
YourExtension.superclass.initComponent.apply(this, arguments);

The Rule: Ensure that your extension saves initialConfig.

listeners

If you try to install event handlers by setting property listeners in your config they will not work. Why? The answer lies again in the order of actions in Ext.Component constructor:

1
2
3
4
5
6
7

    Ext.Component.superclass.constructor.call(this);
 
    if(this.baseAction){
        this.baseAction.addComponent(this);
    }
 
    this.initComponent();

As you can see, the constructor calls its parent, that is Ext.util.Observable before initComponent. Ext.util.Observable constructor executes:

1
2
3
4
5
6

Ext.util.Observable = function(){
    if(this.listeners){
        this.on(this.listeners);
        delete this.listeners;
    }
};

Any listeners set in initComponent are thus ignored.

There is an easy workaround. Put constructor method in your extension:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

 
 constructor:function(config) {
    // parent constructor call pre-processing - configure listeners here
    config = config || {};
    config.listeners = config.listeners || {};
    Ext.applyIf(config.listeners, {
        // add listeners config here
    });
 
    // call parent constructor
    AnExtension.superclass.constructor.call(this, config);
 
    // parent constructor call post-processing
 
} // eo function constructor

and define your listeners therein.

The Rule: Define listeners in constructor method.

Conclusion

If you decide to use my way of writing a big application then follow these rules:

1. Do Copy&Paste but always with full understanding of what the code does.
2. Always check if the Ext class you are going to pre-configure inherits from Ext.Component. You have to use an another approach if it does not.
3. Never forget to call the parent method, unless you exactly know what you are doing.
4. Ensure that your extension saves initialConfig.
5. Define listeners in constructor method.

Happy extending!

Do not forget to read Part 1 and Part 3 of this article.

We need to know all events that are fired by a component and in which order sometimes. It is easy to find out.

Let’s say that the component in question has id my-comp. Load the page with the component, open Firebug, Console tab, and type:

Ext.util.Observable.capture(Ext.getCmp('my-comp'), console.info)

Now do some actions with the component and watch the Firebug output.