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.

If information on the view is not contained in the cache, a ViewModel object must be created to proceed displaying the view. Handle this event to modify the created ViewModel. To access the ViewModel, use the model field of the viewInfo object passed as the event handler's parameter.

JavaScript
MyApp.app.afterViewSetup.add(function(viewInfo) {
    var viewModel = viewInfo.model;
    //...
})

In addition to the ViewModel object, the viewInfo object provides the viewName and uri fields that specify the name of the view that is being displayed and the uri that the application navigates to.

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.

If information on the view is not contained in the cache, a ViewModel object must be created to proceed displaying the view. Handle this 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,
        routeData = args.routeData;
    //...
})

The object passed as the event handler's parameter exposes the following fields.

  • viewInfo
    Includes the viewName and uri fields that specify the name of the view that is being displayed and the uri that the application navigates to.
  • routeData
    An object that includes the fields representing the parameters of the routing rule registered within the application router.

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

blankViewRendered

An event triggered before a blank view is displayed.

If information on the view is not contained in the cache, the view is displayed in two steps:

  • Show a blank view (the markup of the view's layout only);
  • Merge the view's and layout's markups, apply bindings and finally display the view.

A blank view is shown first while the view is prepared to quickly respond to end-user manipulations that have been performed to navigate to the view.

Handle the blankViewRendered event to access the viewInfo object after the markup is ready to be rendered to display a blank view.

JavaScript
MyApp.app.blankViewRendered.add(function(viewInfo) {
    var markup = viewInfo.renderResult.$markup;
    //...
})

The viewInfo object passed as the event handler's parameter exposes the following fields:

  • viewName;
  • uri;
  • layoutName;
  • $layoutTemplate;
  • renderResult (the object that exposes the $markup and layoutControllerName fields).

NOTE: This event can be handled for a specific view as well. In this instance, add the blankViewRendered 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.

navigating

An event triggered after navigation to another view has started.

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

Generally, you can use the following parameters of the navigating event handler.

  • currentUri
    The URI from which the application navigates to another URI.
  • uri
    The URI to which the application navigates.
  • options
    The object that is passed as the second parameter of the invoked navigate method.
  • cancel
    A Boolean value that indicates whether or not to cancel the navigation to the specified URI (view).

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

viewDisposed

An event triggered after a view is disposed.

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: name, uri, model (the ViewModel of the disposed view) and renderResult (an object exposing the $markup and layoutControllerName fields).

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.

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: name, uri, model (the ViewModel of the disposed view) and renderResult (an object exposing the $markup and layoutControllerName fields).

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 changed by another view on the application page.

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 changed by 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: name, uri, model (the ViewModel of the hidden view) and renderResult (an object exposing the $markup and layoutControllerName fields).

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.

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. When the view's markup is prepared, the layout in which the view is displayed renders this markup. You can perform specific actions after the 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: name, uri, model (the ViewModel of the displayed view) and renderResult (an object exposing the $markup and layoutControllerName fields).

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 and it will be enough to display the view at once. 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 these events that 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.

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: name, uri, model (the ViewModel of the displayed view) and renderResult (an object exposing the $markup and layoutControllerName fields). 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 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.

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 will animate the transition to show the view is also accessible. To specify the direction, use the direction field of the object passed 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.

The following fields are exposed by the object passed as the event handler's parameter

  • viewInfo
    The object presenting information about the displayed view. The following fields are available: name, uri, model (the ViewModel of the displayed view) and renderResult (an object exposing the $markup and layoutControllerName fields)
  • direction
    Specifies the direction in which the layout animated the transition to the shown view. This field can be set to the "backward", "forward" or "none" value
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.