New to Telerik UI for ASP.NET Core? Download free 30-day trial

Methods and Events

The client objects of the Telerik UI for ASP.NET Core helpers provide methods and events that you can use to query or modify their state at runtime.

Using Methods

To use the methods of the helpers, you have to obtain a reference to the specific helper instance through any of the following approaches:

The jQuery data Method

To get a reference to a helper instance, use the jQuery data method and pass the plugin name as a string (the Kendo UI widgets wrapped by Telerik UI for ASP.NET Core are jQuery plugins).

    @(Html.Kendo().AutoComplete()
        .Name("animals")
        .BindTo(new string[] {
              "Ant",
              "Antilope",
              "Badger"
        })
    )

    @addTagHelper *, Kendo.Mvc

    @{
        var animals_data = new List<string>() { "Ant", "Antilope", "Badger" };
    }

    <kendo-autocomplete name="animals" bind-to="animals_data">
    </kendo-autocomplete>
    $(document).ready(function () {
        // Retrieve the helper instance.
        var autoCompleteWidget = $("#animals").data("kendoAutoComplete");
        console.log(autoCompleteWidget);
    });

The getKendo Method

To get a reference to a helper instance, you may also use the getKendo<WidgetName> method.

    @(Html.Kendo().AutoComplete()
        .Name("animals")
        .BindTo(new string[] {
              "Ant",
              "Antilope",
              "Badger"
        })
    )

    @addTagHelper *, Kendo.Mvc

    @{
        var animals_data = new List<string>() { "Ant", "Antilope", "Badger" };
    }

    <kendo-autocomplete name="animals" bind-to="animals_data">
    </kendo-autocomplete>
    $(document).ready(function () {
        // Retrieve the helper instance.
        var autoCompleteWidget = $("#animals").getKendoAutoComplete();
        console.log(autoCompleteWidget);
    });

The JavaScript Method Syntax

After the helper instance is available, you can call its methods by using the standard JavaScript method syntax. The complete list and examples of the widget methods and method parameters is available in the API reference section. If the code which will return a helper instance returns undefined, then the helper is not yet initialized. Such a problem may occur, for example, if an instance is referenced from code that was executed earlier than the document.ready handler.

    @(Html.Kendo().AutoComplete()
        .Name("animals")
        .BindTo(new string[] {
              "Ant",
              "Antilope",
              "Badger"
        })
    )

    @addTagHelper *, Kendo.Mvc

    @{
        var animals_data = new List<string>() { "Ant", "Antilope", "Badger" };
    }

    <kendo-autocomplete name="animals" bind-to="animals_data">
    </kendo-autocomplete>
    $(document).ready(function () {
        // Retrieve the helper instance when it is available.
        var autoCompleteWidget = $("#animals").data("kendoAutoComplete");
        // Focus the AutoComplete.
        autoCompleteWidget.focus();
    });

Handling Widget Events

Depending on its specific features, each component exposes different events. For example, the AutoComplete helper triggers Change, Close, DataBound, and so on. You can pass event handlers either during the helper initialization or after the helper initialization. When you work with the events of the Telerik UI for ASP.NET Core helpers, you can also use event handler arguments, prevent events, and unbind from events.

Binding Events during Initialization

Event handlers which are attached during the initialization of the helper will be executed every time the event is fired.

    @(Html.Kendo().AutoComplete()
        .Name("animals")
        .BindTo(new string[] {
              "Ant",
              "Antilope",
              "Badger"
        })
        .Events(e =>
        {
            e.Change("onChange");
        })
    )

    @addTagHelper *, Kendo.Mvc

    @{
        var animals_data = new List<string>() { "Ant", "Antilope", "Badger" };
    }

    <kendo-autocomplete name="animals" bind-to="animals_data" on-change="onChange">
    </kendo-autocomplete>
    function onChange(e) {
        console.log("change event handler");
    }

Binding Events after Initialization

All helpers provide the bind and the one method. Both methods attach event handlers to already existing helper instances but the event handlers that are attached with one will be executed only once.

    @(Html.Kendo().AutoComplete()
        .Name("animals")
        .BindTo(new string[] {
              "Ant",
              "Antilope",
              "Badger"
        })
    )

    @addTagHelper *, Kendo.Mvc

    @{
        var animals_data = new List<string>() { "Ant", "Antilope", "Badger" };
    }

    <kendo-autocomplete name="animals" bind-to="animals_data">
    </kendo-autocomplete>
    $(document).ready(function () {

        var autoCompleteWidget = $("#animals").data("kendoAutoComplete");

        // Attach an event handler that will be executed each time the event is fired.
        autoCompleteWidget.bind("change", function(e) {
            console.log("change event handler");
        });

        // Attach an event handler that will be executed only the first time the event is fired.
        autoCompleteWidget.one("open", function(e) {
            console.log("open event handler");
        });
    });

Using Event Handler Arguments

Each helper passes a single argument to the event handler—the so-called "event object". Usually, it has one or more fields which contain specific information for the event. All event objects have a sender field which provides a reference to the helper instance that triggered the event. Passing additional custom event arguments to the handler is not supported. The full list and examples of the widget events and the fields in the event objects is available in the API reference section.

    @(Html.Kendo().AutoComplete()
        .Name("animals")
        .BindTo(new string[] {
              "Ant",
              "Antilope",
              "Badger"
        })
        .Events(e =>
        {
            e.Change("onChange");
        })
    )

    @addTagHelper *, Kendo.Mvc

    @{
        var animals_data = new List<string>() { "Ant", "Antilope", "Badger" };
    }

    <kendo-autocomplete name="animals" bind-to="animals_data" on-change="onChange">
    </kendo-autocomplete>
    function onChange(e) {
        var autoCompleteWidget = e.sender;
    }

Preventing Events

Certain helper events can be prevented by calling the preventDefault method of the event object. The effect of the event prevention is specific for each event and is documented in the API reference.

    @(Html.Kendo().AutoComplete()
        .Name("animals")
        .BindTo(new string[] {
              "Ant",
              "Antilope",
              "Badger"
        })
        .Events(e =>
        {
            e.Open("onOpen");
        })
    )

    @addTagHelper *, Kendo.Mvc

    @{
        var animals_data = new List<string>() { "Ant", "Antilope", "Badger" };
    }

    <kendo-autocomplete name="animals" bind-to="animals_data" on-open="onOpen">
    </kendo-autocomplete>
    function onOpen(e) {
        e.preventDefault();
    }

Unbinding from Events

To unbind from a specific event, keep a reference to the event handler function and invoke the unbind method with it. Note that calling the unbind method without any argument unbinds all event handlers from the event.

    <button id="unbindButton">Unbind event</button>

    @(Html.Kendo().AutoComplete()
        .Name("animals")
        .BindTo(new string[] {
            "Ant",
            "Antilope",
            "Badger"
        })
    )

    @addTagHelper *, Kendo.Mvc

    @{
        var animals_data = new List<string>() { "Ant", "Antilope", "Badger" };
    }

    <kendo-autocomplete name="animals" bind-to="animals_data">
    </kendo-autocomplete>
    $(document).ready(function () {

        var handler = function (e) { console.log(e); };

        var autoCompleteWidget = $("#animals").data("kendoAutoComplete");

        autoCompleteWidget.bind("open", handler);

        $("#unbindButton").on("click", function () {
            autoCompleteWidget.unbind("open", handler);
        });
    });

Known Limitations

Telerik UI for ASP.NET Core does not fire an event when the corresponding API method is invoked. For example, the Select event of the PanelBar helper is not fired if you call the select method through the API.

See Also

In this article