Version

Using Events in Ignite UI

Topic Overview

Purpose

This topic demonstrates how to handle events raised by Ignite UI™ controls. Also included is an explanation of the differences between binding events on initialization and after initialization.

In this topic

This topic contains the following sections:

Requirements

General requirements

  • jQuery-specific requirements
  • An HTML web page where Ignite UI controls are instantiated.
  • MVC-specific requirements
  • An MVC project in Microsoft Visual Studio® with an igGrid bound to a data source
  • A reference to the Infragistics.Web.Mvc.dll (contains the ASP.NET MVC wrappers)

Note: Calling API methods programmatically does not raise events related to their operation; those events are only raised by their respective user interaction..

Scripting requirements

  • The required scripts for both jQuery and MVC approach are the same because the MVC wrappers render similar JavaScript as the jQuery widget. You will need:
    1. The jQuery core library script
    2. The jQuery UI library
    3. The required Ignite UI script files for the widgets used on your page

The following code demonstrates the scripts as added to the HTML document.

In HTML:

<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="jquery-ui.js"></script>
<script type="text/javascript" src="infragistics.core.js"></script>
<script type="text/javascript" src="infragistics.lob.js"></script>
<script type="text/javascript" src="infragistics.dv.js"></script>

Binding to events

There are two main ways to bind to grid events

Binding to events on initialization

When binding to events on initialization of the widget you subscribe to the event using an option which takes the form of: eventName:<handler>. In the following example, the event handler function is implemented inline, but you can also assign the event handler to the name of a function to implement the handler outside of the control initialization.

Examples

igGrid

In the following example, the igGrid control is instantiated with the Hiding feature enabled and an event handler specified for the columnHiding event.

Code:

In Javascript:

<script type="text/javascript">
$("#grid1").igGrid({
    features: [
    {
        name: 'Hiding',
              columnHiding: function (e, args) {
              // Handle event  
       }]
});
</script>

igCombo

The following example shows how to handle the selectionChanging event of the igCombo control.

Code:

In Javascript:

<script type="text/javascript">
     $(function () {
          $("#comboTarget").igCombo({
                           selectionChanging: function (e, args) {
                           // Handle event  
                           }
          });
      });
</script>

igTextEditor

The following example shows how to instantiate a text editor and bind to its valueChanged event.

Code:

In Javascript:

<script type="text/javascript">
$('#editorContainer').igTextEditor({
    width: 200, 
    valueChanged: function(e, args){
        //Handle event
    }
})
</script>

Binding to events after initialization

Overview

There are a number of different approaches which are provided by jQuery for handling events. Depending on your situation, you may choose to use the bind(), live(), delegate() or on() functions to wire event handlers to a widget's events.

The following table discusses the details of each function:

  • bind: Attaches an event handler to existing DOM elements that match a given selector.

  • live: Attaches an event handler to existing and any new DOM elements that match a given selector. Event handlers do not propagate up the DOM tree.

  • delegate: Attaches an event handler to existing and any new DOM elements that match a given selector. Event handlers do propagate up the DOM tree.

  • on: Attaches an event handler to existing and any new DOM elements that match a given selector. (The delegate function is obsolete in jQuery version 1.7, making on the preferred approach for establishing event handlers.)

When using bind(), keep in mind that it attaches the specified handler only on the currently available elements, which means dynamically added items (after the DOM is loaded) aren't included in the event handler assignments. The delegate() function is a newer version of live() and it has improved performance over live().

Note: As of jQuery 1.7, the live() method is deprecated and as of jQuery 3.0 the delegate() and bind() methods are also deprecated. These methods were superseded by the on() and one() functions as preferred replacements.

When using any of the prescribed jQuery event wiring functions make sure to adhere to the jQuery UI event naming conventions. For instance the jQuery UI widget factory adds the name of the widget as a prefix of the event name. Therefore if want to attach to the “columnhiding” event of the “iggridhiding” widget, the event name becomes, “iggridhidingcolumnhiding”.

Note: The Ignite UI API documentation includes a full list of each control's available options, methods and events.

Note: When using the igEditor controls with the ASP.NET MVC wrapper, the wrapper always instantiates the igEditor control with its type option set according to the widget you want to instantiate. When using live, bind or delegate you must pass – “igeditor” + “eventName”

In the following examples there are separate sections each for the bind and unbind of an event.

Examples

igGrid

  • Bind:

    The following code instantiates an igGrid control, enables auto-generation of columns and binds to a data source.

    Code:

    Instantiate igGrid in MVC

    In HTML:

      @(Html.Infragistics().Grid(Model). ID("grid1")
          .AutoGenerateColumns(true)
          .Features(feature =>{
              feature.Hiding());
              }).DataBind()
          .Render()
      )
    

    Next, the existing grid instance is updated to include an event handler for the columnHiding event which points to a separate function that implements the handler.

    In Javascript:

      $("#grid1").live("iggridhidingcolumnhiding", gridColumnHiding);
    

    The following is a stub for the event handler function.

    In Javascript:

      <script type="text/javascript">        
          function gridColumnHiding (evt, ui) {
              // Handle event        
           };   
      </script>
    
  • Unbind:

    Introduction

    This snippet shows how to unsubscribe from an established event subscription. For the purpose of the following code snippet, reuse the code above to attach to the columnHiding event and then use the die function to disassociate the event handler.

    Note: If you need and event handler invoked only once, the best way to do that is to use one() function which unsubscribes the event handler after the first time the event is invoked.

    Code:

    In Javascript:

      <script type="text/javascript">        
          $("#grid1").die("iggridhidingcolumnhiding");
      </script>
    

igCombo

  • Bind

    In the code below we’ll attach to selectionChanging event of the igCombo

    Code:

    In HTML:

      @(Html.
          Infragistics().
          Combo().
          ID("comboProducts").
          Width("150px").
          DataSource(new List<string>() 
              { "Item1", "Item2", "Item3" }).
          SelectedIndexes(new int[] { 0 }).
          DataBind().
          Render()
      )
    

    JavaScript:

      $("#comboProducts").live('igcomboselectionchanging', function (e, args) {
          // Handle event
      });
    
  • Unbind:

    This code snippet demonstrates how to unsubscribe from event already attached using the approach from the sample above.

    Code:

    JavaScript:

      $("#comboProducts").die('igcomboselectionchanging');
    

igTextEditor

  • Bind:

    Introduction

    This sample igTextEditor is instantiated in a MVC context and is bound to the valueChanged event. When using ASP.NET MVC helpers to instantiate controls which inherit from the igEditor control, the render method generates an igEditor control with the appropriate type value to configure the right editor. Therefore, when binding or unbinding to an event the “igeditor” prefix is required.

    Code:

    Instantiate igTextEditor

    In HTML:

      @(Html.Infragistics().TextEditor()
            .ID("textEditor")
            .Width(150)
            .Render()
      )
    

    Bind to selectionChanged event

    JavaScript:

      $("#textEditor").live('igedtorvaluechanged', function (e, args) {
          // Handle event
      });
    
  • Unbind:

    The following code shows demonstrates how to unsubscribe from an event already attached using the approach from the sample above.

    Code:

    JavaScript:

      $("#textEditor").die('igedtorvaluechanged');
    

Related Topics

Related Samples

View on GitHub