jQuery/JS SPA Framework - HtmlApplication - 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 'website' mode, this method always returns true. In 'mobileApp' mode, this method returns false if the current view is a root view in the navigation history; otherwise, it returns true.

clearState()

Calls the clearState() method of the application's StateManager object.

createNavigation(navigationConfig)

Creates global navigation commands.

Parameters:
navigationConfig:

Array<Object>

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.

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

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

Return Value:

Promise<void> (jQuery or native)

A Promise that is resolved after the template is loaded or rejected after loading failed. It is a native Promise or a jQuery.Promise when you use jQuery.

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)

Navigates to the specified URI.

Parameters:
uri:

String

|

Object

| undefined

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

navigate(uri, options)

Navigates to the specified URI.

Parameters:
uri:

String

|

Object

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

options:

Object

Specifies additional navigation parameters.

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

Boolean

Specifies whether the navigated view should be shown in modal mode.

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.

    • 'back' - replaces the previous 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.

  • modal
    Set this field to true to display the navigated view in a modal popup window. For this purpose, add the Popup Layout to your application. This layout uses the Popup widget to display a view in a popup window. By default, the SimpleLayoutController controller is used to manage popup window content. So, when defining a modal view, find out which content placeholders and command containers are available in the Simple Layout. If the navigated view should always be displayed in a popup modal window, specify its modal option. In this instance, you will not have to specify this parameter each time you navigate to this view.

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 onExecute 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 onExecute option set to the '#_back' method. For details, refer to the Navigate Back in Mobile Apps and Navigation in Web Apps topics.

off(eventName)

Detaches all event handlers from a single event.

Parameters:
eventName:

String

The event's name.

Return Value:

Object

The object for which this method is called.

See Also

off(eventName, eventHandler)

Detaches a particular event handler from a single event.

Parameters:
eventName:

String

The event's name.

eventHandler:

Function

The event's handler.

Return Value:

Object

The object for which this method is called.

See Also

on(eventName, eventHandler)

Subscribes to an event.

Parameters:
eventName:

String

The event's name.

eventHandler:

Function

The event's handler.

Return Value:

Object

The object for which this method is called.

Use this method to subscribe to one of the events listed in the Events section.

See Also

on(events)

Subscribes to events.

Parameters:
events:

Object

Events with their handlers: { "eventName1": handler1, "eventName2": handler2, ...}

Return Value:

Object

The object for which this method is called.

Use this method to subscribe to several events with one method call. Available events are listed in the Events section.

See Also

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.

restoreState()

Calls the restoreState() method of the application's StateManager object.

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 the moment the state was saved is displayed again.

saveState()

Calls the saveState method of the application's StateManager object.

By default, the application's state manager has only the navigation manager in the collection of state sources. 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

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.