skip to main content
OpenEdge Mobile 11.5.1 Updates : JSDO dialect of the Kendo UI DataSource
 

JSDO dialect of the Kendo UI DataSource

To provide data to a Kendo UI widget, such as a Kendo UI Grid, you use a Kendo UI DataSource. This is a JavaScript class (kendo.data.DataSource) that allows you to define an instance to provide either local data values or a remote data service of some type that you define using various configuration properties. The DataSource configuration for a remote data service primarily defines the transport options for reading and modifying the data and the schema of the data. For more information, see the Kendo UI documentation on the kendo.data.DataSource.
Although you can define a DataSource to access virtually any remote data service, the Telerik Kendo UI and Backend Services internally support different dialects of the Kendo UI DataSource, each of which supports specialized transport and schema definitions for accessing a given remote data service. Thus, the JavaScript Data Object dialect of the Kendo UI DataSource supports access to the JSDO as a remote data service. In doing so, it takes advantage of the built-in data management features of the JSDO and its schema as defined by a JSDO catalog. The JSDO dialect of the Kendo UI DataSource therefore serves a similar function on the Telerik Platform as JSDO Services do in the Mobile App Builder in previous OpenEdge releases.
The JSDO dialect of the Kendo UI DataSource supports:
*The Kendo UI Grid and other Kendo UI widgets in much the same way as other dialects and custom instantiations of the Kendo UI DataSource. However, some standard DataSource property and method behavior is implemented based on a transport that defines a JSDO instance as its remote data service.
*Access to a single-table JSDO instance or any single table from a multi-table JSDO instance—using a separate DataSource for each table of a shared multi-table JSDO to show master-detail relationships.
*JSDO dialect transport properties: jsdo, tableRef, and countFnName, which specify, respectively, the JSDO configured for the DataSource, the name of the JSDO table that the DataSource accesses (optional for single-table JSDOs), the name of the JSDO invoke method that the DataSource must call to return the total number of records in the server result set for the JSDO table (required only for server paging).
*Pre-configured DataSource CRUD operations using the individual JSDO CRUD or submit operations already defined for the JSDO instance—there is no need to configure each DataSource CRUD operation individually.
*Initial values for create operations, as defined for the JSDO instance.
*The option to configure a DataSource to instantiate its own JSDO for private, single-table access, as well as to share an existing JSDO instance.
*Access to the JSDO instance directly in DataSource event handlers or Promise deferred functions, for example, to call addRecords( ), the local storage APIs, or invoke methods on the JSDO.
*The standard sync( ) method on the DataSource, which calls the JSDO saveChanges( ) method, depending on a user's interaction with the connected Kendo UI widget.
*The standard batch configuration property on the DataSource, which indicates if the JSDO calls saveChanges( ) to invoke a submit operation (if available) to send a group of changes across the network or to invoke each Mobile create, update, and delete operation individually across the network.
*The standard serverPaging, serverFiltering, and serverSorting configuration properties of the DataSource, which allow a remote data service to manage the paging, filtering, and sorting features (respectively) of Kendo UI. If any or all of these server properties are set to true, the JSDO passes the corresponding property settings for these features to the Mobile read operation to be managed on the server. If any or all of these server properties are set to false (the default), the DataSource manages the corresponding features in its own local memory using the data that has already been returned by the Mobile read operation.
*A generic JSDO server error message for any single Mobile create, update, delete, or submit operation that returns a server error, allowing you to inspect the XHR object for details of the error or errors (for a submit operation) returned.
*The progress.data.JSDOSession class (described later) to create a JSDO login session for the DataSource that is validated with either Anonymous, Basic or Form-based authentication over HTTP or HTTPS.
Following is a sample Kendo UI DataSource instantiation that shows specific configuration features of the JSDO dialect, shown in bold:
myjsdo = new progress.data.JSDO({ name: 'dsCustomerOrd' });

var dataSource = new kendo.data.DataSource( {
type: "jsdo",
serverPaging: true,
serverFiltering: true,
filter: { field: "State", operator: "eq", value: "MA" },
serverSorting: true,
sort: { field: "State", dir: "desc" },
transport: {
jsdo: myjsdo,
tableRef: "ttCustomer",
countFnName: "count",
},
/* batch: true, */
error: function(e) {
var obj, dsErrors, error = "", i;

console.log('Error: ', e);
if (e.errorThrown) {
error = "\n" + e.errorThrown.message;
}
if (e.xhr && e.xhr.response) {
try {
obj = JSON.parse(e.xhr.response);
dsErrors = obj.dsCustomerOrd["prods:errors"];

if (obj._retVal) {
error += "\n" + obj._retVal;
} else if (obj._errors instanceof Array &&
obj._errors.length > 0) {
for (i = 0; i < obj._errors.length; i += 1) {
error += "\n" + obj._errors[i]._errorNum
+ " " + obj._errors[i]._errorMsg;
}
}
else if (dsErrors &&
dsErrors.ttCustomer instanceof Array) {
for (i = 0; i < obj.dsErrors.ttCustomer.length; i += 1)
{
error += "\n" +
dsErrors.ttCustomer[i]["prods:error"];
}
}
}
catch(e) {
alert("Error while parsing response: " + e.xhr.response);
}
}
alert("Error returned from server: " + error);
e.preventDefault();
}
} );
Note that this example DataSource accesses a JSDO that is instantiated prior to instantiating the DataSource itself, which also assumes that a JSDO login session has been created and a JSDO catalog for a multi-table ProDataSet has been added to the session for the JSDO. OpenEdge supports a new progress.data.JSDOSession class to manage JSDO sessions for use with the Kendo UI DataSource. For more information, see Session management updates.
Following is a brief description of the configuration options specified in the sample JSDO dialect of the Kendo UI DataSource shown above:
*Setting the standard type property to "jsdo" — Specifies that the Kendo UI DataSource is being instantiated for the JSDO dialect.
*Setting the standard serverPaging, serverFiltering, or serverSorting properties to true — When any of these properties is set to true, the respective DataSource feature is handled by Business Entity resource accessed by the JSDO when the Mobile read operation is invoked. For example, if serverFiltering is true, the settings from the filter property on the DataSource (or from any more recent invocation of the filter( ) method on the DataSource) are included in the JSON Filter Pattern that is passed to the filter parameter of the Mobile read operation. If serverFiltering is false, all filtering of data is handled by the DataSource in its internal memory. The same is true of the remaining server* configuration properties and their related property settings, like the pageSize property for serverPaging and the sort property for serverSorting.
If none of these properties are true, the JSDO returns all records, for the single (or specified) table of the JSDO to the DataSource, which manages any paging, filtering, and sorting using its own internal memory.
Note: The JSDO dialect of the DataSource does not support the serverGrouping and serverAggregates configuration properties in this release. That is, any data grouping and aggregate features of Kendo UI are managed in Kendo UI internal memory.
*Setting the JSDO dialect jsdo transport property — The jsdo property specifies the JSDO that is accessed by the DataSource. In the sample, an existing instance of the JSDO (myjsdo) is specified. You can also specify the name of a JSDO resource as a string, and the DataSource will create the JSDO instance for you. This is the same resource name you would use to create the JSDO yourself. In this sample, you would specify the jsdo value as "dsCustomerOrd".
*Setting the JSDO dialect tableRef transport property — Required only for a JSDO created for a resource that is a multi-table ProDataSet, the tableRef property specifies the name of the JSDO table whose data the DataSource handles. So, for an OpenEdge ProDataSet, you specify the name of the corresponding temp-table in the Business Entity (ttCustomer in the sample). If you want to access the data in all tables in the ProDataSet, you need to create a separate Kendo UI DataSource for each table accessed by the JSDO and attach it a Kendo UI widget appropriately.
*Setting the JSDO dialect countFnName transport property — The countFnName property specifies the name of the Business Entity invoke operation method that returns the total number of records in the server result to the Kendo UI DataSource when using server paging (serverPaging == true). For more information, see Updating Business Entities for new Mobile Apps in the Telerik Platform. Note that for a JSDO that reads data from a multi-table ProDataSet, this invoke method only returns the total number of records in the result set (in all pages) of the parent table.
*Setting the standard batch property — Specifies how record changes are processed when the sync( ) method is called on the DataSource, depending on the batch property setting (false by default). For this release of the JSDO dialect of the DataSource, if batch == true, the DataSource's JSDO must define a Mobile submit operation. The following table shows how the DataSource responds to the setting of its batch property, depending on whether a submit operation is defined in the JSDO:
Table 2. JSDO dialect response to the batch property setting on the DataSource
DataSource batch property setting
Does JSDO define a submit operation?
DataSource response when saving changes
false
No
The transport gets a change for a single record. This record change is sent to the server one record at a time, using the corresponding Mobile create, update, or delete operation (by calling saveChanges(false) on the JSDO).
true
No
Not supported in this release. The DataSource throws an exception if saving changes to the server with batch == true when the JSDO does not define a submit operation.
false
Yes
The transport gets a change for a single record. This record change is sent to the server one record at a time, using the Mobile submit operation (by calling saveChanges(true) on the JSDO).
true
Yes
The transport gets changes for one or more records in an array. All the changes are grouped by the JSDO and sent to the server using the Mobile submit operation (by calling saveChanges(true) on the JSDO).
Note: For a standard Kendo UI DataSource with batch == true, multiple record changes are grouped together so that all record changes of a given type (create, update, or destroy) are sent to the server at one time by the DataSource transport. However in this release, the transport for the JSDO dialect can only send the entire set of record changes (all create, update, and destroy changes together) in a single Mobile submit operation.
*Handling the parameter (e) returned by the DataSource error event handler function — The error event handler function is called when an error occurs while performing CRUD operations in the remote data service (JSDO in this case). An error can thus be returned when invoking the read( ) method or the sync( ) method on the DataSource.
The errorThrown, sender, status, and xhr properties of the event parameter (e) are set depending on the error returned. To process these errors, you can look at e.errorThrown.message and at the XmlHttpRequest (XHR) response for more information. The XHR response can have one of the following formats:
*An error message object
*An error message text
*A dataset structure with errors in the prods:errors property
Note that if an error occurs when invoking the DataSource sync( ) method when saving changes in the JSDO to the server, the following generic message is typically returned in e.errorThrown.message: "JSDO: Error while saving changes.". This message is returned if one or more errors occurs while saving JSDO changes, regardless of the batch property setting on the DataSource. So for example, if batch == true, and multiple errors occur for a single Mobile submit operation, this one error message is returned for all of them.
For a JSDO dialect read( ) or sync( ) call, you can explore the XHR response from the server for more information about any of these errors. There are two basic approaches you can use, when:
*Mobile create, read, update, and delete (CRUD) operations called on the JSDO process data without before-image support.
*Mobile CRUD and submit operations called on the JSDO process data with before-image support. In this case, error information can be included in one or more changed record objects that are returned for the request.
Submit operations always process data with before-image support. Note also that even when the DataSource invokes sync( ) for one record change operation at a time (with batch == false), it invokes a Mobile submit operation (if it is defined in the JSDO) for each record.
The error handler in the sample follows one or the other of these two approaches, as only one can occur for each DataSource request.
To locate and handle the errors for individual Mobile CRUD operations without before-image support, this XHR response contains any error information that is returned in the response property object returned in the JSDO request object from the JSDO saveChanges( ) operation (see the OpenEdge JSDO reference documentation for more information). The example error event handler function shows one example of how you can inspect the XHR response to handle error information returned in the response property object of the XHR, by accessing the _retVal and _errors properties of this object.
To locate and handle the errors for individual Mobile CRUD and submit operations with before-image support, you have to access a prods:errors property in the dataset structure (dsCustomerOrd) found in the same response property object. This property contains any application error information returned by the Business Entity for each temp-table record where a record change operation returned an error. The application error associated with each such record in this example is in dsCustomerOrd["prods:errors"].ttCustomer[i]["prods:error"]. Note that for multiple record change errors that are returned for a submit operation, the example shows how you can return them from the corresponding table array (ttCustomer[i]["prods:error"]). For individual CUD operations working with similar before-image data, there can be only one table record that provides this error information for each Mobile CUD operation. A Mobile read operation, of course, might also return errors in multiple table records.
In both cases, the sample concatenates error information at each level of detail for a given server request.