Angular SPA Framework - HtmlApplication - Events

This section describes events fired by the HtmlApplication object.

afterViewSetup

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

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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.

Type:

Event

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.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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;
});

resolveLayoutController

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

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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<Object>

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();     
    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

resolveViewCacheKey

Fires before the application searches for a cached view that matches the key generated for the current URI.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
key

String

Specifies the key used to search the cached view. Change this field value to use a cached view associated with another URI.

navigationItem

Object

An object that holds the target item of the application navigation history.

routeData

Object

An objects that holds target URI parameters produced by application's router.

If the application finds a view with the specified key, it uses this view. Otherwise, it creates a new view instance. The generated key is held in the key field of the event arguments object passed to the event handler. You can pass another key to the key field of the event arguments object to use a cached view created for another URI. In this case, the viewShowing event fires with actual parameters of the current URI, which enables you to update the loaded view according to values of these parameters.

In the following example, the application uses the same cached view instance for all URIs navigating to the Greeting view ("Greeting/hello", "Greeting/goodbye", etc.), regardless the "message" parameter. It just updates the view according to the message parameter.

JavaScript
MyApp.app.on("resolveViewCacheKey", function(args) {
    args.key = args.routeData.view;
});

MyApp.app.router.register(":view/:message", { view: "Greeting", message: undefined });

MyApp.Greeting = function(params, viewInfo) {
    var updateViewModel = function(params) {
        viewModel.message(params.message);
    };

    var viewModel = {
        message: ko.observable(),

        //Update the loaded view according to the current URI paramaters
        viewShowing: function(args) {
            updateViewModel(args.params);
        }
    };
    updateViewModel(params);
    return viewModel;
};
NOTE
If caching is disabled, the application always creates a new instance of a view.

viewDisposed

Fires after a view is disposed.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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.

NOTE
If the view contains DeferRendering widgets, their content is not yet rendered when the viewRendered event is fired. To access their content, use the onRendered option or the rendered event of a particular DeferRendering widget.

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.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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.

Type:

Event

Function parameters:
e:

Object

Information about the event.

Object structure:
Name Type Description
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. To do so, 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.

NOTE
If you use device APIs provided by Apache Cordova in your application, call device API functions after the deviceready event of Cordova has fired. Otherwise, the application may work too slow on startup. The deviceready event fires when Apache Cordova is fully loaded.