HtmlApplication Events

This section describes events fired by the HtmlApplication object.

afterViewSetup

An event triggered after a ViewModel has been created during the view display process.

Callback Function Argument 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. 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.afterViewSetup.add(function(arg) {
    var viewModel = arg.viewInfo.model;
    //...
})

In addition to the model field, the viewInfo object exposes the viewName, uri, routData, 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

An event triggered before a ViewModel is created during the view display process.

Callback Function Argument 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.

JavaScript
MyApp.app.beforeViewSetup.add(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

An event triggered after the application is initialized together with all its components.

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

navigating

An event triggered after navigation to another view has started.

Callback Function Argument 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).

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

JavaScript
MyApp.app.navigating.add(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

An event triggered when the HtmlApplication.back() method is called or the appropriate hardware button is pressed.

Callback Function Argument Structure:
cancel: Boolean
Indicates whether to cancel the backwards navigation.
isHardwareButton: Boolean
Indicates whether this event is fired as a result of pressing a hardware Back button.

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 cancel backwards navigation if an end-user cancels it.

JavaScript
Application1.app.currentViewModel = null;
Application1.app.viewShown.add(function (e) {
    Application1.app.currentViewModel = e.viewInfo.model;
});
Application1.app.navigatingBack.add(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;
});

resolveLayoutController

An event triggered when information about a view to be shown is gathered.

Callback Function Argument 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 (the platform and form).

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 that is most appropriate in the current navigation context according to the specified navigation strategy. Handle the resolveLayoutController event to set a specific layout controller for a particular view, which will change the specified navigation strategy.

JavaScript
window.AppNamespace = {};
$(function () {        
    AppNamespace.app = new DevExpress.framework.html.HtmlApplication(
        {
            namespace: AppNamespace,
            navigationType: 'myNavigation'
        }
    );
    AppNamespace.app.router.register(":view/:name", { view: "home", name: '' });
    AppNamespace.app.resolveLayoutController.add(function(args) {
        var viewName = args.viewInfo.viewName;
        if(viewName === "about") {
            var result = $.grep(args.availableLayoutControllers, function (item, index) {
                return item.navigationType == 'empty';
            });
            result.length ? result[0].controller : null;
            args.layoutController = result;
        }
    });
    AppNamespace.app.navigate();
});

You can find more information about ways to use this event to change the navigation strategy in the Override Navigation Strategy topic. For details on the events related to the view display process, refer to the View Life Cycle topic.

viewDisposed

An event triggered after a view is disposed.

Callback Function Argument Structure:
viewInfo: Object
Provides information required for displaying a view.

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.viewDisposed.add(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

An event triggered before a view is disposed.

Callback Function Argument Structure:
viewInfo: Object
Provides information required for displaying a view.

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.viewDisposing.add(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.

Callback Function Argument 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's 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).

JavaScript
MyApp.app.viewHidden.add(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

An event triggered after the rendering of a view is completed.

Callback Function Argument Structure:
viewInfo: Object
Provides information required for displaying a view.

To display a view, information about this view must be obtained from the application's cache first. 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).

JavaScript
MyApp.app.viewRendered.add(function(args) {
    var viewModel = args.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 full information on this view, which will be enough to display this view right away. In this instance, the viewRendered event will not be fired. 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 every time before a view is displayed after information on this view is obtained.

Callback Function Argument 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 be obtained from the application's cache first. If the view has already been displayed and has not been removed from the navigation history yet, the viewInfo object found in the cache includes all the information about the view. This information is presented by the following fields: viewName, uri, routeData, viewTemplateInfo, layoutController, model (the ViewModel of the displayed view) and renderResult (an object exposing the $markup field). With all this information 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 process 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.

JavaScript
MyApp.app.viewShowing.add(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 to 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.

Callback Function Argument Structure:
viewInfo: Object
Provides information required for displaying a view.
direction: String
The direction in which the layout controller animates the transition to show the view. The following values are accepted

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 shown view) and renderResult (an object exposing the $markup field).

JavaScript
MyApp.app.viewShown.add(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 moment, and the coming 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 these events related to the view display process, refer to the View Life Cycle topic.