Methods

This section describes the methods used to manipulate the application flow.

back()

Navigates to the URI preceding the current one in the navigation history.

canBack()

Returns a Boolean value indicating whether or not the navigation history contains items except for the root item.

Return Value: Boolean

If the navigation history contains items, the value is true. Otherwise, the value is false.

clearState()

Removes the information on the navigation stack saved to the state storage using the saveState method.

getViewTemplate(viewName)

Returns an HTML template of the specified view.

Parameters:
viewName: String

A name of the searched view template.

Return Value: jQuery

A jQuery object representing the searched view template.

Use this method to get an HTML template of a view. The name passed as the method's parameter should be the value of the name option specified for the dxView component representing the searched view.

getViewTemplateInfo(viewName)

Returns a configuration object used to create a dxView component for a specified view.

Parameters:
viewName: String

A name of the requested view.

Return Value: Object

A configuration object of the dxView component representing the specified view.

The name passed as the method's parameter should be the value of the name option specified for the requested dxView configuration object.

navigate(uri, options)

Navigates to the specified URI.

Parameters:

A string containing the URI to which the application navigated or a route values object to produce an URI.

options: Object

Specifies additional navigation parameters.

Object structure:
root: Boolean

Indicates whether to create a new navigation stack based on the navigated view.

target: String

Specifies whether to add the navigated view to the navigation stack or replace the current view. The following values are accepted: 'blank' and 'current'.

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'.

The following values can be passed as the uri parameter.

  • string
    The string must confirm the routing rule (one of the routing rules) that is registered in the application's router. For details on how to declare a routing rule, refer to the Declare a Routing topic.

    JavaScript
    app.router.register(":view/:id", { view: "home", name: "World" });
    JavaScript
    app.navigate('contacts/1');
  • object
    This object must expose the fields that correspond to the routing rule parameters.

    JavaScript
    app.router.register(":view/:id", { view: "home", name: "World" });
    JavaScript
    app.navigate({
        view: 'contacts',
        id: 1
    });

Using the second parameter of this function, you can specify the following parameters.

  • root
    If you pass an object with the root field set to true as the second parameter of the navigate method, the specified view will be invoked as a root view. This means that a new navigation stack will be created as if you used the application's global navigation to navigate to this view. The view that will be invoked from the root view with an unspecified root parameter will be saved to navigation history based on this root view.

    JavaScript
    app.navigate('OrderItems/' + orderId, { root: true });
  • target
    You can pass an object with the target field set to the following values.

    • 'blank' - adds the invoked view to the navigation history (the default value)
    • 'current' - replaces the current view in the navigation history with the invoked view

      JavaScript
      app.navigate('OrderItems/' + orderId, { target: 'current' });
  • direction
    Specify the direction in which the layout will animate the transition to the view. This option can be set to the "backward", "forward" or "none" value.

To learn more about root views and navigation history, refer to the Navigation History topic.

If none of the parameters are specified, the navigate method will display the view that is set as a default view in the routing rule (see the Declare a Routing topic).

As an alternative to the navigate method, you can introduce a command and set its action option to a string or an object representing a URL to navigate to. In this instance, the root, target and direction options can be set for the command as well as to define the navigation details.

To learn more about the navigate method and other methods used to navigate to a view, refer to the Navigate to a View topic.

To navigate back to a previous view, use the back method, or define a command. The command will be visualized in the required place of the view and navigate to the previous view if you set the '#_back' method for the action option. For details, refer to the Navigate Back topic.

restoreState()

Restores the navigation stack saved by the saveState() method to the state store, and applies it to the application.

When calling this method, the saved navigation stack becomes the current navigation stack in the application, and the view that was displayed at the moment the state was saved is displayed again.

saveState()

Saves the current navigation stack to the state storage.

Use this method to save the current navigation stack to a state storage when required, e.g., when the application is closed. By default, the session storage is used as a state storage. You can use another storage specifying it via the stateStorage option of the HtmlApplication object.

The state stored by this method is the following:

  • items in the current navigation stack;
  • the position of the displayed view in the current navigation stack.

You can restore the state saved by this method. To do this, use the restoreState() method. In addition, you can remove the saved state by using the clearState() method.