Client-Side Events

  • 4 min to read

DevExpress ASP.NET controls provide an advanced client-side API that increases web application efficiency via a combination of server-side and client-side processing. Client-side events allow you to perform web application logic on the client in response to end-user manipulations of a control.

Client-Side Events Editor (for WebForms only)

Use the Client-Side Events editor (available in the control’s Designer, as shown below) to write a client-side event handler. The editor displays a list of available client-side events, and allows you to write an event handler implementation within it. The editor automatically adds the code to the markup.

ClientSideAPI_EventsEditor

A control’s Designer can be launched in the following ways.

  • Click the control's Smart Tag and select Designer... from the invoked drop down list.

    ClientSideAPI_SmartTag_1

  • Right-click the control and choose Designer... in the invoked context menu.

    ClientSideAPI_SmartTag_2

  • Select the control, open its Properties window, and select Designer... within the Command Panel.

    ClientSideAPI_SmartTag_3

  • Select the control, open its Properties window, and click the ClientSideEvents property's ellipsis button (shown below) or a client-side event’s ellipsis.

    ClientSideAPI_SmartTag_4

To create an event handler, choose the required event on the left, and write the event handler implementation on the right. Note that the Designer automatically generates a default event handler signature within the Event Handler Body pane.

ClientSideAPI_EventsEditorText

Click OK to automatically add the corresponding aspx code to the markup.

<dx:ASPxButton ID="ASPxButton1" runat="server" Text="ASPxButton" AutoPostBack="False">
     <ClientSideEvents Click="function(s, e) {
          alert('The Click event has been invoked');
     }" />
</dx:ASPxButton>

Note that you can also write similar code to create an event handler directly in an aspx file.

Client-side event handler signature

A client-side event handler signature is similar to the standard server-side version. The default signature is illustrated below.

<ClientSideEvents EventName="function(s, e) { ... }" />

An event handler function has two parameters:

- the s parameter represents the client object that raises the event;

- the e parameter represents the event argument, which typically contains event-specific information.

Note that using the s object to access an event source within an event handler is preferable to using the ClientInstanceName property.

<dx:ASPxGridView ClientInstanceName="grid" ... >
    <ClientSideEvents RowDblClick="function(s, e) {
        //grid.StartEditRow(e.visibleIndex);
        s.StartEditRow(e.visibleIndex);
    }" />
    ...
</dx:ASPxGridView>

Ways of assigning an event handler

For each client-side event that you handle, you must specify a JavaScript function to be executed when the event is triggered. Functions can be assigned in the following ways.

Note

Register Javascript functions at the top of the page. In this case, the browser executes these scripts before it renders DevExpress ASP.NET components.

  • Write an event handler implementation via the Client-Side Events Editor or directly in the markup.

    <ClientSideEvents Click="function(s, e) {
         alert('The button has been clicked');
    }" />
    
  • Assign an external function to the event handler.

    <ClientSideEvents Click="OnMyButtonClick" />
    
    function OnMyButtonClick (s, e) {
         alert('The ' + s.name + ' button has been clicked');
    }
    
  • Use the ASPxClientEvent.AddHandler, ASPxClientEvent.RemoveHandler and ASPxClientEvent.ClearHandlers client-side methods to manually manipulate event handlers (assign or remove them) on the client-side.

    function AddKeyboardNavigationTo(grid) {
        grid.BeginCallback.AddHandler(function(s, e) { alert('A callback begins') });
        grid.EndCallback.AddHandler(function(s, e) { alert('A callback ends') });
    }
    
  • Use the ClientSideEvents property, which lists the names of available client control events and provides the ability to assign an appropriate JavaScript handler function to the corresponding client-side event.

    MyMenu.ClientSideEvents.ItemClick = "function(s, e) { alert(s.name); }";
    MyMenu.ClientSideEvents.Init = "MyFunction";
    
  • Use the ClientSideEventsBase.SetEventHandler server-side method to define a handler for the specified DevExpress client event.

    MyMenu.ClientSideEvents.SetEventHandler("ItemClick", "function(s, e) { alert(s.name); }");
    MyMenu.ClientSideEvents.SetEventHandler("Init", "MyFunction");
    
  • Use the ASPxClientUtils.AttachEventToElement / ASPxClientUtils.DetachEventFromElement client-side method to bind / unbind the specified function to or from a specific DOM element's event. (For DOM Events only.)

    Note that the event's name does not contain the "on" prefix.

    <ClientSideEvents Init="MyOnInit" />
    
    function MyOnInit(s, e) {
         ASPxClientUtils.AttachEventToElement(s.GetMainElement(), "dblclick", function (event) {
              //code here
         });
    };
    
See Also