jQuery/JS SPA Framework - HtmlApplication - Events
afterViewSetup
Event
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.
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
Event
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.
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
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
Event
Name | Type | Description |
---|---|---|
currentUri |
The URI from which the application navigates to another URI. |
|
uri |
The URI to which the application navigates. |
|
cancel |
Indicates whether to cancel the navigation. |
|
options |
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.
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
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.
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
Event
Name | Type | Description |
---|---|---|
viewInfo |
Provides information required for displaying a view. The following fields are available: 'viewName', 'uri', 'routData' and 'viewTemplateInfo'. |
|
layoutController |
The layout controller that must be used to provide a layout markup for the given view. |
|
availableLayoutControllers |
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.
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.
Event
Name | Type | Description |
---|---|---|
key |
Specifies the key used to search the cached view. Change this field value to use a cached view associated with another URI. |
|
navigationItem |
An object that holds the target item of the application navigation history. |
|
routeData |
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.
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; };
viewDisposed
Event
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).
MyApp.app.on("viewDisposed", function(args) { var viewModel = args.viewInfo.model; //... });
For details on the events related to the view display process, refer to the View Life Cycle topic.
viewDisposing
Event
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).
MyApp.app.on("viewDisposing", function(args) { var viewModel = args.viewInfo.model; //... });
For details on the events related to the view display process, refer to the View Life Cycle topic.
viewHidden
Event
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.
MyApp.app.on("viewHidden", function(args) { var viewModel = args.viewInfo.model; //... });
For details on the events related to the view display process, refer to the View Life Cycle topic.
viewRendered
Event
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.
MyApp.app.on("viewRendered", function(args) { var viewModel = args.viewInfo.model; //... });
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
Event
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.
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.
For details on this and other events related to the view display process, refer to the View Life Cycle topic.
viewShown
Event
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).
MyApp.app.on("viewShown", function(args) { var viewModel = args.viewInfo.model, direction = args.direction; //... });
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.
If you have technical questions, please create a support ticket in the DevExpress Support Center.