Configuration

This section describes configuration options used to create an HtmlApplication object.

animationSet

Specifies the animation presets that are used to animate different UI elements in the current application.

Type: Object
Default Value: undefined

To animate a DevExtreme application, specify the animationSet option. You can assign one of the following predefined animation sets.

  • 'default'
    A default animation set for DevExtreme applications. This set is characterized by a big number of different animations so that your application looks 'live' and attractive out-of-the-box.

  • 'native'
    This animation set is organized so that your DevExtreme looks and behave as a native application on any device.

  • 'slide'
    This animation set is similar to the 'default' animation set, but a 'slide' animation is used instead of a 'drop' animation.

  • 'zoom'
    This animation set is similar to the 'default' animation set, but a 'zoom' animation is used instead of a 'drop' animation.

These predefined animation sets are available in the DevExpress.framework.html.animationSets collection.

JavaScript
MyApp.app = new DevExpress.framework.html.HtmlApplication({
    //...
    animationSet: DevExpress.framework.html.animationSets['slide'],
});

In this instance, if you use predefined layouts, the transition from a view to a view will be animated. This is because the animation presets contained in the predefined animation sets are used in the predefined layouts for the dxTransition and dxContentPlaceholder elements. You can also animate other parts of your application using the animation presets from the application's animation set. To learn how to do this, as well as how to define custom animation sets, refer to the Animation article.

commandMapping

Specifies where the commands that are defined in the application's views must be displayed.

Type: Object
Default Value: DevExpress.framework.CommandMapping.defaultMapping

When adding a command to a view, specify in which command container this command must be displayed. For this purpose do the following.

  • Learn in which layout the view that contains this command will be displayed.
    If you use a predefined layout set, read this topic to learn in which layout your view will be displayed.

  • Learn what command containers are available in this layout.
    Since a layout can be defined for several platforms, learn the identifiers of the command containers provided for all these platforms. If you use built-in layouts, read this topic to learn what command containers they expose.

  • Add your command to the list of the commands that the required command containers display.
    Use the commandMapping configuration option of the HtmlApplication object. The object that is assigned to this option must expose fields named by the command container identifiers. These fields must be assigned to the object with the following fields.

    • defaults
      This is the object where the default values of command options are specified.
    • commands
      An array of objects that define commands to be mapped to the current command container.

Here is an example. Add the "myCommand" command to a view markup.

HTML
<div data-bind="dxCommand: { id: 'myCommand', title: 'My command' }"></div>

You found/introduced a layout for this view and found/introduced the desired command container for your command.

HTML
<div data-options="dxCommandContainer: { id: 'my-container' }"></div>

Here is the command mapping that must be defined to display your command in the required command container.

JavaScript
MyApp.app = new DevExpress.framework.HtmlApplication({
    commandMapping: {
        'my-container': {
            defaults: {
                'showIcon':false, 
                'location':'before'
            },
            commands: [
                {
                    id: 'myCommand',
                    location: 'after' // container defaults can be overridden
                }
            ]
        }
    }
});

The following fields can be set for commands.

  • id
    The command's identifier that is set using the id option of the dxCommand markup component that represents this command.

  • location
    If the command is mapped to the container that will be displayed as a toolbar, set this option to specify a location of the command on the toolbar. The following values are possible: 'before', 'center', 'after' and 'menu' (the command will be added to the toolbar's overflow menu).

  • showIcon
    Indicates whether to show an icon for the command.

  • showText
    Indicates whether to show the command's title.

  • Any option exposed by the dxCommand markup component.

Command options override the corresponding defaults that are declared for all commands of a particular command container.

NOTE
If you use predefined layouts, it is only required to define a mapping for your custom commands. An application loads default command mapping and extends it by your custom command mapping declared within the application's configuration object. To learn what commands are mapped to the built-in layouts by default, refer to the Default Command Mapping topic.
See Also

disableViewCache

Specifies whether or not view caching is disabled.

Type: Boolean

By default, this option is not specified, which means that view caching is enabled. In this instance, the first time a view is displayed, it is cached. Thereafter, when the view must be displayed repeatedly, it is obtained from the cache, so that the application does not need to create a view each time it is displayed. For details on the view display process, refer to the View Life Cycle topic.

To disable view caching, set this option to true. In this mode, each view will be created and rendered each time it is displayed.

To disable the caching of a specific view only, set the disableCache configuration option of the dxView component representing this view to true.

layoutSet

An array of layout controllers that should be used to show application views in the current navigation context.

Type: String|Array
Default Value: undefined

Views are displayed within a layout markup that usually contains such common elements as a navigation control and a toolbar - elements that are not related to a view but must be displayed to provide global navigation or other actions. Use the layoutSet option to specify which layout controllers should be used to provide appropriate layout markups for different application views and when each of these controllers should be used. The framework comes with a set of predefined layout sets. In the simplest case, you can assign one of these sets to this option.

JavaScript
window.MyApp = {};
$(function() {
    MyApp.app = new DevExpress.framework.html.HtmlApplication({
        layoutSet: DevExpress.framework.html.layoutSets['navbar'],
        namespace: MyApp
    });
});

In addition, you can specify a custom layout set. For this purpose, assign an array of objects providing information on the required layout controllers.

JavaScript
window.MyApp = {};
$(function() {
    MyApp.app = new DevExpress.framework.html.HtmlApplication({
        layoutSet: [
            { platform: 'android', controller: new MyAndroidLayoutController() },
            { platform: 'ios', controller: new MyiOSLayoutController() }
        ],
        namespace: MyApp
    });
});
See Also

mode

Specifies whether the current application must behave as a mobile or web application.

Type: String
Default Value: "mobileApp"
Accepted Values: 'mobileApp'|'webSite'

Use this option to notify the application whether it should be treated as a mobile application or a web application. Currently, the mode that you set using this option influences the following two aspects.

  • How to build a navigation history in the application
    In a 'webSite' mode, the navigation history is linear and is based on browser history. In a 'mobileApp' mode, the navigation history is based on navigation stacks and root views. To learn more about navigation history, refer to the Navigation History in Mobile Apps and Navigation in Web Apps topics.

  • Whether or not to initialize a view port for the application In a 'mobileApp' mode, the mobile browser's viewport must be initialized. In a 'webSite' mode, view port initialization is not needed.

namespace

Specifies the object that represents a root namespace of the application.

Type: Object

The object passed to this option should be previously defined. The following example illustrates how to create the MyAppNamespace object and pass it to the namespace configuration option of the application.

JavaScript
window.MyAppNamespace = {};
$(function() {
    MyAppNamespace.app = new DevExpress.framework.html.HtmlApplication(
        { namespace: MyAppNamespace }
    );
    MyAppNamespace.app.router.register(":view/:name", { view: "home", name: '' });
    MyAppNamespace.app.navigate();
});

When defining the functions that return ViewModels for application views, create these functions within the application's namespace specified via the namespace option.

JavaScript
MyAppNamespace.home = Function() {
    var viewModel = {
        //...
    }
    return viewModel;
};

navigateToRootViewMode

Specifies application behavior when the user navigates to a root view.

Type: String
Default Value: "resetHistory"
Accepted Values: 'keepHistory'|'resetHistory'

A mobile application usually consists of several root views accessible from global navigation. Each root view may have a stack of child views that are invoked one after another. For instance, a child view can be invoked to show detailed information on an item selected within a root view. To learn more about navigation stacks, refer to the Navigation History in Mobile Apps topic.

The navigateToRootViewMode option specifies whether the child view stack of a root view is kept or reset when you return to this root view.

The default value is "resetHistory". In this case, the application always displays the root view when you navigate to it. If you change the value to "keepHistory", the application will show the last accessed child view of this root view.

NOTE
This option is not considered when the 'webSite' mode is set for the application. This is because there are no navigation stacks in this mode. Instead, there is only a single stack based on the browser's navigation history.

navigation

An array of dxCommand configuration objects used to define commands available from the application's global navigation.

Type: Array

If you use one of the predefined layout sets, the built-in layouts that are used to display your views will include a global navigation control. This control is usually accessible from any view and provides access to the main application views - root views.

When developing a cross-platform application, consider the fact that a navigation control will be displayed differently across devices. Thus, navigation must be defined in an abstract way. For this purpose, the HTMLApplication object exposes the navigation option. This option is set to an array of objects, which in turn are used by the framework to create application navigation commands. Specify command configuration options within each object of the array. The framework will create commands using these objects as configuration objects. The commands will be displayed according to the current layout, based on the current device and platform.

The following example illustrates how to create an HtmlApplication, and add the "Index" and "About" commands to the application's global navigation.

JavaScript
$(function () {
    app = new DevExpress.framework.html.HtmlApplication({ 
        layoutSet: DevExpress.framework.html.layoutSets['navbar'],
        navigation:[
            {
                title: "Index",
                onExecute: "#Index",
                icon: "home"
            },
            {
                title: "About",
                onExecute: "#About",
                icon: "info"
            }
        ]
    });
    app.router.register(":view", { view: "mainView" });
    app.navigate();
});

In this example, a navbar widget will be used for global navigation, and commands will be displayed as navbar items. To learn how to define a command that will navigate to a particular view, refer to the Global Navigation Items topic of the documentation.

router

A custom router to be used in the application.

Type: Object

The custom router must have the format(obj) and parse(uri) methods implemented so that the navigation system integrated into the DevExtreme SPA framework works.

stateManager

A state manager to be used in the application.

Type: Object

When initializing the HtmlApplication object, the StateManager object is created and assigned to the stateManager field. You can use the application's state manager to manipulate the application state - add additional state sources, save and restore the state when required.

By default, the session storage is used by the application state manager as a state storage. You can use another storage specifying it using the stateStorage option of the HtmlApplication object.

stateStorage

Specifies the storage to be used by the application's state manager to store the application state.

Type: Object

By default, the state manager that is assigned to the HtmlApplication object works with the session storage. To specify another storage for application state storing, use the stateStorage option of the HtmlApplication object.

useViewTitleAsBackText

Indicates whether on not to use the title of the previously displayed view as text on the Back button.

Type: Boolean
Default Value: false

When using predefined layouts for application views, the Back button is added automatically to a view's toolbar. This button is added when there is a previously displayed view in the current navigation stack. To create this button, a command with the 'back' identifier is added to the application. This command is then displayed as a button. A place for this button on the toolbar is determined according to default command mapping. You can influence the text that will be displayed on the Back button. If the useViewTitleAsBackText option is set to true, the title of the previous view will be displayed. Otherwise, the default Back text will be displayed.

NOTE
On some devices, text may be absent on the Back button. This is made intentionally, according to the platform guidelines provided for this device.
NOTE
In web applications, there are no navigation stacks and the browser's Back button is used to return to the previously displayed view. Thus, the useViewTitleAsBackText option is not considered.

viewCache

A custom view cache to be used in the application.

Type: Object

The framework's navigation system uses a view cache to save information about the views that have already been displayed in this application. Each time a view is displayed, information about the view is requested from the view cache, so that the markup does not need to be generated again. You can influence the way the predefined view cache works by using the techniques below.

  • Totally disable caching
    Set the application's disableViewCache configuration option to true.

  • Disable the caching of some of the application views
    Set the disableCache configuration option of the dxView markup component that represents the required view to true. This may be helpful for the views that contain map widgets and large images.

  • Specify a limit for the number of views that can be cached Specify the application's viewCacheSize configuration option.

If the options above do not allow you to achieve the required caching behavior, implement a custom view cache and assign it to the viewCache option of the HtmlApplication object. A view cache must be an object that exposes the following members:

  • setView: function(key, viewInfo){};
  • getView: function(key) {};
  • removeView: function(key) {};
  • clear: function() {};
  • hasView: function(key) {};
  • viewRemoved = $.Callbacks().

You can inherit from the base view cache and implement some of the functions in a custom manner. The base view cache does not take into account the application and view options listed above. It only implements basic caching functionality.

JavaScript
MyNamespace.AdvancedViewCache = DevExpress.framework.ViewCache.inherit({
    setView: function(key, viewInfo) {
        //...
    }
});

Then, assign your view cache object to the application's viewCache configuration option.

JavaScript
MyNamespace.app = new DevExpress.framework.html.HtmlApplication({
    //...
    viewCache: new MyNamespace.AdvancedViewCache(),
});

For details on the view display process, refer to the View Life Cycle topic.

viewCacheSize

Specifies a limit for the views that can be cached.

Type: Number
Default Value: 10

When adding information about a view to a filled cache, the first added view is removed from the cache, releasing a place for the last view.

When a view is requested from the cache to be displayed repeatedly, it becomes the last in the cache stack.

For details on the process of view caching and displaying, refer to the View Life Cycle topic.

viewPort

Specifies options for the viewport meta tag of a mobile browser.

Type: Object
Object structure:
allowZoom: Boolean
Specifies whether or not to enable pinch-zooming in a mobile browser's view port.
allowPan: Boolean
Specifies whether or not to enable panning on the vertical and horizontal axes in a mobile browser's view port.
allowSelection: Boolean
Specifies whether or not to enable selection in a mobile browser's view port.
NOTE
The value that is set for this option is considered in mobile applications only.