DevExtreme jQuery/JS - Templates

Templates allow you to customize DevExtreme widgets. This article gives an overview of the capabilities that DevExtreme provides for implementing and applying templates.

NOTE
Refer to the Implementing Templates article for documentation on templates in DevExtreme ASP.NET MVC Controls.

Default Templates

Default templates are based on data source fields. You can control their appearance by adding or removing particular fields from data source objects. For example, the List widget has a default template for items that contain the text, visible, and disabled fields. If you assign the following array to the widget's dataSource option, all the items have text, the second item is disabled, and the third is invisible:

JavaScript
var fruits = [
    { text: "Apples" },
    { text: "Oranges", disabled: true },
    { text: "Lemons", visible: false }
];

You can achieve the same in the markup using the dxItem component that supports default and custom templates. Do not set the widget's dataSource option in this case. This approach is for Angular, AngularJS, and Knockout only.

Angular
HTML
TypeScript
<dx-list ... >
    <dxi-item text="Apples"></dxi-item>
    <dxi-item text="Oranges" [disabled]="true"></dxi-item>
    <dxi-item text="Lemons" [visible]="false"></dxi-item>
</dx-list>
import { DxListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxListModule
    ],
    // ...
})
AngularJS
HTML
JavaScript
<div ng-controller="DemoController">
    <div dx-list="{ ... }">
        <div data-options="dxItem: { text: 'Apples' }"></div>
        <div data-options="dxItem: { text: 'Oranges', disabled: true }"></div>
        <div data-options="dxItem: { text: 'Lemons', visible: false }"></div>
    </div>
</div>
angular.module('DemoApp', ['dx'])
    .controller('DemoController', function ($scope) {
        // ...
    });
Knockout
HTML
JavaScript
<div data-bind="dxList: { ... }">
    <div data-options="dxItem: { text: 'Apples' }"></div>
    <div data-options="dxItem: { text: 'Oranges', disabled: true }"></div>
    <div data-options="dxItem: { text: 'Lemons', visible: false }"></div>
</div>
var viewModel = {
    // ...
};

ko.applyBindings(viewModel);

Default templates and the fields available in them depend on the widget. For a list of default templates for a widget, search for "default template" in the left menu.

Custom Templates

DevExtreme provides the dxTemplate markup component for Angular, AngularJS, and Knockout apps. Implement a dxTemplate within the widget's container using the library's syntax. You can access a template's context properties within the template and, in item templates, the item index as shown in the following code. Assign the template's name to a widget's ...Template option. One widget can have multiple dxTemplates. If you use jQuery alone, set the widget's ...Template option to a function that combines the HTML markup using jQuery DOM manipulation methods.

Angular
HTML
TypeScript
<dx-list ...
    [dataSource]="listData"
    itemTemplate="listItem">
    <div *dxTemplate="let itemData of 'listItem'; let itemIndex = index">
        {{itemIndex}} - {{itemData.itemProperty}}
    </div>
</dx-list>
import { DxListModule } from 'devextreme-angular';
// ...
export class AppComponent {
    listData = [
        // ...
    ]
}
@NgModule({
    imports: [
        // ...
        DxListModule
    ],
    // ...
})
AngularJS
HTML
JavaScript
<div ng-controller="DemoController">
    <div dx-list="{
        ...
        dataSource: listData,
        itemTemplate: 'listItem'
    }" dx-item-alias="itemData">
        <div data-options="dxTemplate: { name: 'listItem' }">
            {{$index}} - {{itemData.itemProperty}}
        </div>
    </div>
</div>
angular.module('DemoApp', ['dx'])
    .controller('DemoController', function ($scope) {
        $scope.listData = [
            // ...
        ];
    });
Knockout
HTML
JavaScript
<div data-bind="dxList: {
    ...
    dataSource: listData,
    itemTemplate: 'listItem'
}">
    <div data-options="dxTemplate: { name: 'listItem' }">
        <span data-bind="text: $index"></span> - <span data-bind="text: itemProperty"></span>
    </div>
</div>
var viewModel = {
    listData: [
        // ...
    ]
};

ko.applyBindings(viewModel);
jQuery
JavaScript
$(function() {
    $("#listContainer").dxList({
        dataSource: [
            // ...
        ],
        itemTemplate: function (itemData, itemIndex, element) {
            element.append(
                $("<span>").text(itemIndex) - $("<span>").text(itemData.itemProperty)
            )
        }
    });
});

View Demo

You can define custom templates for individual items in collection widgets. In Angular, AngularJS, and Knockout apps, declare the items using the dxItem component as shown in the following code. Do not set the widget's dataSource option. To do the same with jQuery, assign a function combining the HTML markup to a data source object's template option.

Angular
HTML
TypeScript
<dx-list ... >
    <dxi-item>
        <i>Item 1</i>
    </dxi-item>
    <dxi-item>
        <b>Item 2</b>
    </dxi-item>
    <dxi-item>
        Item with a nested component
        <div *dxTemplate>
            <dx-button text="Click me"></dx-button>
        </div>
    </dxi-item>
</dx-list>
import { DxListModule, DxButtonModule } from 'devextreme-angular';
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxListModule,
        DxButtonModule
    ],
    // ...
})
AngularJS
HTML
JavaScript
<div ng-controller="DemoController">
    <div dx-list="{ ... }">
        <div data-options="dxItem: { }">
            <i>Item 1</i>
        </div>
        <div data-options="dxItem: { }">
            <b>Item 2</b>
        </div>
        <div data-options="dxItem: { }">
            Item with a nested component
            <div dx-button="{
                text: 'Click me'
            }"></div>
        </div>
    </div>
</div>
angular.module('DemoApp', ['dx'])
    .controller('DemoController', function ($scope) {
        // ...
    });
Knockout
HTML
JavaScript
<div data-bind="dxList: { ... }">
    <div data-options="dxItem: { }">
        <i>Item 1</i>
    </div>
    <div data-options="dxItem: { }">
        <b>Item 2</b>
    </div>
    <div data-options="dxItem: { }">
        Item with a nested component
        <div data-bind="dxButton: {
            text: 'Click me'
        }"></div>
    </div>
</div>
var viewModel = {
    // ...
};

ko.applyBindings(viewModel);
jQuery
JavaScript
$(function() {
    $("#listContainer").dxList({
        dataSource: [{
            template: function () {
                return $("<i>").text("Item 1")
            }
        }, {
            template: function () {
                return $("<b>").text("Item 2")
            }
        },{
            template: function () {
                return $("<div>").append(
                    $("<span>").text("Item with nested component"),
                    $("<div>").dxButton({
                        text: "Click me"
                    })
                )
            }
        }]
    });
});

Each widget's customization is described in dedicated articles. Search for "customize appearance" in the left menu and navigate to your widget's article for more information.

3rd-Party Template Engines

You can choose a 3rd-party template engine if you do not use Angular, AngularJS, or Knockout. DevExtreme supports the following template engines out of the box:

To use one of them, pass its name to the DevExpress.ui.setTemplateEngine(name) method:

JavaScript
HTML
DevExpress.ui.setTemplateEngine("underscore");

$(function() {
    $("#list").dxList({
        // ...
        itemTemplate: $("#itemTemplate")
    });
})
<div id="list"></div>
<script type="text/html" id="itemTemplate">
    <!-- your Underscore template -->
</script>

View Demo

You can also use other template engines, but you need to implement functions that compile and render templates in this case. See DevExpress.ui.setTemplateEngine(options) for details.