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 appearance by adding or removing particular fields from data source objects. For example, the List widget has a default template for items that contains the text, visible, and disabled fields. If you assign the following array to the widget's dataSource option, the first item will be disabled, the second hidden, both of them will have text, and the third item will render a custom markup:

JavaScript
function customMarkup() {
    var d = document.createElement("div");
    d.innerHTML = "<i>Oranges</i>";
    return d;
}
var fruits = [
    { text: "Apples", disabled: true },
    { text: "Lemons", visible: false },
    { template: customMarkup }
];

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.

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

ko.applyBindings(viewModel);
React
DxComponent.js
import React from 'react';
import List, { Item } from 'devextreme-react/list';

class DxComponent extends React.Component {
    render() {
        return (
            <List>
                <Item text="Apples" disabled={true} />
                <Item text="Oranges" visible={false} />
                <Item>
                    <i>Oranges</i>
                </Item>
            </List>
        );
    }
}
export default DxComponent;

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 syntax of the used library (Angular, Knockout, etc.). 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. In the code below, it is the List widget's itemTemplate 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 = [
        { 
            itemProperty: "someValue",
            // ...
        },
        // ...
    ]
}
@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 = [
            { 
                itemProperty: "someValue",
                // ...
            },
            // ...
        ];
    });
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: [
        { 
            itemProperty: "someValue",
            // ...
        },
        // ...
    ]
};

ko.applyBindings(viewModel);
jQuery
JavaScript
$(function() {
    $("#listContainer").dxList({
        dataSource: [
            { 
                itemProperty: "someValue",
                // ...
            },
            // ...
        ],
        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.