jQuery SPA Framework - HtmlApplication - Configuration

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.

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.

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.

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

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

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

• locateInMenu
  If the command is mapped to the container that will be displayed as a toolbar, set this option to specify when to display the command in the toolbar's overflow menu. The following values are accepted: 'always', 'never' and 'auto'.

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

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.

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.

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.

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

• SPA Framework - Custom Layout Sets topic.

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.

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.

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.

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

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.

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.

$(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.

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.

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.

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.

Loading and pre-processing application templates usually takes significant time. A DevExtreme application can cache the resulting markup in the browser's local storage to avoid loading and pre-processing templates at the second and subsequent application startups. To enable caching, specify the current version of the application templates using the templatesVersion option.

Increment the templates version each time you change application templates to regenerate the markup according to the new templates.

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.

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.

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

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

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.

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.