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:

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’);"
    )
) 

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:

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.