Object Structures

This section describes the structure of the objects that are used in API multiple times as function parameters or option values.

animationConfig

Defines animation options.

Type: Object

device

The device object defines the device on which the application is running.

Module: core/devices
Export: default
Type: Object

This object is returned by the DevExpress.devices.current() and DevExpress.devices.real() methods to provide information on the device on which the application is currently running. Use the fields of this object to get the required information on the device.

You can emulate as if the application runs on another device. For this purpose, use the DevExpress.devices.current() function passing the required device object as a parameter.

The information on the device on which the application is currently running is used to provide an appropriate look and feel for the application. In particular, the styles that are most appropriate for the current device will be applied.

format

Formats values.

Type: String| function |Object
Function parameters:
value: Number|Date
A value to be formatted.
Return Value: String
The value after formatting.
Default Value: undefined
Accepted Values: 'currency' | 'fixedPoint' | 'percent' | 'decimal' | 'exponential' | 'largeNumber' | 'thousands' | 'millions' | 'billions' | 'trillions' | 'longDate' | 'longTime' | 'longDateLongTime' | 'monthAndDay' | 'monthAndYear' | 'quarterAndYear' | 'shortDate' | 'shortTime' | 'shortDateShortTime' | 'second' | 'millisecond' | 'day' | 'month' | 'quarter' | 'year' | 'dayOfWeek' | 'hour' | 'minute'

This option accepts three types of values.

  • String
    One of the predefined formats (accepted by the type option) or a date format string (accepted by the raw option of the Globalize date formatter). For information on values accepted by the raw option, refer to the LDML documentation.

    NOTE: The use of a custom date format requires Globalize libraries to be referenced within your application. For more information on using the Globalize library, refer to the Localization guide.

  • Function
    Specifies a custom format. A shortcut for the formatter option.

  • Object
    Allows you to configure the format in many aspects. Can have one of these two structures.

    // Uses a predefined format
    format: {
        type: String, // one of the predefined formats
        precision: Number, // the precision of values
        currency: String // a specific 3-letter code for the "currency" format
    }

    or

    // Specifies a custom format
    format: {
        formatter: Function, // a custom formatting function
        parser: Function // a parsing function for string values
    }

Instead of fields described in this section, you can use fields accepted by Globalize formatters. In this case, do not specify the type option. For example, you can use skeletons to format dates.

format: {
    skeleton: 'GyMMMd'
}

See the numberFormatter, currencyFormatter and dateFormatter documents for further information. Note that this approach might require additional CLDR modules not shipped with the DevExtreme package.

positionConfig

The position object specifies the widget positioning options.

Type: Object

This object is passed to the position configuration option of a widget that overlays the main screen (LoadPanel, Popup, Popover, and Toast).

The positionConfig object may contain the following fields: my, at, of, offset and collision. Look at the following sentence to see how to use these fields to position the required element against the target element.

"Place my 'left' side at the 'left bottom' corner of the '#targetElement'." The italic quoted phrase located after each option name within the sentence represents a value of the appropriate option.

template

A template notation used to specify a template for widget elements (item, title, content, etc.).

Type: String| function |DOM Node|jQuery

To use a template pass a value that has one of the following types to a template option (itemTemplate, titleTemplate, contentTemplate, template, etc.).

  • String

    Specifies the name of the template to use, if the template is defined within a widget using the dxTemplate markup option.

    AngularJS
    HTML
    <div dx-list="listOptions" dx-item-alias="itemData">
        <div data-options="dxTemplate:{ name:'customTemplate' }">
            <i>{{title}}</i><br/>
            <b>{{text}}</b>
        </div>
    </div>
    JavaScript
    var myApp = angular.module('myApp', ['dx']);
    myApp.controller("demoController", function ($scope) {
        $scope.listOptions = {
            // ...
            itemTemplate: 'customTemplate'
        }
    });
    angular.element(document).ready(function () {
        angular.bootstrap(document, ['myApp']);
    });
    Knockout
    HTML
    <div data-bind="dxList: listOptions">
        <div data-options="dxTemplate:{ name:'customTemplate' }">
            <i data-bind="title"></i><br/>
            <b data-bind="text"></b>
        </div>
    </div>
    JavaScript
    var myViewModel = {
        listOptions: {
            // ...
            itemTemplate: 'customTemplate'
        }
    }
    ko.applyBindings(myViewModel);
  • DOM Node or jQuery

    Specifies the element of the template to use. This approach is used if the template is specified out of the widget.

    AngularJS
    HTML
    <script type="text/html" id="customTemplate">
        <i>{{title}}</i><br/>
        <b>{{text}}</b>
    </script>
    <div dx-list="listOptions" dx-item-alias="itemData">
    </div>
    JavaScript
    var myApp = angular.module('myApp', ['dx']);
    myApp.controller("demoController", function ($scope) {
        $scope.listOptions = {
            // ...
            itemTemplate: $('#customTemplate')
        }
    });
    angular.element(document).ready(function () {
        angular.bootstrap(document, ['myApp']);
    });
    Knockout
    HTML
    <script type="text/html" id="customTemplate">
        <i data-bind="title"></i><br/>
        <b data-bind="text"></b>
    </script>
    <div data-bind="dxList: listOptions">
    </div>
    JavaScript
    var myViewModel = {
        listOptions: {
            // ...
            itemTemplate: $('#customTemplate')
        }
    }
    ko.applyBindings(myViewModel);
  • function

    You can use a function that returns a template name or a template element if a template is defined within or out of the widget. This approach is almost similar to the first two approaches described above. However, it enables you to choose a template depending on certain conditions.

    AngularJS
    HTML
    <div dx-list="listOptions" dx-item-alias="itemData">
        <div data-options="dxTemplate:{ name:'usualTemplate' }">
            <i>{{title}}</i><br/>
            <b>{{text}}</b>
        </div>
        <div data-options="dxTemplate:{ name:'importantTemplate' }">
            <h2>{{title}}</h2><br/>
            <b style="color: red;">{{text}}</b>
        </div>
    </div>
    JavaScript
    var myApp = angular.module('myApp', ['dx']);
    myApp.controller("demoController", function ($scope) {
        $scope.listOptions = {
            // ...
            itemTemplate: function (itemData, itemIndex, itemElement) {
                if(itemData.important)
                    return 'importantTemplate';
                return usualTemplate;
            }
        }
    });
    angular.element(document).ready(function () {
        angular.bootstrap(document, ['myApp']);
    });
    Knockout
    HTML
    <div data-bind="dxList: listOptions">
        <div data-options="dxTemplate:{ name:'standardTemplate' }">
            <i data-bind="title"></i><br/>
            <b data-bind="text"></b>
        </div>
        <div data-options="dxTemplate:{ name:'importantTemplate' }">
            <h2 data-bind="title"></h2><br/>
            <b style="color: red;" data-bind="text"></b>
        </div>
    </div>
    JavaScript
    var myViewModel = {
        listOptions: {
            // ...
            itemTemplate: function (itemData, itemIndex, itemElement) {
                if(itemData.important)
                    return 'importantTemplate';
                return usualTemplate;
            }
        }
    }
    ko.applyBindings(myViewModel);

    Alternatively, you can use a function to render the element. In this case, the function should return nothing; hoever, it should append the required markup to the rendered element, which can be accessed using the appropriate argument. The rendering function is usually used in the jQuery approach.

    JavaScript
    var listOptions = {
        // ...
        itemTemplate: function (itemData, itemIndex, itemElement) {
            itemElement.append("<i>itemData.title</i><br/>");
            itemElement.append("<b>itemData.text</b>");
        }
    }

    The list of arguments passed to the function depends on the option, which the function is assigned to. For example, if the function is passed to the itemTemplate option, it accepts the itemData, itemIndex and itemElement arguments. If the function is passed to the contentTemplate option, it accepts the contentElement argument. The arguments passed to this function are listed in a particular option description.

See Also