Introduction to Ext.NET Events
Listeners, DirectEvents, DirectMethods and MessageBus
Understanding the differences between Ext.NET event types and when to choose a certain type is an important concept to learn. Your project requirements will help determine which event type to use given a particular scenario.
In this series of four articles on the subject we will discuss client side and server side events, how they are triggered, how to handle each, and potential use cases for each.
This first post will investigate usage of client side Listeners.
All Ext.NET components, such as Panel, Window and Button, enable four types of events handlers:
Type | Description |
---|---|
Listeners | Client side handlers of client side events |
DirectEvents | Server side event handlers of client side events using AJAX. |
DirectMethods | Call a server side Method (such as C# or VB) from client side JavaScript using AJAX. |
MessageBus | The MessageBus allows loosing of coupling of component events because events can publish or subscribe to events without knowing about each other. Each component has MessageBusListeners (client side handlers of MessageBus client side events) and MessageBusDirectEvents (server side handlers of MessageBus client side events). |
Listeners
Listeners are event handlers for client side triggered events. The Listener event handler will execute JavaScript code you provided after the action is triggered, such as a clicking a Button
.
Using Visual Studio Intellisense is a great way to discover which events are available on the component. Each component inherits events from its super class and will typically extend with more events unique to that component.
All classes in Ext.NET inheriting from the Observable class trigger events. All client side events are defined inside the <Listeners>
property.

If a component fires a Listener event (client side), in order to handle that event (run custom logic) you must first subscribe to the event by adding a JavaScript function. Subscribing to an event can be accomplished by the following ways:
Listeners Configuration
The Listeners property is configured on the component in markup or code-behind. To handle the ‘click’ event of a Button you configure the Click
Listener by setting the Handler
property with some JavaScript. The JavaScript within the Handler
will be executed in the browser when the Button is clicked.
// C#
Button1.Listeners.Click.Handler = "alert(‘Hello World’);";
// ASPX
<ext:Button runat="server" Text="Submit">
<Listeners>
<Click Handler="alert(‘Hello World’);" />
</Listeners>
</ext:Button>
// Razor (ASP.NET MVC)
@(Html.X().Button()
.Listeners(ev =>
ev.Click.Handler = "alert(‘Hello World’);"
)
)

to be raised with the message ‘Hello World’.
Another important Listener property is Fn
.
The Fn
property is set with a JavaScript function name or inline function. Here are examples of valid Fn
values:
// A JavaScript function is defined
// somewhere on the page.
var doSomething = function () {
alert(‘Hello World’);
};
// Option #1
// .Fn property is set with the JavaScript function name
Fn="doSomething";
// Option #2
// An inline JavaScript function definition
Fn="function () { alert(‘Hello World’); }"
// Option #2b
// Same function as above, but with named arguments
Fn="function (item, e) { alert(‘Hello World’); }"
The Handler
property is set with only the body of the JavaScript function. This code is automatically wrapped in a proper JavaScript function template.
For example, if you set:
<ext:Button runat="server" Text="Submit">
<Listeners>
<Click Handler="alert(‘Hello World’);" />
</Listeners>
</ext:Button>
Ext.NET will convert the above to the following when rendered to the page.
Ext.create("Ext.button.Button", {
text: "Submit",
listeners: {
click: function (item, e) {
alert(‘Hello World’);
}
}
});
Each event has its own list of arguments. You can find arguments in the Sencha Ext JS client side API documentation or reviewing the Ext.NET source code of the Listeners class (all listeners classes are located in the <Ext.Net>EventsListeners
folder).
There’s also a handy sample in the Examples Explorer for listing all Listeners related to a component and showing their event signatures, see Listeners Arguments Reflector.

The Button Click Listener has two arguments: item
and e
. The item
will be an instance of the Button component. The e
is an instance of the event object.
The Reconfigure listener of the GridPanel is called with the following arguments: item
, store
and columns
.

If you set the Fn
property, you must add the required function arguments manually. The arguments can be given different names, but the order is important. For example, the following two functions use different function argument names (item
vs cmp
), but each will work exactly the same.
var doSomething = function (item, e) {
alert(item.id); // alerts ‘Button1’
};
var doSomethingElse = function (cmp, ev) {
alert(cmp.id); // alerts ‘Button2’
};
Every Listener includes the following properties:
Name | Description | Default Value |
---|---|---|
AutoPostBack | Initiate a hard postback of the page. Same as a classic ASP.NET Control. | false |
BroadcastOnBus | Broadcast the event on the MessageBus (will be explained in MessageBus tutorial) |
false |
Buffer | Causes the handler to be scheduled to run delayed by the specified number of milliseconds. If the event fires again within that time, the original handler is not invoked, but the new handler is scheduled in its place. | 0 |
Delay | The number of milliseconds to delay the invocation of the handler after the event fires. | 0 |
Delegate | A simple selector to filter the target or look for a descendant of the target. If you set Delegate=”a” for Click event then the event handler will be executed only if you click on anchor tag inside target component. |
"" |
PreventDefault | True to prevent the browsers default handling of the event. | false |
Scope | The scope in which to execute the handler function. The handler function’s this context. If omitted, defaults to the object which fired the event. |
this |
Single | True to add a handler to handle just the next firing of the event, and then remove itself (handler will be executed once only). | false |
StopEvent | True to stop the event. That is stop propagation, and prevents the browsers default action. It should be used with browser native events only (like click, mousemove, keypress, etc). | false |
StopPropagation | True to prevent event propagation. | false |
Using .On and .AddListener server side Methods
These methods should be used to add a Listener to a component during a DirectEvent, after the component has been rendered in the browser.
The methods allow adding of client side handlers after a component has been created and are typically used during a DirectEvent. Unlike using the <Listeners>
, the On
Method allows to add several handlers for one event (one handler for each On
call).
Button1.On("click", new JFunction("alert(‘The button is clicked’);", "button", "e"));
Arguments can be omitted if you don’t use it in the handler.
Please note that if the handler returns false
then other handlers will not be executed (returning false
cancels the event handling), DirectEvent handlers for this event will not be executed also.
Using .on or .addListener client side methods
If you need to add an event handler using client side JavaScript, you can call the on
function on the client side instance of a component.
Button1.on(
"click",
function (button, e) {
alert(‘The button is clicked’);
}
);
Additional tips and tutorials can be found in the client side API documentation.
You can also trigger an event to fire manually in JavaScript by calling the fireEvent
JavaScript function. You must pass the name of the event as the first argument. The following sample demonstrates calling the fireEvent
function:
// this will cause all ‘click’ Listeners
// on the Button to fire.
App.Button1.fireEvent(‘click’, App.Button1);
Please note that DirectEvents can also be initiated by calling the fireEvent
function (DirectEvents are executed after Listeners, but the sequence can change by using Delay
property of the Listener).
A DirectEvent can be canceled if any Listener (without a Delay
set) returns false
. Please see fireEvent
client side documentation.
Summary
In this part of the article we considered Listeners – client side handlers of client side events. Listeners allow us to handle events in the client browser with instant feedback upon user actions and without server interaction.
DirectEvents will be explored in the next tutorial.
hi vladimir,
Ext.net is raising hand to developers, who seeking for good Js tool + live blogs + books and docs.
Thanks.
still wait for full support of RTL.
Great tutorial, can’t wait for the next installment.
please do any toturials about full CRUD.
Great article. I like the simple but detailed examples. Looking forward to the DirectMethod explanation.
… (DirectEvents are executed after Listeners, but the sequence can change by using Delay property of the Listener) …
With the Buffer property Configuration, DirectEvents are also executed after Listeners, is it true?
Yes, generally speaking, Buffer behaves as a Delay.
Thank @Vladimir … i’ll be waiting for the next publish!.
Thanks for this tutorial!!
RTL support has been added to Ext.NET. Currently, in SVN only. The following example is built into Ext.NET as well.
http://docs.sencha.com/ext-js/4-2/#!/example/rtl/rtl.html
It will be also available with the upcoming v2.2.0 release.
Nice post! When are you going to publish next steps? MessageBus is a great feature and it’ll be nice to have a tutorial about it.
Regards
Matteo