jQuery SPA Framework - Markup Components

Use dxAction binding to execute a custom action when clicking a bound HTML element. The action can be defined in one of the following ways.

• Function
  This function is performed when clicking a bound HTML element.

• String
  The target URL to be navigated to.

• Object
  The fields of this object represent parameters for the URL to be navigated to.

Generally, the dxAction binding is analogous to the dxclick event supplied with the DexExtreme UI Events library. However, there two distinctions.

• The dxAction binding allows you to navigate to a URL by assigning that URL (a string or an object) as a binding value. For details, refer to the Navigate to a View topic.

• When you assign a function to dxAction binding, you can use the function's parameters to access the DOM element involved in this binding, the model that is available for binding against the element and the jQueryEvent that caused the action execution.

The dxCommand markup component allows you to define a view-related action in an abstract way. Add a div element to the root of the view markup with the data-bind attribute set to dxCommand. Use the configuration options of the dxCommand component to define an action in an abstract way. These options include the handler performed when executing the command, the title, the icon, and the enabled and visible states.

<div data-options="dxView: { name: 'index', title: 'Home' }">
    <div data-bind="dxCommand: { id: 'myCommand', onExecute: '#product-details', title: 'Add' } "></div>
</div>

As you can see in the code above, a command can be used for navigation. In this instance, you can set the onExecute option to a URI or to an object defining a URI. In addition, you can specify navigation options for a command - the options that have the same names as the fields of the options object passed as the second parameter to the HtmlApplication.navigate(uri, options) method.

A command's markup options can be bound to ViewModel fields. Here is an example.

<div data-options="dxView: { name: 'home', title: 'Home' }">
    <div data-bind="dxCommand: { id: 'myCommand', onExecute: add, title: 'Add' } "></div>
</div>

To function properly, this code snippet expects the "add" field to be present in the ViewModel.

To be displayed, a command must be registered within a command container using the application's command mapping. Depending on the command container chosen for a command in a layout and the device the application is running on, different widgets will be used to display commands. You can specify widget configuration settings directly within the dxCommand component's configuration object.

<div data-bind="dxCommand: { id: 'myCommand', onExecute: '#product-details', title: 'Add', hint: 'Add a product' } "></div>

In the code above, the specified hint option will be applied if the widget that will display the command has the hint option in its configuration.

To learn more about commands and how to display them in a view, read the Add Commands to Views topic.

Some of the widgets that are located within a layout markup can be indicated as command containers. In this instance, view commands can be displayed as items of these widgets. For instance, if a layout has a toolbar added as a command container, the commands of the view that is merged with this layout can be displayed as toolbar items.

<div data-options="dxToolbar: { }, dxCommandContainer : { id: 'android-footer-toolbar' } "></div>

A command container must have an identifier. To set an identifier, use the id option of the dxCommandContainer component. You will use a command container's id when defining command mapping. Keeping in mind the command containers provided by a layout used for your views, specify which commands must be displayed within each of these command containers. For this purpose, use the application's commandMapping option.

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

If you use predefined layouts in your application, you should be aware of the command containers that are provided by these layouts. For this purpose, research the HTML code of the required layouts or look through the Built-in Layouts article. Use the identifiers of the required command containers when mapping your commands. Note that you can rely on the application's default command mapping, which defines what commands must be displayed within each of the predefined layouts (including device specific layout versions) and in which spots of the widgets representing these command containers these commands must be placed. In this instance, you don't have to define command mapping for your commands. Only name your commands as commands are named in default command mapping.

A content element is a view element rendered to the appropriate content placeholder in the layout. The name of the placeholder to which the current content should be rendered is specified by the targetPlaceholder configuration option.

The following example illustrates how to create a layout containing two content placeholders ("content" and "footer").

<div class="my-layout" data-options="dxLayout: { name: 'default', platform: 'ios' }">
    <div class="layout-content" data-options="dxContentPlaceholder: { name: 'content', animation: 'slide' }"></div>
    <div class="layout-footer" data-options="dxContentPlaceholder: { name: 'footer', animation: 'overflow' }"></div>
</div>

The example below shows how to create a view with corresponding content elements.

<div data-options="dxView: { name: 'mainView', title: 'Home' }">
    <div data-options="dxContent: { targetPlaceholder: 'content' }">
        <div class="buttonContainer" data-bind="dxButton: { text: 'Click me', onClick: buttonClicked }"></div>
        <div class="mapsContainer" data-bind="dxMap: { location: 'Brooklyn Bridge,New York,NY', zoom: 10 }"></div>
    </div>
    <div data-options="dxContent: { targetPlaceholder: 'footer' }">
        <span data-bind="text: footerText"></span>
    </div>
</div>

The opposite scenario is also possible. A view can contain a content placeholder. In this instance, the layout that displays this view can have a markup for this placeholder. For this purpose, the markup must be wrapped by the div element with the data-options attribute set to dxContent.

When rendering an application, all content elements of the view are placed in the appropriate content placeholder elements of the layout. The placeholder is identified by name, which is specified by the name configuration option.

The following example illustrates how to create a layout containing two content placeholders ("content" and "footer").

<div class="my-layout" data-options="dxLayout: { name: 'default', platform: 'ios' }">
    <div class="layout-content" data-options="dxContentPlaceholder: { name: 'content', animation: 'slide' }"></div>
    <div class="layout-footer" data-options="dxContentPlaceholder: { name: 'footer', animation: 'overflow' }"></div>
</div>

The example below displays a view with corresponding content elements.

<div data-options="dxView: { name: 'mainView', title: 'Home' }">
    <div data-options="dxContent: { targetPlaceholder: 'content' }">
        <div class="buttonContainer" data-bind="dxButton: { text: 'Click me', onClick: buttonClicked }"></div>
        <div class="mapsContainer" data-bind="dxMap: { location: 'Brooklyn Bridge,New York,NY', zoom: 10 }"></div>
    </div>
    <div data-options="dxContent: { targetPlaceholder: 'footer' }">
        <span data-bind="text: footerText"></span>
    </div>
</div>

The opposite scenario is also possible. A view can contain a content placeholder. In this case, the layout that displays this view can have markup for this placeholder. For this purpose, the markup must be wrapped by the div element with the data-options attribute set to dxContent.

The dxLayout markup component allows you to introduce a custom layout HTML template. To indicate a particular markup as a layout, wrap this markup by a div element and set the element's data-options attribute to dxLayout. Set a name for the layout using the name option of the dxLayout component.

<div class="my-layout" data-options="dxLayout: { name:'default' }">
    <div class="layout-header" data-bind="dxToolbar: { dataSource:toolbarData }"></div>
    <div class="layout-content" data-options="dxContentPlaceholder: { name:'content', animation:'slide' }"></div>
    <div class="layout-footer" data-options="dxContentPlaceholder: { name:'footer', animation:'overflow' }"></div>
</div>

You can define a layout for a specific device only (e.g. iPhone). For this purpose, specify dxLayout options with the same names as the fields of the device object.

To render the layout markup and fill it with missing content (merge it with the view markup and add commands to command containers), a layout controller must be created. In addition, a layout markup can be accompanied by style sheets (CSS). For more information about layouts, refer to the Define Layouts help article.

Use the dxTransition markup component to specify the type of animation shown when the contents of a layout element are being changed.

Enclose the required part of the layout in a dxTransition element to apply the specified transition type to this part. In this case, when you switch between views, the contents of the enclosed part will change smoothly, according to the specified transition type.

The following example shows a layout whose "header" and "content" content placeholders are enclosed in a dxTransition element.

<div data-options="dxLayout : { name: 'myLayout' }" >
    <div data-options="dxTransition: { name: 'myTransition', animation: 'slide' }">
        <div data-options="dxContentPlaceholder : { name: 'header'} " >
            <div data-bind="dxToolbar: { items: [ { text: title, location: 'center' } ] }"> </div>
        </div>
        <div data-options="dxContentPlaceholder : { name: 'content'}">
            <div class="load-panel" data-bind="dxLoadPanel: { visible: true }"> </div>
        </div>
    </div>
    <div data-options="dxContentPlaceholder : { name: 'footer' }">
        <div data-bind="dxNavBar: { }" 
            data-options="dxCommandContainer: { id: 'footer-command-container' }">
        </div>
    </div>
</div>

A view is defined by a piece of HTML markup that forms the view template. The view can optionally have JavaScript code and associated style sheets used to customize the look and feel. To define a view's HTML template, add a div element and include the required markup in it. To indicate this markup as a view markup, set the wrapping div's data-options attribute to dxView, and pass the required view markup options.

<div data-options="dxView: { name: 'mainView', title: 'Home' }">
    <div data-options="dxContent: { targetPlaceholder: 'content' }">
        <div data-bind="dxButton: { text: 'Click me', onClick: buttonClicked }"></div>
        <div data-bind="dxMap: { location: 'Brooklyn Bridge,New York,NY', zoom: 10 }"></div>
    </div>
</div>

You can define a view for a specific device only (e.g. iPhone). For this purpose, specify dxView options with the same names as the fields of the device object.

For more information about views, refer to the Views and Layouts help section.

The dxViewPlaceholder markup component enables you to display a view inside another view as a way of reusing a markup (similar to partial rendering in ASP.NET MVC or ASP.NET user controls). To do this, create an empty div element inside a view markup. To declare this element as the place where another view will be rendered, set the element's data-options attribute to dxViewPlaceholder. Set the viewName configuration option of the dxViewPlaceholder component to the name of the view to be rendered to this placeholder.

<!--main view-->
<div data-options="dxView: { name: 'mainView', title: 'Home' }">
    <div data-options="dxViewPlaceholder: { viewName: 'content' }"></div>
    <div data-options="dxContent: { targetPlaceholder: 'footer' }">
        <span data-bind="text: footerText"></span>
    </div>
</div>

<!--view part-->
<div data-options="dxView: { name: 'content' }">
    <div data-options="dxContent: { targetPlaceholder: 'content' }">
        <div class="buttonContainer" data-bind="dxButton: { text: 'Click me', onClick: buttonClicked }"></div>
        <div class="mapsContainer" data-bind="dxMap: { center: 'Brooklyn Bridge,New York,NY', zoom: 10 }"></div>
    </div>
</div>

For more information about views, refer to the Views and Layouts help section.