kendo.ui.Grid
Represents the Kendo UI Grid widget. Inherits from
Widget.
Configuration
altRowTemplate
String|Function
The template which renders the alternating table rows. Be default the grid renders a table row (<tr>
) for every data source item.
The outermost HTML element in the template must be a table row (
<tr>
). That table row must have the
uid
data attribute set to#= uid #
. The grid uses thedata attribute to determine the data to which a table row is bound to. Set the
uid
class
of the table row tok-alt
to get the default "alternating" look and feel.
Example - specify alternating row template as a function
<div id="grid"></div>
<script id="alt-template" type="text/x-kendo-template">
<tr data-uid="#= uid #">
<td colspan="2">
<strong>#: name #</strong>
<strong>#: age #</strong>
</td>
</tr>
</script>
<script>
$("#grid").kendoGrid({
dataSource: [
{ name: "Jane Doe", age: 30 },
{ name: "John Doe", age: 33 }
],
altRowTemplate: kendo.template($("#alt-template").html())
});
</script>
Example - specify alternating row template as a string
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
dataSource: [ { name: "Jane Doe", age: 30 }, { name: "John Doe", age: 33 } ],
altRowTemplate: '<tr data-uid="#= uid #"><td colspan="2"><strong>#: name #</strong><strong>#: age #</strong></td></tr>'
});
</script>
autoBind
Boolean
(default: true)
If set to false
the widget will not bind to the data source during initialization. In this case data binding will occur when the
change event of thedata source is fired. By default the widget will bind to the data source specified in the configuration.
Setting
autoBind
tofalse
is useful when multiple widgets are bound to the same data source. Disabling automatic binding ensures that the shared data source doesn't make more than one request to the remote service.
Example - disable automatic binding
<div id="grid"></div>
<script>
var dataSource = new kendo.data.DataSource({
data: [ { name: "Jane Doe" }, { name: "John Doe" }]
});
$("#grid").kendoGrid({
autoBind: false,
dataSource: dataSource
});
dataSource.read(); // "read()" will fire the "change" event of the dataSource and the widget will be bound
</script>
columns
Array
The configuration of the grid columns. An array of JavaScript objects or strings. A JavaScript objects are interpreted as column configurations. Strings are interpreted as thefield
to which the column is bound. The grid will create a column for every item of the array.
If this setting is not specified the grid will create a column for every field of the data item.
Example - specify grid columns as array of strings
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: ["name", "age"], // two columns bound to the "name" and "age" fields
dataSource: [ { name: "Jane", age: 31 }, { name: "John", age: 33 }]
});
</script>
Example - specify grid columns as array of objects
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [{
field: "name",// create a column bound to the "name" field
title: "Name" // set its title to "Name"
}, {
field: "age",// create a column bound to the "age" field
title: "Age" // set its title to "Age"
}],
dataSource: [ { name: "Jane", age: 30 }, { name: "John", age: 33 }]
});
</script>
columns.aggregates
Array
The aggregate(s) which are calculated when the grid is grouped by the columns
field.The supported aggregates are "average", "count", "max", "min" and "sum".
Example - set column aggregates
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "firstName", groupable: false },
{ field: "lastName" }, /* group by this column to see the footer template */
{ field: "age",
groupable: false,
aggregates: [ "count", "min", "max" ],
groupFooterTemplate: "age total: #: count #, min: #: min #, max: #: max #"
}
],
groupable: true,
dataSource: {
data: [
{ firstName: "Jane", lastName: "Doe", age: 30 },
{ firstName: "John", lastName: "Doe", age: 33 }
]
}
});
</script>
Check Aggregates for a live demo.
columns.attributes
Object
HTML attributes of the table cell (<td>
) rendered for the column.
HTML attributes which are JavaScript keywords (e.g. class) must be quoted.
Example - specify column HTML attributes
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [ {
field: "name",
title: "Name",
attributes: {
"class": "table-cell",
style: "text-align: right; font-size: 14px"
}
} ],
dataSource: [ { name: "Jane Doe" }, { name: "John Doe" }]
});
</script>
The table cells would look like this: <td class="table-cell" style="text-align: right; font-size: 14px">...</td>
.
columns.command
String|Array
The configuration of the column command(s). If set the column would display a button for every command. Commands can be custom or built-in ("edit" or "destroy").
The "edit" built-in command switches the current table row in edit mode.
The "destroy" built-in command removes the data item to which the current table row is bound.
Custom commands are supported by specifying the
click option.
The built-in "edit" and "destroy" commands work only if editing is enabled via the
editable option. The "edit" command supports "inline" and "popup" editing modes.
Example - set command as a string
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name" },
{ command: "destroy" } // displays the built-in "destroy" command
],
editable: true,
dataSource: [ { name: "Jane Doe" } ]
});
</script>
Example - set command as array of strings
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name" },
{ command: ["edit", "destroy"] } // displays the built-in "edit" and "destroy" commands
],
editable: "inline",
dataSource: [ { name: "Jane Doe" } ]
});
</script>
Example - set command as array of objects
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name" },
{ command: [
{
name: "details",
click: function(e) {
// command button click handler
}
},
{ name: "destroy" } // built-in "destroy" command
]
}
],
editable: true,
dataSource: [ { name: "Jane Doe" } ]
});
</script>
columns.command.name
String
The name of the command. The built-in commands are "edit" and "destroy". Can be set to a custom value.
Example - set the command name
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name" },
{ command: [{ name: "edit" }] }
],
editable: "popup",
dataSource: [ { name: "Jane Doe" } ]
});
</script>
columns.command.text
String
The text displayed by the command button. If not set the
name option is used as the button text.
Example - customize the text of the command
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name" },
{ command: [{ name: "destroy", text: "Remove" }] }
],
editable: true,
dataSource: [ { name: "Jane Doe" } ]
});
</script>
columns.command.className
String
The CSS class applied to the command button.
Example - set the CSS class of the command
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name" },
{ command: [{ className: "btn-destroy", name: "destroy", text: "Remove" }] }
],
editable: true,
dataSource: [ { name: "Jane Doe" } ]
});
</script>
<style>
.btn-destroy {
color: red;
}
</style>
columns.command.click
Function
The JavaScript function executed when the user clicks the command button. The function receives a
jQuery Event as an argument.
The function context (available via the this
keyword) will be set to the grid instance.
Example - handle the click event of the custom command button
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name" },
{ command: [ {
name: "details",
click: function(e) {
// e.target is the DOM element representing the button
var tr = $(e.target).closest("tr"); // get the current table row (tr)
// get the data bound to the current table row
var data = this.dataItem(tr);
console.log("Details for: " + data.name);
}
} ]
}
],
dataSource: [ { name: "Jane Doe" } ]
});
</script>
columns.editor
Function
Provides a way to specify a custom editing UI for the column. Use the container
parameter to create the editing UI.
The editing UI should contain an element whose
name
HTML attribute is set as the column
field.
Parameters
- container
jQuery
-
The jQuery object representing the container element.
- options
Object
- options.field
String
-
The name of the field to which the column is bound.
- options.format
String
-
The format string of the column specified via the
format option.
- options.model
kendo.data.Model
-
The model instance to which the current table row is bound.
- options.values
Array
-
Array of values specified via the
values option.
Example - create a custom column editor using the Kendo UI AutoComplete
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [ {
field: "name",
editor: function(container, options) {
// create an input element
var input = $("<input/>");
// set its name to the field to which the column is bound ('name' in this case)
input.attr("name", options.field);
// append it to the container
input.appendTo(container);
// initialize a Kendo UI AutoComplete
input.kendoAutoComplete({
dataTextField: "name",
dataSource: [
{ name: "Jane Doe" },
{ name: "John Doe" }
]
});
}
} ],
editable: true,
dataSource: [ { name: "Jane Doe" }, { name: "John Doe" } ]
});
</script>
Check Editing custom editor for a live demo.
columns.encoded
Boolean
(default: true)
If set to true
the column value will be HTML-encoded before it is displayed. If set to
false
the column value will be displayed as is. By default the column value is HTML-encoded.
Example - prevent HTML encoding
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name", encoded: false }
],
dataSource: [ { name: "<strong>Jane Doe</strong>" } ]
});
</script>
columns.field
String
The field to which the column is bound. The value of this field is displayed by the column during data binding.
Example - specify the column field
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
// create a column bound to the "name" field
{ field: "name" },
// create a column bound to the "age" field
{ field: "age" }
],
dataSource: [ { name: "Jane", age: 30 }, { name: "John", age: 33 }]
});
</script>
columns.filterable
Boolean|Object
(default: true)
If set to true
a filter menu will be displayed for this column when filtering is enabled. If set to
false
the filter menu will not be displayed. By default a filter menu is displayedfor all columns when filtering is enabled via the
filterable option.
Can be set to a JavaScript object which represents the filter menu configuration.
Example - disable filtering
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name", filterable: false },
{ field: "age" }
],
filterable: true,
dataSource: [ { name: "Jane", age: 30 }, { name: "John", age: 33 }]
});
</script>
columns.filterable.ui
String|Function
The role data attribute of the widget used in the filter menu or a JavaScript function which initializes that widget.
Example - specify the filter UI as a string
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [ {
field: "date",
filterable: {
ui: "datetimepicker" // use Kendo UI DateTimePicker
}
} ],
filterable: true,
dataSource: [ { date: new Date() }, { date: new Date() } ]
});
</script>
Example - initialize the filter UI
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [ {
field: "date",
filterable: {
ui: function(element) {
element.kendoDateTimePicker(); // initialize a Kendo UI DateTimePicker
}
}
} ],
filterable: true,
dataSource: [ { date: new Date() }, { date: new Date() } ]
});
</script>
Check
Filter menu customization for a live demo.
columns.footerTemplate
String|Function
The template which renders the footer table cell for the column.
The fields which can be used in the template are:
- average - the value of the "average" aggregate (if specified)
- count - the value of the "count" aggregate (if specified)
- max - the value of the "max" aggregate (if specified)
- min - the value of the "min" aggregate (if specified)
- sum - the value of the "sum" aggregate (if specified)
Example - specify column footer template
<div id="grid"></div>
<script>
$("#grid").kendoGrid({
columns: [
{ field: "name" },
{ field: "age",
footerTemplate: "Min: #: min # Max: #: max #"
}
],
dataSource: {
data: [
{ name: "Jane Doe", age: 30 },
{ name: "John Doe", age: 33 }
],
aggregate: [
{