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.

All Listeners available on the component can be viewed using Intellisense
All Listeners available on the component can be viewed using Intellisense

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’);"
    )
) 
Clicking the Button will cause a JavaScript alert to be raised with the message 'Hello World'.
Clicking the Button will cause a JavaScript alert
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.

Button Click Listener arguments
Button Click Listener arguments

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.

GridPanel Reconfigure Listener arguments
GridPanel Reconfigure Listener arguments

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’
};

&nbsp;
 

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.

10 Comments

  1. alon

    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.

  2. Meodudang

    … (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?

  3. joyefox

    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

Leave a Reply

Your email address will not be published. Required fields are marked *