February 10, 2008

All about Ext.Button!

I have already demonstrated the difference of ExtJS1.x and 2.0 with a simple "Hello World" program. Now let’s get deeper and this time it’s about buttons in ExtJS. In this article we will cover creating, handling and manhandling of Ext buttons.

Setting up your programming environment:

There isn’t much to this. If you do not have ExtJS 2.0, you need to download the latest version. All you have to do is unzip the downloaded file, place them in a proper folder structure. I usually have a folder structure as shown:



The js folder has all the JavaScript of the application. Inside this folder I have separate folders for different libraries and I store my custom JavaScript files in appjs. Again this appjs can have subfolders to separate JavaScript files module-wise. This might not be the best folder structure but for now we will stick to this. If you are new to Ext you can have a look at my "Hello World" program.

Ok! Now we are ready for some action. Let’s start with creating a simple button.

Creating a Button:

Ext has Button class implement in the base package ie, Ext. To create a button all you have to do is create an instance of this class and specify the attributes. The Button class has a parameterized constructor with one parameter, the button’s configuration!
Here is the code to create a simple button:
buttonObject = new Ext.Button({applyTo:'button-div',text:'Simple Button'});
You will see that we have used two configuration parameters. applyTo is used to specify which HTML element is going to become the button. The HTML element can be DIV, P or SPAN tag. Remember that applyTo should be passed for the button to render. The next parameter is the text of the button itself. Now another way to specify the holding element for button can be done my calling the public method applyToMarkup. The method takes a parameter which is the id of HTML element to which the button will be rendered.

Attaching handlers to button:


There are basically three ways to attach event to the button you created. One is to use the constructor to specify a callback when the button is clicked and the other is to use addListner method. This method is more generic because you can specify action for any type of events on a button.

The first method is by using the constructor you specify the call back function that needs to invoke when the button is clicked. Remember: It’s only for handling button clicks. Have a look at the example below:
buttonObject = new Ext.Button({applyTo:'button-div',text:'Testing',handler:buttonHandler});
buttonHandler is a method defined in our application class as private method. Here is the complete application code:
app = function() {

var buttonObject;

var buttonHandler = function(button,event) {
alert('You clicked the button!');
};

return {

init:function() {
buttonObject = new Ext.Button({applyTo:'button-div',         text:'Testing',
handler:buttonHandler});

} 
};
}();
The second method is to use the setHandler method to set the call back method for click event. The method has only one argument and it’s the call back method.

The third method to attach an action is to use the public method addListener. Through this you will be able to define actions for events like clicking, mouse over, mouse out etc. Take a look at this example
buttonNext = new Ext.Button({text:'Touch me'});
buttonNext.applyToMarkup('nxt-button');
buttonNext.addListener('mouseover',mouseHandler);
The addListener method has four parameters out of which last two are optional. Thus in our above example, we have made use of just the feature of assigning action to certain events. The third argument specifies the scope in which the handler method should be executed and the last argument specifies the object containing handler configuration properties. These properties can be scope, delay etc.

Before we close, there is one more way to attach event handler to button. This can be done by calling on method. This method has the same number of parameters as the addListener method.


Firing and removing handlers:


ExtJS provides a good set of APIs to manipulate events and actions for any component. As its possible for developers to create and attach actions for button, its also possible to manually fire, stop and remove these event and action.

Situations arise wherein you need to fire an event or series of events when one components event is fired. To fire an event manually we have fireEvent method.
This method has variable length argument of which the first argument is the event name that needs to be fired and the rest is the parameters passed to the handler if any.Have a look at the example below:
app = function() {

var buttonObject;
var buttonNext;

var buttonHandler = function(button,event) {
alert('You clicked the button!');
buttonNext.fireEvent('mouseover');
};

var mouseHandler = function(button,event) {
alert('Mouse on me!');
};

return {
init:function() {
buttonObject = new Ext.Button({applyTo:'button-div',
text:'Click me',
handler:buttonHandler});

buttonNext = new Ext.Button({text:'Touch me'});
buttonNext.applyToMarkup('nxt-button');
buttonNext.addListener('mouseover',mouseHandler);
} 
};
}();
Here we manually fire the ‘mouseover’ event for buttonNext when user clicks on the first button. Thus inturn, the mouseHandler of buttonNext is called.

Now, let’s remove handlers attached to the buttons. ExtJS provides two methods to remove a specific handler from an event. Developer as either use removeListener or un method (addListener and on for adding). And finally to remove all the handlers attached, you may call purgeListeners method.

Suspending and Resuming Events:

Adding, firing and removing is not all that. At times you may need to suspend the events so that the handlers are not fired. You can use suspendEvents and resumeEvents method to enable and disable the event firing for a component. For example:
buttonNext.suspendEvents();
This would suspend all event fired by buttonNext object.

Other Methods:


I am not explaining each function explicitly. But I am just covering the major once that a developer needs to know. For complete list of methods refer the Ext API Documentation.

Winding Up:

For a Ext beginner, I hope this will greatly helpful. Please let me know of any mistakes in this tutorial. You can download the final source code from here.

Read other articles and tutorials on ExtJS!

1 comment :

Fluid Foundation said...

You sir, are a king among men. Thanks for the explanation.