Using the Progress Data Source for NativeScript and Angular

Using the Progress Data Source for NativeScript and Angular

Description

The Progress Data Source is an npm module that provides seamless integration between client apps built with the Angular framework (that is, NativeScript and Angular web apps) and a Progress Data Object Service. It is available as an npm package on http://www.npmjs.com, which you can download and use in your NativeScript app or your web app.

The Data Source module allows you to access data as well as to perform CRUD operations on a data resource from a supported Data Object Service. It is a TypeScript implementation. Therefore, along with JavaScript code, a declaration file is also provided in the package. It defines the module’s types and function signatures.

The declaration file declares two classes:

DataSource — This provides the integration layer to access the remote data resource. (Internally, it supports access to the JSDO.)

DataSourceOptions — This provides options to a Data Source instance.

DataSourceOptions Properties

Property	Type	Description
countFnName?	string	The name of the remote invoke operation in the BusinessEntity that returns the total number of records in the data set. Used when server paging is performed.
filter?	any	Use it to specify client-side filtering of data. Similar to the filter property of the kendo.data.DataSource class. Example: filter: { field: "State", operator: "eq", value: "MA" }
jsdo	progress.data.JSDO	This property is required. It specifies the JSDO instance, which provides access to the resources of a Progress Data Object Service. All other properties of the DataSourceOptions class are optional.
mergeMode?	number	An integer that represents a merge mode to use.Possible values are: progress.data.JSDO.MODE_APPEND progress.data.JSDO.MODE_MERGE progress.data.JSDO.MODE_REPLACE The default value is MODE_MERGE.
readLocal?	boolean	If true, the read method does not perform a read operation on the remote service (if there is existing local data), but just returns the local data. If false (the default), the read method allows access to data on the remote service. It is useful to set readLocal to true for a child Data Source, when you develop a hierarchical app, for example.
skip?	number	Use it to specify how many records in the result set must be skipped before a page of data is returned.
sort?	any	Use this object to specify sorting of data. Similar to the sort property of the kendo.data.DataSource class. Example: sort: { field: "State", dir: "desc" },
tableRef?	string	It refers to the temp table that is to be accessed as a resource. Note: This property is required only if the specified jsdo represents a multi-table DataSet.
top?	number	Use it to specify the number of records to be returned from the result set.

DataSource Functions

Table 5. DataSource Functions
Function/API	Description	Input	Output
read(params?: progress.data.FilterOptions): Observable<DataResult>	It asynchronously retrieves data from the remote data resource. (Internally, it calls the jsdo.fill() method.)	progress.data.FilterOptions: interface FilterOptions { filter?: any; id?: any; skip?: number; sort?: any; top?: number; } The data retrieved is based on the specified filter property. If none of the optional parameters is specified, then all the data is retrieved.	Returns an Observable. If it succeeds, the observer's next() function returns an array of record objects along with the total number of record objects returned. For a failure, the observer's error() function returns an Error object containing an error message.
getData(): <Array<object>>	It returns an array of record objects that currently resides in local memory	NA	Returns an array of record objects.
create(data: object): object	It creates a new record in local memory.	data: An object that contains the details of the new record.	Returns the new record on success. On failure, an exception is thrown.
findById(id: string): object	It returns a copy of the record with the specified ID.	id Note: The existing implementation of the function uses JSDO's internal _id as the id property.	Returns the record with the specified ID. On failure, it returns null.
update(data: any): boolean	It updates a record in local memory.	data: An object that contains the updated details for the record.	Returns true on success. Else returns false.
remove(data: any): boolean	It deletes a record from local memory.	data: An object with a valid id of the record to be deleted.	Returns true if successful. Else returns false.
hasCUDSupport(): boolean	It indicates whether CUD (Create, Update and Delete) support is available in the underlying JSDO.	NA	Returns true if CUD support is available. Else returns false.
hasSubmitSupport(): boolean	It indicates whether the underlying JSDO has Submit support (that is, provides a Submit operation).	NA	Returns true if the corresponding JSDO has Submit support. Otherwise, returns false.
saveChanges(): Observable<Array<object>>	It synchronizes the Data Object service with all the record changes (CUD) pending in local memory. It is an asynchronous call.	NA	Returns an Observable. If it succeeds, the observer's next() function returns an object containing all changed rows. For a failure, the observer's error() function returns an Error object containing an error message.

Example

The following example illustrates the usage of some Data Source APIs in a NativeScript Master Detail starter template (tns-template-master-detail-progress-ng) that is meant to access the Data Object resource, Customer.

To use the DataSource and the DataSourceOptions classes in a NativeScript app, first import the classes in your service file (Customer.Service.ts, which takes care of retrieving and updating data), as shown below:

import { DataResult, DataSource, DataSourceOptions } from "@progress/jsdo-nativescript";

Next, add the imported DataSource class as a property and then instantiate it:

export class CustomerService {
private dataSource: DataSource;
createSession(callback) {
progress.data.getSession({
serviceURI,
catalogURI,
authenticationModel: 'anonymous'
}).then(() => {
this.dataSource = new DataSource({
jsdo: new progress.data.JSDO({
name: 'Customer'
})
});
this.readCustomers(callback);
}, () => {
console.log('Error while creating session.');
});
}

As you can see, 'Anonymous' is configured as the authentication model.

Then, you can use the Data Source APIs as per your needs. For example, the following lines of code implement the read API to read data from the Customer resource:

readCustomers(callback) {
this.dataSource.read({
filter: {
field: 'State',
operator: 'eq',
value: 'HI'
}
}).subscribe((myData: DataResult) => {
callback(myData.data);
});
}

Again, to create a new record in the backend Customer resource, the following code snippet is useful:

dataSource.create(<object for new record>)
dataSource.saveChanges().subscribe((myData) => {
// Code for successful operation
}, (error: Error) => {
// Code to handler error
);

The following lines show how you can implement the update API:

dataSource.update(<object for existing record - includes _id property>)
dataSource.saveChanges().subscribe((myData) => {
// Code for successful operation
}, (error: Error) => {
// Code to handler error
);

Finally, the remove API can be used as follows:

dataSource.remove(<object for existing record - includes _id property>)
dataSource.saveChanges().subscribe((myData) => {
// Code for successful operation
}, (error: Error) => {
// Code to handler error
);