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.

The navigation history is built in different ways in mobile and web applications. To learn the difference, read the Navigation History in Mobile Apps and Navigation in Web Apps topics.

canBack()

Returns a Boolean value indicating whether or not backwards navigation is currently possible.

Return Value: Boolean

true if the backwards navigation is possible. Otherwise, the value is false.

When the navigation system operates in a 'website' mode, this method returns true if navigation history contains items (except for the root item). In the 'mobileApp' mode, this method always returns true.

clearState()

Removes the application state that has been saved by the saveState() method to the state storage.

Currently, information on the current navigation stack is saved by the saveState() method. The saved navigation stack is not restored after the clearState() method is called.

createNavigation(navigationConfig)

Creates global navigation commands.

Parameters:
navigationConfig: Array

An array of dxCommand configuration objects defining commands for the global navigation.

Use this method to create navigation commands dynamically. The created commands are mapped to the "global-navigation" command container. You can access them via the application's navigation field. To display these navigation commands within the navigation controls used in the application's layouts, call the renderNavigation method.

To see an example, refer to the Create Navigation Dynamically tutorial.

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

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

loadTemplates(source)

Adds a specified HTML template to a collection of view or layout templates.

Parameters:
source: String|jQuery object

A string containing the URI of the HTML page or a jQuery object presenting a template markup.

Return Value: jQuery.Promise

A Promise of the jQuery Deferred object that is resolved when the template is loaded or rejected when loading fails.

Use this method to provide an HTML template for a view or layout dynamically. When a template for this view/layout is required, the loaded template will be found in the collection of view/layout templates.

The markup that is passed as the method's parameter should be defined using the dxView/dxLayout markup components in the same manner as a view/layout that is defined statically.

HTML
<div data-options="dxView : { name: 'MyView', title: 'My view'  } ">
    <div data-options="dxContent : { targetPlaceholder: 'content' } ">       
        ...
    </div>
</div>
HTML
<div data-options="dxLayout: { name:'default', platform:'ios' }">

</div>
See Also

NOTE: If more than one view/layout template is found, an exception will be raised. So, check to see that there are no templates for a view/layout when you add a template dynamically. Use the getViewTemplate and getViewTemplateInfo methods to find a view template in a template collection.

navigate(uri, options)

Navigates to the specified URI.

Parameters:

A string containing the URI to which the application should navigate.

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 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
    This field can be set in a mobile application only. 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 the 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
    This field can be set in a mobile application only. 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.

NOTE: Only the target option is considered when the webSite mode is set for the application. The root and direction options are valid for mobile applications. To learn more about root views and navigation history in mobile applications, refer to the Navigation History in Mobile Apps 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 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 with the action option set to the '#_back' method. For details, refer to the Navigate Back in Mobile Apps and Navigation in Web Apps topics.

renderNavigation()

Renders navigation commands to the navigation command containers that are located in the layouts used in the application.

If you specify a set of navigation commands dynamically, call the renderNavigation method. This method clears the navigation command container and renders the navigation control representing this command container so that the commands created dynamically are displayed. This is performed in each layout that is included in the application's layout set if the layout includes a control representing a global navigation command container.

NOTE: If you define navigation commands for the application before the application runs, using the navigation option, you don't have to call neither the createNavigation nor renderNavigation method. Navigation commands will be created and rendered automatically.

To see an example, refer to the Create Navigation Dynamically tutorial.

restoreState()

Restores the application state that has been saved by the saveState() method to the state storage, and applies it to the application.

Currently, only information about the current navigation stack is saved by the saveState() method. So, when calling the restoreState() 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 application state.

Use this method to save the current application state when required, e.g., when the application is closed.

This method passes the request to save the current state to a state manager. The state manager has a collection of state sources that should be notified when a request to save the current state arrives. By default, the state manager has only the navigation manager in this collection. So when calling this method, the navigation manager saves the current navigation history. Note that when the navigation system works in the website mode, the navigation manager does nothing to save the state. In the mobileApp mode, the current navigation stack is saved to a state storage. In particular, the following information on the navigation stack is saved.

  • Items in the current navigation stack
  • The position of the displayed view in the current navigation stack

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.

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.

templateContext()

Provides access to the object that defines the current context to be considered when choosing an appropriate template for a view.

Return Value: Object

An object that represents the current context to be used when choosing an appropriate template for a view.

Currently, the object returned by this method specifies the current device orientation only. But you can add a custom context to this object so that it is also considered when choosing an appropriate template for a view. For this purpose, use the option(optionName, optionValue) method of TemplateContext object. For details, refer to the Context Specific Markup topic.