Skip to content

Commit

Permalink
Sync with Kendo UI Professional
Browse files Browse the repository at this point in the history
  • Loading branch information
kendo-bot committed Oct 9, 2023
1 parent 8c6997a commit 66e29be
Show file tree
Hide file tree
Showing 20 changed files with 527 additions and 405 deletions.
40 changes: 20 additions & 20 deletions docs/framework/datasource/crud.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
---
title: CRUD Data Operations
page_title: CRUD Data Operations - Kendo UI for jQuery DataSource
description: "Learn how to use the Kendo UI for jQuery DataSource component for the create, read, update, and destroy (CRUD) data operations of your JavaScript widgets."
description: "Learn how to use the Kendo UI for jQuery DataSource component for the create, read, update, and destroy (CRUD) data operations of your JavaScript components."
slug: cruddataoperations_kendoui_datasourcecomponent
position: 5
---

# CRUD Data Operations

The [Kendo UI DataSource component](https://demos.telerik.com/kendo-ui/datasource/index) fully supports CRUD (Create, Read, Update, Destroy) data operations.
The [Kendo UI DataSource component](https://demos.telerik.com/kendo-ui/datasource/index) supports all CRUD (Create, Read, Update, Destroy) data operations.

However, it must be combined with a user interface or another Kendo UI widget such as the Grid, ListView, or other. Even though the examples in this article use the Grid as a sample, you can apply the configurations to any other widget or scenario.
However, it must be combined with a user interface or another Kendo UI component such as the Grid, ListView, or other. Even though the examples in this article use the Grid as a sample, you can apply the configurations to any other component or scenario.

## Sample Projects and Examples

Expand All @@ -22,13 +22,13 @@ However, it must be combined with a user interface or another Kendo UI widget su

The DataSource component can work with local data or remote data. In both cases, the CRUD operations are managed by the `transport` configuration of the DataSource.

`transport` is a JavaScript object that can be configured to execute predefined functions or make requests to predefined URLs on certain events. For more information, refer to the [`transport` API documentation](/api/javascript/data/datasource/configuration/transport).
`transport` is a JavaScript object that can be configured to execute predefined functions or make requests to predefined URLs on some events. For more information, refer to the [`transport` API documentation](/api/javascript/data/datasource/configuration/transport).

> You have to define all transport actions (read, update, create, destroy) in the same way—for example, as functions (when using local or custom transport), or as objects (when using remote transport). It is not possible to mix the two configuration alternatives.
> You have to define all transport actions (read, update, create, destroy) in the same way—for example, as functions (when using local or custom transport), or as objects (when using remote transport). Don't mix the two configuration alternatives.
## Setting the Schema

The `schema` of the DataSource is responsible for a number of data-connectivity actions. For more information, refer to the [`schema` API documentation](/api/javascript/data/datasource/configuration/schema).
The `schema` of the DataSource handles some data-connectivity actions. For more information, refer to the [`schema` API documentation](/api/javascript/data/datasource/configuration/schema).

The `schema` configuration defines the following fields and field types:

Expand All @@ -40,7 +40,7 @@ The `schema` configuration defines the following fields and field types:

You have to configure `id` for both local and remote data scenarios. You can only skip the `id` definition when all data fields are of the string type and editing is disabled.

The field that is used as a model ID has default values that are used by the DataSource component to identify new items. If the value of an item in the data set matches the default value, it will be considered a new item.
The field that is used as a model ID has default values that are used by the DataSource component to locate new items. If the value of an item in the data set matches the default value, it will be used as a new item.

The default values per field type are:

Expand All @@ -52,13 +52,13 @@ The `schema` configuration defines the following fields and field types:
"default": ""
```
The value of the denoted field in `schema.model.id` will also be set to the field with an `id` name in the actual data object. The field with the `id` name is a reserved field for the DataSource and will always be populated with the default value for its type or with the data from the actual data that is supplied by the developer.
The value of the denoted field in `schema.model.id` will also set the field with an `id` name in the same data object. The field with the `id` name is a reserved field for the DataSource and will always be populated with the default value for its type or with the data from the supplied by the developer data.
* The `key`, which points to the data items array in `schema.data`—Required when the data does not represent a plain array of objects or JSON.
## Setting the Local CRUD Operations
The following information is applicable to scenarios in which the data is already available on the client, or when you will have to take care of its retrieval and submission and the DataSource will not make any HTTP requests on its own.
The following information applies to scenarios in which the data is already available on the client, or when you will have to take care of its retrieval and submission and the DataSource will not make any HTTP requests on its own.
### Local Read Operations
Expand Down Expand Up @@ -88,7 +88,7 @@ Executing the `success` method of the `read` function argument populates the Dat
The `update` configuration setting of the DataSource defines a function that handles the updated data items which are received as a function argument. When `batch` is disabled, as it is by 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 updated, they are received as an array of objects in `e.data.models`. You have to execute the `success` or `error` method of the function argument at the end.
> * The Kendo UI DataSource uses the `ID` value to determine whether a data item is new or existing.
> * If the `ID` value is `zero`, it is assumed that the data item is new so the `create` function is executed.
> * If the `ID` value is `zero`, the data item will be used as new so the `create` function is executed.
> * If you need to use zero `ID` values, then change the [`defaultValue`](/api/javascript/data/model/methods/define) of the ID field to `-1` (minus one) in
[`schema.model.fields`](/api/javascript/data/datasource/configuration/schema.model).
Expand Down Expand Up @@ -119,7 +119,7 @@ The `update` configuration setting of the DataSource defines a function that han
The `create` function performs a similar routine as `update` with the following differences:
* The newly created data items have no `ID` so they must be added by the function script or returned by the remote service.
* The newly created data items must be returned in the `success` method with their IDs assigned. Otherwise, the DataSource instance will operate with incorrect data and subsequent data operations can fail.
* The newly created data items must be returned in the `success` method with their IDs assigned. Otherwise, the DataSource instance will run with incorrect data and later data operations can fail.
* If the [`schema.data`](/api/javascript/data/datasource/configuration/schema.data) configuration is set, the `success` method receives the created data item in an object with the same structure as the object that is passed to the `success` method of the `read` function. For more information, refer to the following example and to the previous section on [local update operations](#local-update-operations).
<!-- exit list -->
Expand Down Expand Up @@ -149,7 +149,7 @@ The `create` function performs a similar routine as `update` with the following
### Local Destroy Operations
Similar to `create` and `update`, the `destroy` function receives the items that will be deleted in `e.data`. The function removes the provided items from the original DataSource and returns `success` or `error`.
Like `create` and `update`, the `destroy` function receives the items that will be deleted in `e.data`. The function removes the provided items from the original DataSource and returns `success` or `error`.
var dataSource = new kendo.data.DataSource({
transport: {
Expand Down Expand Up @@ -187,7 +187,7 @@ If any of the `transport` actions (read, update, create, destroy) fails, then yo
### Local CRUD Operations Example
The following example is the complete implementation based on the previous information and demonstrates CRUD operations with simple **Products** data. `original datasource` signifies the `sampleData` variable which is used to populate the Grid initially. All data operations are persisted in this variable so that it can be used or submitted somewhere else. Avoid using an [`ObservableArray`](/api/javascript/data/observablearray) instead of a plain JavaScript array in the example. The Kendo UI DataSource will wrap the provided plain array and transform it to a collection of [`ObservableObjects`](/api/javascript/data/observableobject) automatically.
The following example is the complete implementation based on the previous information and demonstrates CRUD operations with simple **Products** data. `original datasource` signifies the `sampleData` variable which is used to populate the Grid initially. All data operations are persisted in this variable so that it can be reused or submitted later. Avoid using an [`ObservableArray`](/api/javascript/data/observablearray) instead of a plain JavaScript array in the example. The Kendo UI DataSource will wrap the provided plain array and transform it to a collection of [`ObservableObjects`](/api/javascript/data/observableobject) automatically.
```dojo
<style>html { font: 12px sans-serif; }</style>
Expand Down Expand Up @@ -294,21 +294,21 @@ The following example is the complete implementation based on the previous infor

## Setting the Remote CRUD Operations

The following information is applicable to scenarios in which you have to retrieve the data from and submit it to a remote data service through HTTP requests that are made by the Kendo UI DataSource.
The following information applies to scenarios in which you have to retrieve the data from and submit it to a remote data service through HTTP requests made by the Kendo UI DataSource.

CRUD operations with remote data rely on server code to perform the read, update, create, and destroy actions. Instead of configuring client functions, the `transport` of the DataSource defines remote service URLs and the expected format in which the data has to be sent and received. Theoretically, similar to the previous examples that use local data, you can use remote CRUD operations with `transport` functions but this is rarely required.
CRUD operations with remote data rely on server code to perform the read, update, create, and destroy actions. Instead of configuring client functions, the `transport` of the DataSource defines remote service URLs and the expected format for sending and receiving the data. Theoretically, like the previous examples that use local data, you can use remote CRUD operations with `transport` functions but this is not a common scenario.

Each of the CRUD operation settings&mdash;read, update, create, destroy&mdash;provides the following common `transport` settings that you have to set accordingly. For more information, refer to the [API of the Kendo UI DataSource](/api/javascript/data/datasource).
Each of the CRUD operation settings&mdash;read, update, create, destroy&mdash;provides the following common `transport` settings that you must set. For more information, refer to the [API of the Kendo UI DataSource](/api/javascript/data/datasource).

* The client request `type` can be `"get"` or `"post"`.
* Additional optional `data` parameters can be sent to the server if needed.
* You can send additional optional `data` parameters to the server if needed.
* The client request and expected server response `dataType` can be `"json"`, `"jsonp"`, `"odata"`, etc.

### Remote Read Operations

The `read` service defined by the DataSource `transport` returns data in the expected JSON, JSONP, XML, or oData format. By default, the expected format is JSON. If the response is not a plain array of objects, you have to define a [`schema`](/api/javascript/data/datasource/configuration/schema) which will describe the structure of the response and [where the data is](/api/javascript/data/datasource/configuration/schema.data).

The following example uses a `read` transport configuration. The assumed server response is a plain JSON array of objects.
The following example uses a `read` transport configuration. The required server response is a plain JSON array of objects.

/* Server response:

Expand Down Expand Up @@ -535,7 +535,7 @@ If any of the `transport` actions (read, update, create, destroy) fails and erro

> The two approaches cannot be combined, that is, custom errors can be provided only with a `200` HTTP status code.
When an `error` event is fired, the DataSource does not process any data items which may also be part of the server response. For example, if an update action fails due to conflicting edits and the data needs to be refreshed from the server, call the [`read`](/api/javascript/data/datasource/methods/read) method of the DataSource in the error handler. Sending the new data together with the error response will not populate the DataSource with the new values.
When an `error` event is fired, the DataSource does not process any data items that are part of the server response. For example, if an update action fails due to conflicting edits and the data needs to be refreshed from the server, call the [`read`](/api/javascript/data/datasource/methods/read) method of the DataSource in the error handler. Sending the new data together with the error response will not populate the DataSource with the new values.

The following example demonstrates a standard error.

Expand Down Expand Up @@ -595,7 +595,7 @@ The following example demonstrates a custom error.

When you use custom transport, the create, update, and delete operations will be handled by the [`transport.submit`](/api/javascript/data/datasource/configuration/transport.submit) function in a single batch. You are also required to define `transport.read` as a function. The `transport.create`, `transport.update`, and `transport.delete` operations will not be executed in this case.

> In order for the defined function to invoke a single request for all read, create, update, and delete operation, set the DataSource in its [batch mode](/api/javascript/data/datasource#configuration-batch).
> For the defined function to invoke a single request for all read, create, update, and delete operation, set the DataSource in its [batch mode](/api/javascript/data/datasource#configuration-batch).
```dojo
<script>
Expand Down
8 changes: 4 additions & 4 deletions docs/framework/datasource/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,16 @@ position: 1

The [Kendo UI DataSource component](https://demos.telerik.com/kendo-ui/datasource/index) plays a central role in all web applications built with Kendo UI for jQuery.

The DataSource is an abstraction for using local data (arrays of JavaScript objects) or remote data (web services returning JSON, JSONP, [oData](http://www.odata.org/), or XML). The DataSource fully supports CRUD (Create, Read, Update, Destroy) data operations and provides both client-side and server-side support for sorting, paging, filtering, grouping, and aggregates.
The DataSource is an abstraction for using local data (arrays of JavaScript objects) or remote data (web services returning JSON, JSONP, [oData](http://www.odata.org/), or XML). The DataSource supports CRUD (Create, Read, Update, Destroy) data operations and provides both client-side and server-side support for sorting, paging, filtering, grouping, and aggregates.

> It is a known limitation that you cannot name a DataSource field "data".
> A known limitation is the inability to name a DataSource field "data".
## Functionality and Features

* [DataSource Operations]({% slug datasourceoperations_kendoui_datasourcecomponent %})&mdash;The Kendo UI for jQuery DataSource provides both client-side and server-side support for sorting, paging, filtering, grouping, and aggregates.
* [CRUD Operations]({% slug cruddataoperations_kendoui_datasourcecomponent %})&mdash;The DataSource component fully supports CRUD (Create, Read, Update, Destroy) data operations.
* [CRUD Operations]({% slug cruddataoperations_kendoui_datasourcecomponent %})&mdash;The DataSource component supports CRUD (Create, Read, Update, Destroy) data operations.
* [CORS Operations]({% slug corsdatafetching_anotherdomain_datasourcecomponent %})&mdash;With the DataSource, you can also perform Cross-Origin Resource Sharing as described in Todd Anglin's blog post from October 3, 2011.
* [Offline Support]({% slug offlinesupport_kendoui_datasourcecomponent %})&mdash;The DataSource operates in an offline mode which enables data-bound Kendo UI widgets to function without an active server connection.
* [Offline Support]({% slug offlinesupport_kendoui_datasourcecomponent %})&mdash;The DataSource operates in an offline mode which enables data-bound Kendo UI components to function without an active server connection.
* [Hierarchical DataSource]({% slug overview_hierarchical_datasourcecomponent %})&mdash;The `HierarchicalDataSource` component allows you to represent hierarchical data.

## Next Steps
Expand Down
6 changes: 3 additions & 3 deletions docs/framework/templates/essentials.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The `#` (hash) sign allows you to:
* Mark areas that will be replaced by data during the template execution.
* Signify the beginning and end of custom JavaScript code within the template.

>tip While other templating libraries include shorthand, like `{ each }`, Kendo UI does not deliver helper syntax for loops and opts for using normal JavaScript instead of custom syntax sugar because it is faster and easier for JavaScript developers.
>tip While other template libraries include shorthand, like `{ each }`, Kendo UI does not deliver helper syntax for loops and opts for using normal JavaScript instead of custom syntax sugar. This is faster and easier for JavaScript developers.
To use the hash syntax, apply any of the following approaches:
* Render values as HTML (`#= #`).
Expand All @@ -29,7 +29,7 @@ To use the hash syntax, apply any of the following approaches:

When you use the Kendo UI template architecture while having hash characters inside your application or website content, consider the following specifics:

* If your template includes a `#` character literal, which is not part of a binding expression and is not a script code marker, you must escape that character. Otherwise, it will cause a template compilation error. For example, an error will be thrown if you use a `#` inside a URL hyperlink or a CSS color value.
* If your template includes a `#` character literal, which is not part of a binding expression and is not a script code marker, you must escape that character. Otherwise, it will cause a template compilation error. For example, an error will appear if you use a `#` inside a URL hyperlink or a CSS color value.

In JavaScript strings, you can escape the `#` literal with `\\\\#`. In external HTML script templates, you can escape the `#` literal with `\\#`.

Expand Down Expand Up @@ -87,7 +87,7 @@ The following example demonstrates the output if, in the same scenario, you have

## Handling External Templates and Expressions

Normally, templates include expressions. While some templating frameworks invent their own re-implementation of JavaScript to provide expression sugar at the cost of performance, the Kendo UI Templates allow the execution of normal JavaScript inside templates thus favoring performance.
Normally, templates include expressions. While some template frameworks invent their own re-implementation of JavaScript to provide expression sugar at the cost of performance, the Kendo UI Templates allow the execution of normal JavaScript inside templates thus favoring performance.

The following example demonstrates how to display a list of items by using JavaScript and Kendo UI Templates.

Expand Down
Loading

0 comments on commit 66e29be

Please sign in to comment.