Using Client Templates
The Telerik UI for ASP.NET Core components provide templating options that let you customize and control their appearance or integrate other UI components. Many use cases require displaying a specified component element (for example, item, option, button, cell, and more) differently based on a specified condition or overriding its default look and feel. In such scenarios, client templates come in handy.
The templating options use Kendo UI Templates, which offer a way to create HTML chunks that can be merged automatically with JavaScript code. They are a substitute for traditional HTML string-building in JavaScript.
The available template types are:
Inline Client Templates
You can create an inline client template as a string or a JavaScript function. They are suitable for small templates.
The following example demonstrates how to define the template for the DropDownList items as a string. To display the Model properties values as HTML, use the hash syntax (#=#).
@(Html.Kendo().DropDownList()
.Name("customers")
.HtmlAttributes(new { style = "width: 100%" })
.DataTextField("ContactName")
.DataValueField("CustomerID")
.Template("<span class=\"contact-name\" style=\"color: \\#ffa96a;\"><b>#=ContactName #</b><p>#=CompanyName#</p></span>") // You can display the values of Model properties that are available in the data returned from the Read request.
.DataSource(source =>
{
source.Read(read =>
{
read.Action("Template_GetCustomers", "DropDownList");
});
})
.Height(400)
)
@addTagHelper *, Kendo.Mvc
<kendo-dropdownlist name="customers" style="width:100%"
datatextfield="ContactName"
datavaluefield="CustomerID"
template="<span class='contact-name' style='color:\\#ffa96a;'><b>#=ContactName #</b><p>#=CompanyName#</p></span>"
height="400">
<datasource type="DataSourceTagHelperType.Custom">
<transport>
<read url="@Url.Action("Template_GetCustomers", "DropDownList")"/>
</transport>
</datasource>
</kendo-dropdownlist>
To set an inline template as a function, pass the name of the function in the template method.
@(Html.Kendo().DropDownList()
.Name("customers")
.HtmlAttributes(new { style = "width: 100%" })
.DataTextField("ContactName")
.DataValueField("CustomerID")
.Template("#=getDropDownItem(data)#")
.DataSource(source =>
{
source.Read(read =>
{
read.Action("Template_GetCustomers", "DropDownList");
});
})
.Height(400)
)
<script>
function getDropDownItem(data) {
if (data.Country == "Germany") {
let templateString = ({ ContactName }) => `<span style="color: orange;"><b> ${kendo.htmlEncode(ContactName)}</b></span>`;
let template = kendo.template(templateString);
return template(data);
} else {
let templateString = ({ ContactName, CompanyName }) => `<span style="color: blue;"><b> ${kendo.htmlEncode(ContactName)}</b> --> ID: <i>${kendo.htmlEncode(CompanyName)}</i></span>`;
let template = kendo.template(templateString);
return template(data);
}
}
</script>
@addTagHelper *, Kendo.Mvc
<kendo-dropdownlist name="customers" style="width:100%"
datatextfield="ContactName"
datavaluefield="CustomerID"
template="#=getDropDownItem(data)#"
height="400">
<datasource type="DataSourceTagHelperType.Custom">
<transport>
<read url="@Url.Action("Template_GetCustomers", "DropDownList")"/>
</transport>
</datasource>
</kendo-dropdownlist>
<script>
function getDropDownItem(data) {
if (data.Country == "Germany") {
let templateString = ({ ContactName }) => `<span style="color: orange;"><b> ${kendo.htmlEncode(ContactName)}</b></span>`;
let template = kendo.template(templateString);
return template(data);
} else {
let templateString = ({ ContactName, CompanyName }) => `<span style="color: blue;"><b> ${kendo.htmlEncode(ContactName)}</b> --> ID: <i>${kendo.htmlEncode(CompanyName)}</i></span>`;
let template = kendo.template(templateString);
return template(data);
}
}
</script>
External Client Templates
The external client templates are preferable for more advanced and complex scenarios. Within an external template, you can add HTML markup and JavaScript logic, as long as the JavaScript is properly formatted with the Kendo UI Template syntax.
The external template is a Kendo UI Template defined by using HTML script blocks, which is suitable for larger templates.
For example, you can define an external client template for a Grid column by following the steps below:
-
Set up a script block with the
text/x-kendo-templatetype.<script type="text/x-kendo-template"> <!--Template content here--> </script> -
Add an
idto the template script and ensure its value is unique on the page.<script type="text/x-kendo-template" id="myTemplate"> </script> -
Specify the desired JavaScript logic in the template. For example, display the relevant information based on the value of the
Discontinuedproperty.<script type="text/x-kendo-template" id="myTemplate"> <div class="product-item"> #if(Discontinued){# <div><b>Active order</b></div> #}else{# <div>#: ProductName # is already shipped</div> #}# </div> </script> -
Pass the
idof the template to theClientTemplateIdmethod of the Grid column.@(Html.Kendo().Grid<Kendo.Mvc.Examples.Models.ProductViewModel>() .Name("Grid") .Columns(columns => { columns.Bound(p => p.ProductName); columns.Bound(p => p.UnitPrice); columns.Bound(p => p.Discontinued).ClientTemplateId("myTemplate"); }) .Pageable() .Scrollable() .DataSource(dataSource => dataSource .Ajax() .PageSize(20) .Read("Products_Read", "Grid") ) )@addTagHelper *, Kendo.Mvc <kendo-grid name="Grid"> <columns> <column field="ProductName"/> <column field="UnitPrice"/> <column field="Discontinued" template="#=getTemplate(data)#"/> </columns> <pageable enabled="true"/> <scrollable enabled="true"/> <datasource type="DataSourceTagHelperType.Ajax" page-size="20"> <schema data="Data" total="Total"> <model id="ProductID"> </model> </schema> <transport> <read url="@Url.Action("Products_Read", "Grid")"/> </transport> </datasource> </kendo-grid> <script> var getTemplate = kendo.template($('#myTemplate').html()); // Compile the external template. </script>
Also, you can integrate Telerik UI for ASP.NET Core components in the external client templates by using the HTML Helpers or Tag Helpers.
Adding HTML Helpers inside External Client Templates
By default, every Telerik UI HtmlHelper renders a script element immediately after its HTML markup. If the helper declaration is placed inside an external Kendo UI template, the nested script elements will be invalid. The ToClientTemplate method instructs the helper to escape its own script element so that it can be nested.
<script id="template" type="text/x-kendo-template">
@(Html.Kendo().NumericTextBox()
.Name("age")
.ToClientTemplate()
)
</script>
<div id="container"></div>
<script>
$(function () {
var template = kendo.template($("#template").html());
$("#container").append(template);
})
</script>
Adding Tag Helpers inside External Client Templates
.NET framework ignores any Tag Helpers that are within script tags. To compile them correctly, when placing a Tag Helper within a Kendo UI Template, set the type to text/html and add the is-in-client-template="true" attribute.
The following example demonstrates how to include Chart TagHelpers in the TileLayout TagHelper.
<!-- container chart templates -->
<script id="downloads-template" type="text/html">
<kendo-chart name="downloads" is-in-client-template="true">
<series>
<series-item type="ChartSeriesType.Line" data="new double[] { 56000, 63000, 74000, 91000, 117000, 138000 }">
</series-item>
</series>
</kendo-chart>
</script>
<script id="devices-template" type="text/html">
<kendo-chart name="devices" is-in-client-template="true">
<series>
<series-item type="ChartSeriesType.Donut" auto-fit="true" data='new dynamic[] {
new {category = "Asia",value = 30.8,color = "\\#006634"},
new {category = "Europe",value = 69.2,color = "\\#90cc38"}}'>
</series-item>
</series>
</kendo-chart>
</script>
<kendo-tilelayout name="tilelayout" columns="2" resizable="true" reorderable="true">
<containers>
<container body-template-id="downloads-template" col-span="1" row-span="1">
<container-header text="Weekly Recap-Downloads" />
</container>
<container body-template-id="devices-template" col-span="1" row-span="1">
<container-header text="Devices" />
</container>
</containers>
</kendo-tilelayout>
Content Security Policy (CSP) Templates
As of the R1 SP1 2023 release, Telerik UI for ASP.NET Core addresses the content security policy issues related to the usafe-eval directive for components except for the Spreadsheet.
To create CSP-compatible templates, Telerik UI for ASP.NET Core introduces an overload of the components template methods that accept JS function name. It allows you to define the template content by a client side handler. This way, you can prevent the components from being dependent on the unsafe-eval and reuse the templates within multiple components in different application pages.
The example below demonstrates how to load the item template of a ComboBox through a function handler.
@(Html.Kendo().ComboBox()
.Name("customers")
.DataTextField("ContactName")
.DataValueField("CustomerID")
.HtmlAttributes(new { style = "width: 100%;" })
.DataSource(source =>
{
source.Read(read =>
{
read.Action("Template_GetCustomers", "ComboBox");
});
})
.TemplateHandler("itemTemplateHandler")
)
@addTagHelper *, Kendo.Mvc
<kendo-combobox name="customers" style="width: 100%;"
datatextfield="ContactName"
datavaluefield="CustomerID"
template-handler="itemTemplateHandler">
<datasource>
<transport>
<read url="@Url.Action("Template_GetCustomers","ComboBox")"/>
</transport>
</datasource>
</kendo-combobox>
function itemTemplateHandler(data) {
if(data.Country == "Germany"){
return `<div><b>${data.ContactName}</b></div>`
} else {
return `<div><i>${ContactTitle}</i> - <b>${ContactName}</b></div>`
}
}