Markup Components

This section describes the framework components that can be used when defining the markup of the application page.

dxCommand

An object used to define markup options for a command.

Type: Object

Commands are abstract actions that can be called from a platform specific location. Suppose you need a view to contain "Back" and "Add" buttons. In an application designed for the iPhone, the "Back" button must be located on the left side of the title bar, and the "Add" button must be located on the right side of the title bar. If you want to make an application for an android phone, you will need to display the "Add" button on the bottom navbar, and not display the "Back" button at all, since the phone has a "Back" button built into the hardware. When implementing an application that will run on both the iPhone and an Android phone, you will not only need to define two different layouts, but also create and manage different widgets for these platforms.

Instead of manually managing different widgets on different platforms, you can define a single view with two commands. In this case, you will have buttons created for commands that will work properly on both iPhone and Android devices. This will also deliver a native user experience for each device.

Commands are declared in view markup within a root element. To add a command, add a div element with the data-bind attribute set to dxCommand, and pass the required markup options. These options include the action to be performed when executing the command, an abstract location for the command on the screen, along with the title, icon, and the enabled and visible states.

HTML
<div data-options="dxView: { name: 'index', title: 'Home' }">
    <div data-bind="dxCommand: { action: add, location: 'create', title: 'Add' } "></div>
</div>

To function properly, this code snippet expects the "add" field to be present in the ViewModel. This field can be a function that will be called when executing the Add command, or a string representing the URL to navigate to. To learn more about actions, refer to the Actions documentation section.

The framework comes with a set of predefined layouts that are located in the layouts folder installed with other PhoneJS resources. In addition, you can find the layouts folder in the template project that comes with PhoneJS, which will assist you as you begin building an application. The following is a list of built-in layouts along with available placeholders and command locations.

  • Navbar

    Exposes the header, content, and footer placeholders. Declares the following command locations: navigation, back, create, edit and save. Defined for iOS, android and win8.

  • SlideOut

    Exposes the header and content placeholders. Declares the following command locations: navigation, menu, back, create, edit, save and delete. Defined for iOS and android.

  • Split

    Exposes the header, content, and footer placeholders. Declares the following command locations: back, create, cancel, edit, save and delete. Defined for win8.

  • Desktop

    Exposes a single content placeholder. Declares the following command locations: navigation, create, edit, save and delete. Defined for the desktop.

  • Empty

    This is the default layout, which exposes a single content placeholder and does not declare command locations.

For more information about commands, refer to the Views and Layouts section of the documentation.

dxContent

An object used to define markup options for a content element.

Type: Object

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

HTML
<div class="my-layout" data-options="dxLayout: { name: 'default', platform: 'ios' }" id="page">
    <div id="wrapper">
        <div class="layout-header" data-bind="dxToolbar: { dataSource: toolbarData }"></div>
        <div class="layout-content" data-options="dxContentPlaceholder: { name: 'content', transition: 'slide' }"></div>
    </div>
    <div class="layout-footer" data-options="dxContentPlaceholder: { name: 'footer', transition: 'overflow' }"></div>
</div>

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

HTML
<div data-options="dxView: { name: 'mainView', title: 'Home' }">
    <div data-options="dxContent: { targetPlaceholder: 'content' }">
        <div class="buttonContainer" data-bind="dxButton: { text: 'Click me', clickAction: 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>

dxContentPlaceholder

An object used to define markup options for a content placeholder.

Type: Object

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

HTML
<div class="my-layout" data-options="dxLayout: { name: 'default', platform: 'ios' }" id="page">
    <div id="wrapper">
        <div class="layout-header" data-bind="dxToolbar: { dataSource: toolbarData }"></div>
        <div class="layout-content" data-options="dxContentPlaceholder: { name: 'content', transition: 'slide' }"></div>
    </div>
    <div class="layout-footer" data-options="dxContentPlaceholder: { name: 'footer', transition: 'overflow' }"></div>
</div>

The example below displays a view with corresponding content elements.

HTML
<div data-options="dxView: { name: 'mainView', title: 'Home' }">
    <div data-options="dxContent: { targetPlaceholder: 'content' }">
        <div class="buttonContainer" data-bind="dxButton: { text: 'Click me', clickAction: 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>

dxLayout

An object used to define markup options for a layout.

Type: Object

A layout defines the structure of an application. Each screen of an application usually consists of a specific view, and several common UI elements such as the dxNavBar and dxToolbar widgets.

To define a layout, create an HTML page and add a div element to it. To declare this element as a layout, set the element's data-options attribute to dxLayout, and pass the required layout markup options.

The following example illustrates the declaration of a layout consisting of a toolbar that is common for all views, and two placeholders ("content" and "footer").

HTML
<div class="my-layout" data-options="dxLayout: { name:'default', platform:'ios' }" id="page">
    <div id="wrapper">
        <div class="layout-header" data-bind="dxToolbar: { dataSource:toolbarData }"></div>
        <div class="layout-content" data-options="dxContentPlaceholder: { name:'content', transition:'slide' }"></div>
    </div>
    <div class="layout-footer" data-options="dxContentPlaceholder: { name:'footer', transition:'overflow' }"></div>
</div>

The default application layout is specified by the defaultLayout field of the options object passed to the application constructor.

JavaScript
app = new DevExpress.framework.html.HtmlApplication({ defaultLayout: "default" });

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

dxTransition

An object used to define markup options for a transition element.

Type: Object

Use the dxTransition markup options 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.

HTML
<div data-options="dxLayout : { name: 'myLayout' }" >
    <div data-options="dxTransition: { name: 'myTransition', type: 'slide' }">
        <div data-options="dxContentPlaceholder : { name: 'header'} " >
            <div data-bind="dxToolbar: { items: [ { text: title, align: '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: { locations: [{'name': 'navigation'}] }">
        </div>
    </div>
</div>

dxView

An object used to define markup options for a view.

Type: Object

A view is defined by a piece of HTML markup that forms the view template. The view can optionally have JavaScript code (in a separate file) and an associated style sheet used to customize the look and feel. Every view has a unique name that serves as an identifier. The framework uses this name to find the view's HTML markup and javascript code. The javascript code assiciated with a view contains a function called by the view's name.

To define a View, add a div element and include the required markup in it. To declare the View markup as a View, set the wrapping div's data-options attribute to dxView, and pass the required View markup options.

HTML
<div data-options="dxView: { name: 'mainView', title: 'Home' }">
    <div data-options="dxContent: { targetPlaceholder: 'content' }">
        <div class="buttonContainer" data-bind="dxButton: { text: 'Click me', clickAction: 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>

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

dxViewPlaceholder

An object used to define markup options for a view placeholder.

Type: Object

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

HTML
<!--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', clickAction: buttonClicked }"></div>
        <div class="mapsContainer" data-bind="dxMap: { location: 'Brooklyn Bridge,New York,NY', zoom: 10 }"></div>
    </div>
</div>

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