DevExtreme Angular - 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
For documentation on templates in DevExtreme ASP.NET MVC Controls, refer to Implementing Templates (for ASP.NET MVC 5) or Templates (for ASP.NET Core).

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.

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 { }

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.

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
  • ],
  • // ...
  • })

View Demo

You can define custom templates for individual items in collection widgets. When using any library or framework except jQuery, 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.

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
  • ],
  • // ...
  • })

Many widgets provide options that end with ...Template, but particular widgets (Button, Drawer, and others) have an option called template. These widgets allow you to declare the markup directly in the widget element to specify their content.

app.component.html
app.component.ts
app.module.ts
  • <dx-button (onClick)="foo($event)">
  • <i style="color:green">
  • Refresh
  • </i>
  • </dx-button>
  • // ...
  • export class AppComponent {
  • foo(e) {
  • // ...
  • }
  • }
  • import { DxButtonModule } from "devextreme-angular";
  • // ...
  • @NgModule({
  • imports: [
  • // ...
  • DxButtonModule
  • ],
  • // ...
  • })

3rd-Party Template Engines

You can use a 3rd-party template engine, but only with jQuery. 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.