Configuration

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

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 the command container where this command must be displayed. For this purpose, do the following.

  • Determine which layout the view that contains this command will be displayed.
    If you use a predefined navigation strategy, read this topic to determine the layout in which your view will be displayed.

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

  • Add your command to the list of 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 have 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':'left'
            },
            commands: [
                {
                    id: 'myCommand',
                    align: 'right' // 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 the location of the command on the toolbar. The following values are possible: 'left', 'center', 'right' and 'menu' (the command will be added to the toolbar's overflow menu).

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

  • showText
    Indicates whether or not 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, you are only required to define a mapping for your custom commands. An application loads a default command mapping and extends it with your custom command mapping declared within the application's configuration object. To learn about the commands that are mapped to the built-in layouts by default, refer to the Default Command Mapping topic.

For details on how to add commands to views, refer to the Add Commands to Views topic.

defaultLayout

Deprecated

Use the navigationType option instead.

The name of the default layout used by the application.

Type: String
Default Value: "default"

A view in a PhoneJS application is created by merging the dxView and dxLayout markups. The dxView markup component defines the markup that is rendered specifically for the current view. The dxLayout markup component commonly represents the unchanged markup that can be used in several views. If a certain layout will be used in all (or most) application views, use the defaultLayout option of the HtmlApplication object to set this layout as the default.

JavaScript
$(function() {
    app = new DevExpress.framework.html.HtmlApplication({
        defaultLayout: 'Navbar'
    });
    //...
});
HTML
<div data-options="dxView: { name: 'home', title: 'Home' }">
    <!-- View markup goes here -->
</div>

To set a specific layout for a view, use the layout option of the corresponding dxView markup component.

HTML
<div data-options="dxView: { name: 'splash', layout: 'splashLayout' }">
    <!-- View markup goes here -->
</div>

A layout is identified by its name, which is specified via the name option of the dxLayout markup component. If you use one of the predefined layouts, open the HTML file that contains the markup of the required layout and find the value of the name option in the dxLayout component configuration.

HTML
<div class="navbar-layout" data-options="dxLayout : { name: 'navbar', platform: 'ios', controller: 'navbar' } " >
    <!--...-->
</div>

To get more details on the process of layout and view merging, refer to the Insert View into Layout topic.

disableViewCache

Specifies whether or not view cashing 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. Each following time when the view must be displayed repeatedly, it is obtained from the cache. This allows the application to not have to create a view each time it is displayed. For details on the process of the view display, 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.

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'

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

The navigateToRootViewMode option specifies whether the child view stack of a root view is kept or reset when you return back 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.

navigation

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

Type: Array

If you use one of predefined navigation strategies, 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({ 
        navigationType: "navbar",
        navigation:[
            {
                title: "Index",
                action: "#Index",
                icon: "home"
            },
            {
                title: "About",
                action: "#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 implement a command action that will navigate to a particular view, refer to the Navigation and Routing section of the documentation.

navigationType

Specifies a strategy for choosing layouts for views in your application.

Type: String
Default Value: undefined

Views are displayed in layouts that usually contain 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 navigationType option to set the required navigation strategy. According to this strategy, a particular layout is applied to a view based on the current navigation context. PhoneJS comes with a set of predefined strategies. In the simplest case, you can use one of these strategies. In addition, you can override a predefined strategy or use a custom navigation strategy. To learn more about navigation strategies, refer to the Navigation Types article.

ns

Deprecated

Use the namespace option instead.

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

Type: Object

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.

Assign an object of configuration options for a mobile browser's view port.