Skip to content

Commit b28aebb

Browse files
author
Dimo Dimov
committed
Add Local CRUD operations documentation
1 parent ee8e47d commit b28aebb

File tree

1 file changed

+253
-0
lines changed

1 file changed

+253
-0
lines changed

‎framework/datasource/crud.md

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
---
2+
title: CRUD Operations
3+
page_title: Kendo UI DataSource CRUD Operations
4+
description: How to use the Kendo UI DataSource component for CRUD operations (create, read, update, delete), i.e. editing
5+
---
6+
7+
# Kendo UI DataSource CRUD Operations
8+
9+
The Kendo UI DataSource fully supports CRUD (Create, Read, Update, Destroy) data operations.
10+
Surely, it must be combined with some user interface or another Kendo UI widget (Grid, ListView, etc).
11+
The examples below will use a Grid, but the same considerations apply in any other scenario.
12+
13+
The DataSource can work with local data or remote data. In both cases the CRUD operations are managed by the so-called Kendo UI Transport.
14+
This is a Javascript object that can be configured to execute predefined functions or make requests to predefined URLs on certain events.
15+
16+
## CRUD Operations with Local Data
17+
18+
### Read
19+
20+
When a Kendo UI DataSource instance must be bound to local data without the need to support editing, it is sufficient to use the `data` option like this:
21+
22+
var dataSource = new kendo.data.DataSource({
23+
data: sampleData
24+
}
25+
26+
However, when editing will be used, then a `transport` configuration is required. The `data` option is no longer needed.
27+
The `read` method of the `transport` should pass a local variable. It can even make a custom Ajax request and then pass the response.
28+
29+
var dataSource = new kendo.data.DataSource({
30+
transport: {
31+
read: function (e) {
32+
// on success
33+
e.success(sampleData);
34+
// on failure
35+
//e.error("XHR response", "status code", "error message");
36+
}
37+
},
38+
error: function (e) {
39+
alert("Status: " + e.status + "; Error message: " + e.errorThrown);
40+
}
41+
}
42+
43+
Executing the `success` method of the `read` function argument will populate the DataSource instance and fire its `change` event.
44+
Executing the `error` method will fire the `error` event of the DataSource, which can be handled.
45+
46+
### Update
47+
48+
The `update` configuration setting of the DataSource should define a function that handles the updated data item(s), received as a function argument.
49+
When `batch` is disabled (default) and only one data item can be updated at a time, the updated data item is received as an object in `e.data`. If `batch` is enabled and multiple data items can be
50+
updated, they are received as an array of objects in `e.data.models`. Again, the `success` or `error` method of the function argument must be executed at the end.
51+
52+
var dataSource = new kendo.data.DataSource({
53+
transport: {
54+
update: function (e) {
55+
// batch is enabled
56+
//var updateItems = e.data.models;
57+
// batch is disabled
58+
var updatedItem = e.data;
59+
60+
// save the updated item to the original datasource
61+
// ...
62+
63+
// on success
64+
e.success();
65+
// on failure
66+
//e.error("XHR response", "status code", "error message");
67+
}
68+
},
69+
error: function (e) {
70+
alert("Status: " + e.status + "; Error message: " + e.errorThrown);
71+
}
72+
});
73+
74+
### Create
75+
76+
The `create` function should perform a similar routine as `update`, with a couple of notable differences:
77+
78+
* The newly created data item(s) has no ID, so it must be added by the function script or returned by the remote service.
79+
* The newly created data item(s) must be returned in the `success` method **with their IDs assigned**.
80+
Otherwise the DataSource instance will operate with incorrect data and subsequent data operations can fail.
81+
82+
<!-- exit list -->
83+
84+
var dataSource = new kendo.data.DataSource({
85+
transport: {
86+
update: function (e) {
87+
// batch is disabled
88+
// generate appropriate data item ID and save the new items to the original datasource
89+
e.data.my_ID_field_name = 123;
90+
// ...
91+
92+
// on success return the new data items with IDs
93+
e.success(e.data);
94+
// on failure
95+
//e.error("XHR response", "status code", "error message");
96+
}
97+
},
98+
error: function (e) {
99+
// handle error
100+
alert("Status: " + e.status + "; Error message: " + e.errorThrown);
101+
}
102+
});
103+
104+
### Destroy
105+
106+
The `destroy` function receives the item(s) to be deleted in `e.data`, similar to `create` and `update`.
107+
The function should remove the provided items from the original datasource and return `success` or `error`.
108+
109+
var dataSource = new kendo.data.DataSource({
110+
transport: {
111+
destroy: function (e) {
112+
// remove items from the original datasource by using e.data
113+
114+
// on success
115+
e.success();
116+
// on failure
117+
//e.error("XHR response", "status code", "error message");
118+
}
119+
},
120+
error: function (e) {
121+
// handle error
122+
alert("Status: " + e.status + "; Error message: " + e.errorThrown);
123+
}
124+
});
125+
126+
### Complete example: Local CRUD Operations with the Kendo UI Grid
127+
128+
The following example uses the information above to demonstrate CRUD operations with simple Products data.
129+
"original datasource" signifies the sampleData variable, which is used to populate the Grid initially.
130+
All data operations are persisted in this variable, so that it can be used or submitted somewhere else.
131+
132+
<!DOCTYPE html>
133+
<html>
134+
<head>
135+
<meta charset="utf-8" />
136+
<title>Kendo UI Grid - CRUD operations with local data</title>
137+
138+
<style>html { font-size: 12px; font-family: Arial, Helvetica, sans-serif; }</style>
139+
<link href="http://cdn.kendostatic.com/2014.2.903/styles/kendo.common.min.css" rel="stylesheet" />
140+
<link href="http://cdn.kendostatic.com/2014.2.903/styles/kendo.default.min.css" rel="stylesheet" />
141+
142+
<script src="http://cdn.kendostatic.com/2014.2.903/js/jquery.min.js"></script>
143+
<script src="http://cdn.kendostatic.com/2014.2.903/js/kendo.web.min.js"></script>
144+
</head>
145+
<body>
146+
147+
<div id="grid"></div>
148+
149+
<script>
150+
var sampleData = [
151+
{ProductID: 1, ProductName: "Apple iPhone 5s", Introduced: new Date(2013, 8, 10), UnitPrice: 525, Discontinued: false, UnitsInStock: 10},
152+
{ProductID: 2, ProductName: "HTC One M8", Introduced: new Date(2014, 2, 25), UnitPrice: 425, Discontinued: false, UnitsInStock: 3},
153+
{ProductID: 3, ProductName: "Nokia 5880", Introduced: new Date(2008, 10, 2), UnitPrice: 275, Discontinued: true, UnitsInStock: 0}
154+
];
155+
156+
// custom logic start
157+
158+
var sampleDataNextID = sampleData.length + 1;
159+
160+
function getIndexById(id) {
161+
var idx,
162+
l = sampleData.length;
163+
164+
for (var j; j < l; j++) {
165+
if (sampleData[j].ProductID == id) {
166+
return j;
167+
}
168+
}
169+
return null;
170+
}
171+
172+
// custom logic end
173+
174+
$(document).ready(function () {
175+
var dataSource = new kendo.data.DataSource({
176+
transport: {
177+
read: function (e) {
178+
// on success
179+
e.success(sampleData);
180+
// on failure
181+
//e.error("XHR response", "status code", "error message");
182+
},
183+
create: function (e) {
184+
// assign an ID to the new item
185+
e.data.ProductID = sampleDataNextID++;
186+
// save data item to the original datasource
187+
sampleData.push(e.data);
188+
// on success
189+
e.success(e.data);
190+
// on failure
191+
//e.error("XHR response", "status code", "error message");
192+
},
193+
update: function (e) {
194+
// locate item in original datasource and update it
195+
sampleData[getIndexById(e.data.ProductID)] = e.data;
196+
// on success
197+
e.success();
198+
// on failure
199+
//e.error("XHR response", "status code", "error message");
200+
},
201+
destroy: function (e) {
202+
// locate item in original datasource and remove it
203+
sampleData.splice(getIndexById(e.data.ProductID), 1);
204+
// on success
205+
e.success();
206+
// on failure
207+
//e.error("XHR response", "status code", "error message");
208+
}
209+
},
210+
error: function (e) {
211+
// handle data operation error
212+
alert("Status: " + e.status + "; Error message: " + e.errorThrown);
213+
},
214+
pageSize: 10,
215+
batch: false,
216+
schema: {
217+
model: {
218+
id: "ProductID",
219+
fields: {
220+
ProductID: { editable: false, nullable: true },
221+
ProductName: { validation: { required: true } },
222+
Introduced: { type: "date" },
223+
UnitPrice: { type: "number", validation: { required: true, min: 1} },
224+
Discontinued: { type: "boolean" },
225+
UnitsInStock: { type: "number", validation: { min: 0, required: true } }
226+
}
227+
}
228+
}
229+
});
230+
231+
$("#grid").kendoGrid({
232+
dataSource: dataSource,
233+
pageable: true,
234+
toolbar: ["create"],
235+
columns: [
236+
{ field: "ProductName", title: "Mobile Phone" },
237+
{ field: "Introduced", title: "Introduced", format: "{0:yyyy/MM/dd}", width: "200px" },
238+
{ field: "UnitPrice", title: "Price", format: "{0:c}", width: "120px" },
239+
{ field: "UnitsInStock", title:"Units In Stock", width: "120px" },
240+
{ field: "Discontinued", width: "120px" },
241+
{ command: ["edit", "destroy"], title: "&nbsp;", width: "200px" }
242+
],
243+
editable: "inline"
244+
});
245+
});
246+
</script>
247+
248+
</body>
249+
</html>
250+
251+
## CRUD Operations with Remote Data
252+
253+
Coming soon. Please refer to the [DataSource API](/api/javascript/data/datasource).

0 commit comments

Comments
 (0)