Actions

A typical application allows end users to create, read, update, or delete items, search or apply filters, navigate between views, and so on. These activities are initiated by the end user interacting with UI elements on the screen (for example, by touching a button or a list item). To perform these activities, bind actions to the events that the UI elements can raise. An action defines some work that should be done. For example, an action that specifies that a particular view should be displayed can be bound to a button's click event, with the result that clicking the button will cause the view to be rendered.

The following list details where actions are supported.

  • Commands

    When defining a command, associate it with an action using the action markup option. The associated action will be performed when executing the command.

  • Widgets

    Widget configuration objects expose options that represent actions (clickAction, updateAction, etc.). The actions that are assigned to these options will be performed when an associated event (click, update, etc.) occurs.

  • dxAction Binding

    An HTML element can be associated with an action via dxAction binding. The action is performed when clicking the bound HTML element.

Action as a Function

An action can be defined as a function. When such an action is executed, an object is passed as a parameter to this function. The set of fields contained in the parameter object depends on where the action is executed. The basic set includes the following fields.

  • component (available for widget actions and commands)
    Returns a component called the action.
  • element (always available) Returns an html element representing the component called the action.
  • jQueryEvent (always available)
    Returns the jQuery event that caused the action's execution.
  • model (always available)
    If the component was created using the Knockout approach, the field contains the component data model; if the jQuery approach was used, the field value is undefined.

See the following examples.

HTML
<div data-options="dxView: { name: 'home', title: 'Home' }">
    <!-- associate with a command -->
    <div data-bind="dxCommand: { id: 'myCommand', title: 'Say Hello', location: 'create', action: function() { alert('Hello world'); }}"></div>

    <!-- associate with a widget -->
    <div data-bind="dxButton: { text: 'Say Hello', clickAction: function() { alert('Hello world'); } }"></div>

    <!-- associate with an HTML element -->
    <div data-bind="dxAction: function() { alert('Hello world'); }">Say Hello</div>
</div>

The function can be defined in the ViewModel.

HTML
<div data-options="dxView: { name: 'home', title: 'Home' }">
    <!-- associate with a command -->
    <div data-bind="dxCommand: { id: 'myCommand', title: 'Say Hello', location: 'create', action: hello}"></div>

    <!-- associate with a widget -->
    <div data-bind="dxButton: { text: 'Say Hello', clickAction: hello }"></div>

    <!-- associate with an HTML element -->
    <div data-bind="dxAction: hello">Say Hello</div>
</div>
JavaScript
home = function() {
    var viewModel = {
        hello: function() { alert('Hello world'); }        
    };
    return viewModel;
}

Action as a String

An action can be defined by a string. In such a case, the string is supposed to represent a URI, which must support the routing rule declared for the application (see Navigation and Routing). When executing a string Action, the application navigates by the specified URI. Take a look at the following examples.

HTML
<div data-options="dxView: { name: 'home', title: 'Home' }">
    <!-- associate with a command -->
    <div data-bind="dxCommand: { id: 'myCommand', title: 'Show Info', location: 'create', action: '#about' }"></div>

    <!-- associate with a widget -->
    <div data-bind="dxButton: { text: 'Show Info', clickAction: '#about' }"></div>

    <!-- associate with an HTML element -->
    <div data-bind="dxAction: '#about'">Show Info</div>
</div>

The string defining an action accepts a template bound to the ViewModel.

HTML
<div data-options="dxView: { name: 'home', title: 'Home' }">
    <!-- associate with a command -->
    <div data-bind="dxCommand: { id: 'myCommand', title: 'Show Contacts', location: 'create', action: '#contacts/{contact.id}'}"></div>

    <!-- associate with a widget -->
    <div data-bind="dxButton: { text: 'Show Contacts', clickAction: '#contacts/{contact.id}' }"></div>

    <!-- associate with an HTML element -->
    <div data-bind="dxAction: '#contacts/{contact.id}'">Say Contacts</div>
</div>
JavaScript
home = function() {
    var viewModel = {
        contact: {
            id: 123,
            name: 'Mike'
        }       
    };
    return viewModel;
}

Note that the ViewModel fields to which an action template is bound can be observable.

Action as an Object

An action can be defined by an object, in which case, that object's fields must represent values of the application's routing rule parameters. When executing such an Action, the application navigates by the URI generated using specified values.

For instance, if the following routing rule is registered in the application...

JavaScript
app.router.register(":view/:id", { view: "home", id: "1" });

...the following actions can be defined...

HTML
<div data-options="dxView: { name: 'home', title: 'Home' }">
    <!-- associate with a command -->
    <div data-bind="dxCommand: { id: 'myCommand', title: 'Show Contact', location: 'create', action: { view: 'contacts', id: 123 } }"></div>

    <!-- associate with a widget -->
    <div data-bind="dxButton: { text: 'Show Contact', clickAction: { view: 'contacts', id: 123 } }"></div>

    <!-- associate with an HTML element -->
    <div data-bind="dxAction: { view: 'contacts', id: 123 }">Show Contact</div>
</div>

...and the application will navigate by the '#contacts/123' URI.

The object defining an action can be defined in the ViewModel.

HTML
<div data-options="dxView: { name: 'home', title: 'Home' }">
    <!-- associate with a command -->
    <div data-bind="dxCommand: { id: 'myCommand', title: 'Show Contact', location: 'create', action: routeValues}"></div>

    <!-- associate with a widget -->
    <div data-bind="dxButton: { text: 'Show Contact', clickAction: routeValues }"></div>

    <!-- associate with an HTML element -->
    <div data-bind="dxAction: routeValues">Show Contact</div>
</div>
JavaScript
home = function() {
    var viewModel = {
        routeValues: {
            view: 'contacts',
            id: 123
        }       
    };
    return viewModel;
}

Note that the ViewModel field to which an action is bound can be observable.