Listeners в Ext.NET

В Ext.NET понимание разницы между различными типами событий и их обработчиками является очень важным. Выбор зависит от конкретного сценария, который вы хотите реализовать вашем приложении.
В данной серии из четырех статей мы рассмотрим различные события на клиенте и на сервере, как они вызываются, обрабатываются и какие имеют преимущества. В данной статье будут рассмотрены Listeners – позволяющие «слушать» события на клиенте и обрабатывать его там же, на клиенте, избегая запроса к серверу.
Все компоненты в Ext.NET, такие как Panel, Window, Button, имеют следующие четыре типа обработчиков событий:

Listeners	Слушают события на клиенте и обрабатывают их так же на стороне клиента.
DirectEvents	Слушают события на клиенте, но выполняют их обработку на стороне сервера, вызов происходит посредством AJAX запроса.
DirectMethods	Позволяют вызывать функции на сервере, например написанные на C# или VB, вызов происходит посредством AJAX запроса.
MessageBus	MessageBus позволяет передавать различные события между компонентами, которые могут друг о друге не знать. Обработка сообщений происходит через подписку на определенные сообщения и отправку сообщений о событиях через MessageBus. Каждый компонент на клиенте имеет специальный обработчик MessageBusListeners, а также  MessageBusDirectDirectEvents для передачи обработки на сторону  сервера.

Listeners

Listeners являются обработчиками событий на клиенте. Они выполняют ваш код после появления некоторого события, например, нажатия на кнопку (Button).
Использование Intellisense в Visual Studio дает возможность узнать какие конкретные события есть у каждого компонента. Каждый компонент наследует события от своего предка и обычно добавляет свои.
Все классы в Ext.NET наследуют события от базового класса Observable. Все события находятся в Listeners.

Все доступные события могут быть просмотрены с помощью Intellisense

Если компонент вызывает некоторое событие на клиенте, то для того чтобы ваш код на клиенте обработал данное событие вы должны подписаться на это событие добавив JavaScript функцию.

Настройка Listeners

Настройка Listeners может быть сделана как в разметке, так и в  Code-Behind. Например, чтобы обработать у некоторой кнопки (Button) событие «click» вы должны использовать поле Handlerу  Click, в данное поле нужно ввести ваш JavaScript код, который будет выполнен браузером при нажатии на данную кнопку.

// 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');"     ) ) 

Нажатие на кнопку вызывает окно 'Hello World'

Другое важное свойство у Listener это Fn.
Свойство Fn должно содержать название JavaScript функции или анонимную функцию (inline function):

// Вызываемая JavaScript функция, // размещается где-то на странице var doSomething = function () {     alert('Hello World'); };  // Вариант #1 // Свойству Fn присвоено имя JavaScript функции Fn="doSomething";   // Вариант #2 // Анонимная JavaScript функция Fn="function () { alert('Hello World'); }"  // Вариант #2b // Такая же функция, что и выше, но с аргументами Fn="function (item, e) { alert('Hello World'); }" 

JavaScript код, который объявляется в Handler, должен быть телом функции и при отображении на странице Ext.NET автоматически обернет его шаблоном функции, который соответствует данному событию.
Например:

<ext:Button runat="server" Text="Submit">     <Listeners>         <Click Handler="alert('Hello World');" />     </Listeners> </ext:Button> 

Ext.NET автоматически обернет данный код и отразит на странице следующим образом:

Ext.create("Ext.button.Button", {     text: "Submit",     listeners: {         click: function (item, e) {             alert('Hello World');         }     } }); 

Каждое событие имеет свой список аргументов, которые вы можете найти либо на справочном сайте Sencha Ext JS API documentation, либо изучив исходный код интересующего вас Listener (если у вас есть исходный код Ext.NET, то посмотреть все классы Listeners вы можете в директории <Ext.Net>\Events\Listeners).
Также на странице Ext.NET с примерами имеется специальный пример — Listeners Arguments Reflector, в котором можно просмотреть все сигнатуры функции любого события у любого компонента.

Описание сигнатуры события Click компонента Button

Например, событие Click компонента Button имеет два аргумента: item и e: item является ссылкой на саму сущность Button, e является объектом, хранящим информацию о событии.
Обработчик события Reconfigure у компонента GridPanel вызывается со следующими аргументами: item, store и columns.

Аргументы события Reconfigure компонента GridPanel

Если же вы используете свойство Fn, то вы должны сами добавить аргументы в функцию. Аргументы могут иметь произвольные имена, но порядок аргументов очень важен. Например, следующие две функции имеют разные имена аргументов, но работают абсолютно одинаково.

 var doSomething = function (item, e) {     alert(item.id); // Отобразит 'Button1' };  var doSomethingElse = function (cmp, ev) {     alert(cmp.id); // Отобразит 'Button2' };  <ext:Button ID="Button1" runat="server">     <Listeners>         <Click Fn="doSomething" />     </Listeners> </ext:Button>  <ext:Button ID="Button2" runat="server">     <Listeners>         <Click Fn="doSomethingElse" />     </Listeners> </ext:Button> 

У каждого Listener имеются следующие свойства:

AutoPostBack	Указывает, нужна ли автоматическая отправка состояние компонента на сервер. Идентично обычному полю в ASP.NET Control.	false
BroadcastOnBus	Указывает нужно ли отправлять событие в MessageBus (будет подробно объяснено в статьей посвященной MessageBus)	false
Buffer	Указывает количество миллисекунд, на которые будет отложена обработка события, если в течении этого времени данное событие появится еще раз, первоначальный обработчик будет заменен на новый. Например, для некоторого события (пусть будет ‘click’) данное поле равно значение равно 1000 и если за 1000 миллисекунд придет 10 таких событий (‘click’), то обработчик события вызовется только один раз,  для самого последнего события.	0
Delay	Указывает количество миллисекунд, на которые будет отложен вызов обработчика события.	0
Delegate	Фильтрует HTML-элемент, для которого может вызываться данное событие. Например, если вы присвоите этому свойству следующее значение: Delegate=<a>, то для события Click обработчик будет вызван только в том случае если вы нажмете именно на HTML-элемент ссылку <a> внутри HTML-разметки компонента.	""
PreventDefault	Если значением является True, то будет предотвращен вызов обработчика браузера по умолчанию. (Например, переход по ссылке)	false
Scope	Указывает контекст переменной this для функции обработчика события. Если значение не указано, то по умолчанию this указывает на объект, который вызвал данное событие.	this
Single	Если значением является True, то обработчик события будет вызван только один раз и автоматически будет удален после свеого первого и последнего вызова.	false
StopEvent	Если значением является True, то останавливает событие, что останавливает дальнейшую отправку события и предотвращает обработку браузером. Должно использоваться только для событий, которые обрабатываются браузером. (click, mousemove, keypress, и.т.д.)	false
StopPropagation	Если значением является True, то останавливает дальнейшую отправку события.	false

Использование серверных методов .On и .AddListener

Эти методы используются для того, чтобы добавить, обработчик (Listener) для некоторого события во время DirectEvent, уже после того как компонент уже был отображен в браузере (серверная обработка событий, будет рассмотрена в дальнейших статьях).
Эти методы позволяют добавить обработчики на стороне клиента к компонентам, которые уже отображены на странице, и обычно используются во время выполнения DirectEvent. В отличие от использования <Listeners>, метод On позволяет добавить несколько обработчиков на одно событие (один обработчик на каждый вызов метода On ).

Button1.On("click", new JFunction("alert('The button is clicked');", "button", "e"));

Аргументы можно опустить, если вы не используете их в обработчике.
Однако следует помнить, что если обработчик возвращает false, то другие обработчики не будут вызваны, так же обработчики событий DirectEvent тоже не будут вызваны.

Использование методов .on и .addListener на стороне клиента

Если вы хотите добавить обработчик события, используя JavaScript, вы можете вызвать функцию on для некоторой сущности компонента:

Button1.on(     "click",      function (button, e) {         alert('The button is clicked');     } ); 

Дополнительную информацию и примеры использования вы можете найти на  этой справочной странице.
Также вы можете вызвать событие вручную с помощью JavaScript функции fireEvent. Вы должны передать название события первым аргументом и далее перечислить список аргументов. Следующий пример, показывает вызов функции fireEvent:

// Это вызовет все обработчики события 'click'  App.Button1.fireEvent('click', App.Button1);  

Следует помнить, что серверные обработчики событий (DirectEvents) также могут быть вызваны с помощью функции fireEvent (Серверные обработчики (DirectEvent) вызываются после клиентских (Listeners), однако эту последовательность можно изменить, используя свойство Delay).
Вызов серверного обработчика (DirectEvent) может быть отменен, если любой обработчик (без установленного свойства Delay) вернет false. Более подробную информацию вы можете прочитать на справочной странице метода fireEvent.

Заключение

В этой части статьи мы рассмотрели Listeners, которые являются обработчиками событий на стороне клиента. Они дают возможность быстро обработать события на стороне клиента и избежать лишнего взаимодействия с сервером.
В следующей статье будут описаны серверные обработчики событий – DirectEvents.