HtmlApplication Events

This section describes events fired by the HtmlApplication object.

afterViewSetup

Fires after a ViewModel has been created during the view display process.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
viewInfo: Object
Provides information required for displaying a view.

When a view is displayed for the first time or information on it is removed from the cache, information on this view is gathered. A ViewModel object is one of the pieces of this information required to display the view. Handle the afterViewSetup event to modify the created ViewModel. Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

To access the ViewModel, use the model field of the viewInfo object. This object can be accessed using the viewInfo field of the object passed as the event handler's parameter.

JavaScript
MyApp.app.on("afterViewSetup", function(arg) {
    var viewModel = arg.viewInfo.model;
    //...
})

In addition to the model field, the viewInfo object exposes the viewName, uri, routeData, viewTemplateInfo and layoutController fields.

For details on this and other events related to the view display process, refer to the View Life Cycle topic.

beforeViewSetup

Fires before a ViewModel is created during the view display process.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
viewInfo: Object
Provides information required for displaying a view.

When a view is displayed for the first time or information on it is removed from the cache, information on this view is gathered. A ViewModel object is one of the pieces of this information required to display the view. Handle the beforeViewSetup event to set a custom ViewModel for the view. Otherwise, a ViewModel will be created using the corresponding function (with the view's name) found in the application's namespace.

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

JavaScript
MyApp.app.on("beforeViewSetup", function(args) {
    var viewModel = args.viewInfo.model;
    //...
})

The object passed as the event handler's parameter provides access to the viewInfo object. At this step, the viewInfo object exposes the following fields: viewName, uri, routeData, viewTemplateInfo and layoutController. You can add the model field. The object assigned to this field will be used as the view's View Model.

For details on this and other events related to the view display process, refer to the View Life Cycle topic.

initialized

Fires after the application and all its components are initialized.

When this event is triggered, all HTML templates are loaded and the application is ready to navigate to the first view.

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

navigating

Fires after navigation to another view has started.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
currentUri: String
The URI from which the application navigates to another URI.
uri: String
The URI to which the application navigates.
cancel: Boolean
Indicates whether to cancel the navigation.
options: Object
Defines navigation options (see the second parameter of the navigate() method description).

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

You can use this event to cancel navigation, as illustrated in the following example.

JavaScript
MyApp.app.on("navigating", function(e){
    e.cancel = true; //Cancel navigation
});

For details on this and other events related to the view display process, refer to the View Life Cycle topic.

navigatingBack

Fires when the HtmlApplication.back() method is called or the appropriate hardware button is pressed.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
cancel: Boolean
Indicates whether to cancel the backwards navigation.
isHardwareButton: Boolean
Indicates whether this event fires as a result of pressing a hardware Back button.

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

This event allows you to handle a Back button click, even if the hardware Back button is pressed. However, the event handler parameters do not provide information about the current view and its View Model. The following code demonstrates how to raise a confirmation dialog when clicking the Back button in a particular view and how to cancel backwards navigation if an end-users cancels it.

JavaScript
Application1.app.currentViewModel = null;
Application1.app.on("viewShown", function (e) {
    Application1.app.currentViewModel = e.viewInfo.model;
});
Application1.app.on("navigatingBack", function (e) {
    if (Application1.app.currentViewModel.name == 'View1') {
        if (!confirm("Are you sure you want to leave View1 ?")) {
            e.cancel = true;
            return;
        };
        //Execute the required code
    };
    Application1.app.currentViewModel = null;
});
See Also

See a step-by-step example in the Handle the Hardware Back Button tutorial.

resolveLayoutController

Fires when information about a view to be shown is gathered.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
viewInfo: Object
Provides information required for displaying a view. The following fields are available: 'viewName', 'uri', 'routData' and 'viewTemplateInfo'.
layoutController: Object
The layout controller that must be used to provide a layout markup for the given view.
availableLayoutControllers: Array
A collection of the layout controllers that are registered in the application and appropriate for the current device (its platform and form). Each object exposes the "controller" field and the fields presenting the device object fields.

Within the information required to display a view, the application sets the instance of the layout controller that will create a layout markup for the view. By default, it is the layout controller from the application's layout set that is most appropriate in the current navigation context. Handle the resolveLayoutController event to set a specific layout controller for a particular view, which will prevent the system from searching for an appropriate controller for this view.

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

JavaScript
window.AppNamespace = {};
$(function () {
    AppNamespace.myController = new myLayoutController({ layoutTemplateName: "myLayout" });     
    AppNamespace.app = new DevExpress.framework.html.HtmlApplication(
        {
            namespace: AppNamespace,
            layoutSet: [
                { platform: 'android', controller: new MyAndroidLayoutController() },
                { platform: 'ios', controller: new MyiOSLayoutController() },
                { customResolveRequired: true, controller: AppNamespace.myController }
            ],
         }
    );
    AppNamespace.app.router.register(":view/:name", { view: "home", name: '' });
    AppNamespace.app.on("resolveLayoutController", function(args) {
        var viewName = args.viewInfo.viewName;
        if(viewName === "about") {
            args.layoutController = AppNamespace.myController;
        }
    });
    AppNamespace.app.navigate();
});
See Also
  • You can find more information about this event and other ways to specify a custom layout set in the Custom Layout Sets topic.
  • For details on the events related to the view display process, refer to the View Life Cycle topic.
  • See a step-by-step example in the Set a Layout for a View tutorial.

viewDisposed

Fires after a view is disposed.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
viewInfo: Object
Provides information required for displaying a view.

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

When handling this event, use the viewInfo field of the object passed as the event handler's parameter. This field is the object that exposes the following fields: viewName, uri, routeData, viewTemplateInfo, layoutController, model (the ViewModel of the disposed view) and renderResult (an object exposing the $markup field).

JavaScript
MyApp.app.on("viewDisposed", function(args) {
    var viewModel = args.viewInfo.model;
    //...
});

NOTE: This event can be handled for a specific view only. In this instance, add the viewDisposed field to the view's ViewModel and assign the required function (handler) to it. For details, refer to the Handle View Events topic.

For details on the events related to the view display process, refer to the View Life Cycle topic.

viewDisposing

Fires before a view is disposed.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
viewInfo: Object
Provides information required for displaying a view.

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

When handling this event, use the viewInfo field of the object passed as the event handler's parameter. This field is the object that exposes the following fields: viewName, uri, routeData, viewTemplateInfo, layoutController, model (the ViewModel of the disposed view) and renderResult (an object exposing the $markup field).

JavaScript
MyApp.app.on("viewDisposing", function(args) {
    var viewModel = args.viewInfo.model;
    //...
});

NOTE: This event can be handled for a specific view only. In this instance, add the viewDisposing field to the view's ViewModel and assign the required function (handler) to it. For details, refer to the Handle View Events topic.

For details on the events related to the view display process, refer to the View Life Cycle topic.

viewHidden

An event triggered when the current view is replaced with another view on the application page.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
viewInfo: Object
Provides information required for displaying a view.

If the current view and the next view are displayed in the same layout, the corresponding layout controller executes a transition to the next view and then fires the viewHidden event. In the case of different layouts of the current and next views, the layout controller of the current view layout fires the viewHidden event anyway. You can access information on the current view, which is replaced with another view. To do this, handle the viewHidden event and use the object that is provided by the viewInfo field of the event handler's parameter. This object exposes the following fields: viewName, uri, routeData, viewTemplateInfo, layoutController, model (the ViewModel of the disposed view) and renderResult (an object exposing the $markup field).

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

JavaScript
MyApp.app.on("viewHidden", function(args) {
    var viewModel = args.viewInfo.model;
    //...
});

NOTE: This event can be handled for a specific view only. In this instance, add the viewHidden field to the view's ViewModel and assign the required function (handler) to it. For details, refer to the Handle View Events topic.

For details on the events related to the view display process, refer to the View Life Cycle topic.

viewRendered

Fires after the rendering of a view is completed.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
viewInfo: Object
Provides information required for displaying a view.

To display a view, information about this view must first be obtained from the application's cache. If there is no information on the view in the cache, the information is collected gradually, step-by-step. You can learn about these steps in the View Life Cycle topic. You can perform specific actions after the view's markup is rendered by handling the viewRendered event. To access information on the displayed view, use the event handler's parameter. The object passed as the parameter exposes the following fields: viewName, uri, routeData, viewTemplateInfo, layoutController, model (the ViewModel of the rendered view) and renderResult (an object exposing the $markup field).

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

JavaScript
MyApp.app.on("viewRendered", function(args) {
    var viewModel = args.viewInfo.model;
    //...
});

NOTE: This event can be handled for a specific view only. In this instance, add the viewRendered field to the view's ViewModel and assign the required function (handler) to it. For details, refer to the Handle View Events topic.

The next time the view is displayed, the cache will contain all of the information required for this view, allowing the view to be displayed right away. In this instance, the viewRendered event will not be raised. However, to perform specific actions after the view is displayed, you can handle the viewShown event.

For details on the events related to the view display process, refer to the View Life Cycle topic.

viewShowing

An event triggered each time before a view is displayed, after information on the view is obtained.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
viewInfo: Object
Provides information required for displaying a view.
direction: String
The direction in which the layout controller will animate the transition to show the view. The following values are accepted: 'backward', 'forward' or 'none'.

To display a view, information about this view must first be obtained from the application's cache. If the view has already been displayed and has not yet been removed from the navigation history, the viewInfo object found in the cache includes all information about the view. This information is presented by the following fields: viewName, uri, routeData, viewTemplateInfo, layoutController, model (the ViewModel of the disposed view) and renderResult (an object exposing the $markup field). Once all this information is available, the view is ready to be displayed. In this instance, the viewShowing event is raised before displaying the view. The viewInfo object can be accessed as the viewInfo field of the event handler's parameter.

If there is no information on the view in the cache when the view display proccess starts, the information is collected gradually, step-by-step. You can learn about these steps in the View Life Cycle topic. In this case, the viewShowing event is raised when the ViewModel is created and added to the viewInfo object as the model field. You can access the viewInfo object using the viewInfo field of the event handler's parameter.

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

JavaScript
MyApp.app.on("viewShowing", function(args) {
    var viewModel = args.viewInfo.model,
        direction = args.direction;
    //...
});

In addition to the viewInfo object provided by the viewInfo field of the object passed as the event handler's parameter, the direction in which the layout controller will animate the transition to show the view is also accessible. To specify the direction, use the direction field of the object passed as the event handler's parameter. This field can be set to the "backward", "forward" or "none" value.

NOTE: This event can be handled for a specific view only. In this instance, add the viewShowing field to the view's ViewModel and assign the required function (handler) to it. For details, refer to the Handle View Events topic.

For details on this and other events related to the view display process, refer to the View Life Cycle topic.

viewShown

An event triggered each time after a view is shown.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
viewInfo: Object
Provides information about the displayed view.
direction: String
Specifies the direction in which the layout controller animated the transition to the displayed view. The following values are accepted: 'backward', 'forward' or 'none'.

Use the on(eventName, eventHandler) method to subscribe to this event and the off(eventName) method to unsubscribe from it.

The viewInfo object that is accessible from the event handler's parameter exposes the following fields: viewName, uri, routeData, viewTemplateInfo, layoutController, model (the ViewModel of the displayed view) and renderResult (an object exposing the $markup field).

JavaScript
MyApp.app.on("viewShown", function(args) {
    var viewModel = args.viewInfo.model,
        direction = args.direction;
    //...
});

NOTE: This event can be handled for a specific view only. In this instance, add the viewShown field to the view's ViewModel and assign the required function (handler) to it. For details, refer to the Handle View Events topic.

This event is appropriate for sending asynchronous requests, because the transition to the view is already completed at this time, and the forthcoming response will not interrupt the process of the view display.

To perform specific actions after the view is rendered for the first time, handle the viewRendered event.

For details on events related to the view display process, refer to the View Life Cycle topic.