WinForms HTML & CSS Templates — Collection Rendering

WinForms Team Blog
26 October 2022

As you may already know, many of our WinForms data-aware controls support HTML & CSS Templates (from our WinForms Data Grid to our WinForms Gantt Control). When these controls display plain data (where each data field stores simple values such as numeric, string, Boolean, etc), data binding syntax allows you to construct templates without restrictions.

<div>${ModelName}</div>
<div>${Price}</div>
<div>$Available: {InStock}</div>
<img src="${Photo}"/>

Unfortunately, some data sources may also include data fields that store a collection of items: a List, an array, a data set, and so on. The DevExpress Tile View— Auto Height demo is an example of such a data source. The Data Grid displays tasks with simple properties (Title, Manager, Due Data), as well as one collection property (the "Members" property returns a list of employees assigned to this card).

In previous versions, you could display data from such properties by manipulating templates within the CustomItemTemplate event. This meant you were required to manually check collection capacity for this specific data record, create an HTML element for each item, and replace the fake element added in advance with a real HTML markup.

void OnCustomItemTemplate(object sender, TileViewCustomItemTemplateEventArgs e) {
    var task = tileView1.GetRow(e.RowHandle) as EmployeeTask;
    var sb = new StringBuilder();
    foreach(var member in task.Members) {
        sb.Append("<div class=\"initials\">");
        sb.Append(member.Initials);
        sb.Append("</div>");
    }
    e.HtmlTemplate.Template = e.HtmlTemplate.Template.Replace("", sb.ToString());
}

In our next major update (v22.2), you will be able to avoid manual template customization and leverage the power of a more native approach. The <dx-collection> tag is the unique DevExpress element that allows you to specify a collection property whose items need to be visualized, and the template that must be applied to these items.

<template id="member-template">
	<div class="initials" title="${FullName}">${Initials}</div>
</template>

<div class="container">
	<div class="card">
		<div class="stripe" dx-class="{PriorityName}"></div>
		<div class="content">
			<div class="top-block">
				<div class="caption"><b>${Name}</b></div>
			</div>
			<div class="description">${Description}</div>
			<div class="bottom-block">
				<div class="bottom-block-near">
					<div><span class="label">Due Date: </span>${DueDate}</div>
					<div><span class="label">Manager: </span>${Employee}</div>
				</div>
				<dx-collection class="members" Items="${Members}"
                    ItemTemplate="member-template"></dx-collection>
			</div>
		</div>
	</div>
</div>
  • Lines 1 to 3 — the template applied to every collection item. Note that these templates must be declared before the main template of the control.
    • The ${Initials} binding tells the template it should display values of the "Initials" property.
    • The title property allows collection items to display hints with "FullName" property values.
  • Lines 18 and 19 — the <dx-collection> tag.
    • The Items property points to the collection property.
    • The ItemTemplate property specifies the ID of the template that must be applied to collection items.

In addition to this core functionality, you can utilize conditional CSS formatting described in an earlier blog post: WinForms HTML & CSS Templates — Conditional Styling. The dx-class property supports four unique attributes for collections:

  • dx-first and dx-last — applied to the first and last items of a collection. Both styles are ignored if a collection has only one item.
  • dx-odd and dx-even — applied to items with odd and even indexes. The first collection item is even (index is 0)..

<template id="template for items">
    <div class="text circle"
    dx-class="{dx-odd:ci-odd; dx-even:ci-even; dx-first:ci-first; dx-last:ci-last;}">
        ${Initials}
    </div>
</template>
.ci-odd { background-color: White; }
.ci-even{ background-color: Black; }
.ci-first{ background-color: Gray; }
.ci-last { background-color: Orange; }

Free DevExpress Products – Get Your Copy Today

The following free DevExpress product offers remain available. Should you have any questions about the free offers below, please submit a ticket via the DevExpress Support Center at your convenience. We’ll be happy to follow-up.