/*!
*
* Wijmo Library 5.20251.40
* https://developer.mescius.com/wijmo
*
* Copyright(c) MESCIUS inc. All rights reserved.
*
* Licensed under the End-User License Agreement For MESCIUS Wijmo Software.
* us.sales@mescius.com
* https://developer.mescius.com/wijmo/licensing
*
*/
/**
* {@module wijmo.odata}
* Provides classes that support the OData protocol, including the
* {@link ODataCollectionView} class.
*
* OData is a standardized protocol for creating and consuming data APIs.
* OData builds on core protocols like HTTP and commonly accepted
* methodologies like REST.
* The result is a uniform way to expose full-featured data APIs.
* (https://www.odata.org/)
*/
/**
*
*/
export declare var ___keepComment: any;
import { Event, EventArgs, RequestErrorEventArgs, CollectionView, PageChangingEventArgs, CollectionViewGroup, Aggregate } from 'wijmo/wijmo';
import * as mGrid from 'wijmo/wijmo.grid';
import * as mFilter from 'wijmo/wijmo.grid.filter';
import * as selfModule from 'wijmo/wijmo.odata';
export declare function softGrid(): typeof mGrid;
export declare function softFilter(): typeof mFilter;
interface IGroupAggregate {
binding: string;
aggregate: Aggregate;
alias: string;
}
export declare enum AggregatesServer {
sum = 1,
countdistinct = 2,
average = 3,
max = 4,
min = 5
}
/**
* Extends the {@link CollectionView} class to support loading and
* saving data from OData sources.
*
* You can use the {@link ODataCollectionView} class to load data from
* OData services and use it as a data source for Wijmo controls.
*
* In addition to full CRUD support you get all the {@link CollectionView}
* features including sorting, filtering, paging, and grouping.
* The sorting, filtering, and paging functions may be performed on the
* server or on the client.
*
* **Note** : grouping function can also be performed on server but only when OData version
* should be NET Core 7.0 or later. As OData added [aggregation support](https://devblogs.microsoft.com/odata/aggregation-extensions-in-odata-asp-net-core/)
* from OData 7.0.
*
* Refer to example {@sample Grid/Data-binding/ODataServerGroup/purejs} that loads
* grouped data from server and shows in {@link FlexGrid}.
*
* The code below shows how you can instantiate an {@link ODataCollectionView}
* that selects some fields from the data source and provides sorting on the
* client.
* Notice how the 'options' parameter is used to pass in initialization
* data, which is the same approach used when initializing controls:
*
* ```typescript
* import { ODataCollectionView } from 'wijmo/wijmo.odata';
* const url = 'http://services.odata.org/V4/Northwind/Northwind.svc/';
* const categories = new ODataCollectionView(url, 'Categories', {
* fields: ['CategoryID', 'CategoryName', 'Description'],
* sortOnServer: false
* });
* ```
*
* The example below uses an {@link ODataCollectionView} to load data from
* a NorthWind OData provider service, and shows the result in a
* {@link FlexGrid} control:
*
* {@sample Grid/Data-binding/ODataAPI/purejs Example}
*/
export declare class ODataCollectionView extends CollectionView {
_url: string;
_tbl: string;
_entityType: string;
_count: number;
_fields: string[];
_keys: string[];
_expand: string;
_dataTypes: any;
_sortOnServer: boolean;
_pageOnServer: boolean;
_filterOnServer: boolean;
_deferCommits: boolean;
_hasPendingChanges: boolean;
_showDatesAsGmt: boolean;
_inferDataTypes: boolean;
_dataTypesInferred: any;
_reviverBnd: any;
_jsonReviver: Function;
_filterDef: string;
_toGetData: any;
_loading: boolean;
_requestHeaders: any;
_odv: number;
_groupOnServer: boolean;
_grpLzyld: boolean;
_groupRefresh: boolean;
_virtualization: boolean;
static _allowServerGroup: {};
static _odvCache: {};
static _rxDate: RegExp;
/**
* Initializes a new instance of the {@link ODataCollectionView} class.
*
* @param url Url of the OData service (for example
* https://services.odata.org/Northwind/Northwind.svc/ ).
* @param tableName Name of the table (entity) to retrieve from the service.
* If not provided, a list of the tables (entities) available is retrieved.
* @param options JavaScript object containing initialization data (property
* values and event handlers) for the {@link ODataCollectionView}.
*/
constructor(url: string, tableName: string, options?: any);
/**
* Gets the name of the table (entity) that this collection is bound to.
*/
readonly tableName: string;
/**
* Gets or sets a string that represents the entity's data type on the server.
*
* This may be required to update data in some OData services.
*
* For more details, please see
* http://docs.oasis-open.org/odata/odata-json-format/v4.0/cs01/odata-json-format-v4.0-cs01.html#_Toc365464687.
*/
entityType: string;
/**
* Gets or sets an array containing the names of the fields to retrieve from
* the data source.
*
* If this property is set to null or to an empty array, all fields are
* retrieved.
*
* For example, the code below creates an {@link ODataCollectionView} that
* gets only three fields from the 'Categories' table in the database:
*
* ```typescript
* import { ODataCollectionView } from 'wijmo/wijmo.odata';
* const url = 'http://services.odata.org/V4/Northwind/Northwind.svc/';
* const categories = new ODataCollectionView(url, 'Categories', {
* fields: ['CategoryID', 'CategoryName', 'Description']
* });
* ```
*/
fields: string[];
/**
* Gets or sets an object containing request headers to be used when sending
* or requesting data.
*
* The most typical use for this property is in scenarios where authentication
* is required. For example:
*
* ```typescript
* import { ODataCollectionView } from 'wijmo/wijmo.odata';
* const url = 'http://services.odata.org/V4/Northwind/Northwind.svc/';
* const categories = new ODataCollectionView(serviceUrl, 'Categories', {
* fields: ['Category_ID', 'Category_Name'],
* requestHeaders: { Authorization: db.token }
* });
* ```
*/
requestHeaders: any;
/**
* Gets or sets an array containing the names of the key fields.
*
* Key fields are required for update operations (add/remove/delete).
*/
keys: string[];
/**
* Gets or sets a string that specifies whether related entities should
* be included in the return data.
*
* This property maps directly to OData's $expand option.
*
* For example, the code below retrieves all the customers and their
* orders from the database. Each customer entity has an "Orders"
* field that contains an array of order objects:
*
* ```typescript
* import { ODataCollectionView } from 'wijmo/wijmo.odata';
* const url = 'http://services.odata.org/V4/Northwind/Northwind.svc/';
* const customersOrders = new ODataCollectionView(url, 'Customers', {
* expand: 'Orders'
* });
* ```
*/
expand: string;
/**
* Gets or sets a custom reviver function to use when parsing JSON
* values returned from the server.
*
* If provided, the function must take two parameters (key and value),
* and must return the parsed value (which can be the same as the
* original value).
*
* For details about reviver functions, please refer to the documentation
* for the
* JSON.parse method.
*/
jsonReviver: Function;
/**
* Gets or sets a JavaScript object to be used as a map for coercing data types
* when loading the data.
*
* The object keys represent the field names and the values are {@link DataType} values
* that indicate how the data should be coerced.
*
* For example, the code below creates an {@link ODataCollectionView} and specifies
* that 'Freight' values, which are stored as strings in the database, should be
* converted into numbers; and that three date fields should be converted into dates:
*
* ```typescript
* import { ODataCollectionView } from 'wijmo/wijmo.odata';
* import { DataType } from 'wijmo/wijmo';
* const url = 'http://services.odata.org/V4/Northwind/Northwind.svc/';
* const orders = new ODataCollectionView(url, 'Orders', {
* dataTypes: {
* Freight: DataType.Number
* OrderDate: DataType.Date,
* RequiredDate: DataType.Date,
* ShippedDate: DataType.Date,
* }
* });
* ```
*
* This property is useful when the database contains data stored in
* formats that do not conform to common usage.
*
* In most cases you don't have to provide information about the
* data types, because the {@link inferDataTypes} property handles
* the conversion of Date values automatically.
*
* If you do provide explicit type information, the {@link inferDataTypes}
* property is not applied. Because of this, any data type information
* that is provided should be complete, including all fields of type
* Date.
*/
dataTypes: any;
/**
* Gets or sets a value that determines whether fields that contain
* strings that look like standard date representations should be
* converted to dates automatically.
*
* This property is set to true by default, because the {@link ODataCollectionView}
* class uses JSON and that format does not support Date objects.
*
* This property has no effect if specific type information is provided using
* the {@link dataTypes} property.
*/
inferDataTypes: boolean;
/**
* Gets or sets a value that determines whether dates should be adjusted
* to look like GMT rather than local dates.
*/
showDatesAsGmt: boolean;
/**
* Gets or sets a value that determines whether sort operations
* should be performed on the server or on the client.
*
* Use the {@link sortDescriptions} property to specify how the
* data should be sorted.
*
* The default value for this property is **true**.
*/
sortOnServer: boolean;
/**
* Gets or sets a value that determines whether paging should be
* performed on the server or on the client.
*
* Use the {@link pageSize} property to enable paging.
*
* The default value for this property is **true**.
*/
pageOnServer: boolean;
/**
* Gets or sets a value that determines whether filtering should be
* performed on the server or on the client.
*
* Use the {@link filter} property to perform filtering on the client,
* and use the {@link filterDefinition} property to perform filtering
* on the server.
*
* In some cases it may be desirable to apply independent filters
* on the client **and** on the server.
*
* You can achieve this by setting (1) the {@link filterOnServer} property
* to false and the {@link filter} property to a filter function (to enable
* client-side filtering) and (2) the {@link filterDefinition} property to
* a filter string (to enable server-side filtering).
*
* The default value for this property is **true**.
*/
filterOnServer: boolean;
/**
* Gets or sets a string containing an OData filter specification to
* be used for filtering the data on the server.
*
* The filter definition syntax is described in the
* OData documentation.
*
* For example, the code below causes the server to return records
* where the 'CompanyName' field starts with 'A' and ends with 'S':
*
* ```typescript
* view.filterDefinition = "startswith(CompanyName, 'A') and endswith(CompanyName, 'B')";
* ```
*
* Filter definitions can be generated automatically. For example, the
* {@link FlexGridFilter} component detects whether its data source is an
* {@link ODataCollectionView} and automatically updates both the
* {@link ODataCollectionView.filter} and {@link ODataCollectionView.filterDefinition}
* properties.
*
* Note that the {@link ODataCollectionView.filterDefinition} property is applied
* even if the {@link ODataCollectionView.filterOnServer} property is set to false.
* This allows you to apply server and client filters to the same collection,
* which can be useful in many scenarios.
*
* For example, the code below uses the {@link ODataCollectionView.filterDefinition}
* property to filter on the server and the {@link ODataCollectionView.filter}
* property to further filter on the client. The collection will show items with
* names that start with 'C' and have unit prices greater than 20:
*
* ```typescript
* import { ODataCollectionView } from 'wijmo/wijmo.odata';
* const url = 'http://services.odata.org/V4/Northwind/Northwind.svc/';
* const data = new ODataCollectionView(url, 'Products', {
* oDataVersion: 4,
* filterDefinition: 'startswith(ProductName, \'C\')', // server filter
* filterOnServer: false, // client filter
* filter: function(product) {
* return product.UnitPrice > 20;
* },
* });
* ```
*/
filterDefinition: string;
/**
* Updates the filter definition based on a known filter provider such as the
* {@link FlexGridFilter}.
*
* @param filterProvider Known filter provider, typically an instance of a
* {@link FlexGridFilter}.
*/
updateFilterDefinition(filterProvider: any): void;
/**
* Gets or sets a value that determines whether grouping should be performed on the server or on the client.
* This property should be set to true only when OData API support aggregation using Apply query.
*
* The default value for this property is false.
*/
groupOnServer: boolean;
_aggregates: string;
_aggQuery: string;
_iaq: IGroupAggregate[];
/**
* Gets or Sets the aggregates query which would parsed by the OData API and returns the aggregates as result.
*
* This property should be set when {@link groupOnServer} is set to true with groupDescriptions.
*
* Aggregates query should be in OData specified AggregationMethods format
*
* ```typescript
* // ODataCollectionView Instance
* let cv = new ODataCollectionView({
* groupOnServer: true,
* aggregates: `Quantity with sum as Quantity,UnitPrice with average as AggPrice`,
* groupDescriptions: ['State','City']
* });
*
* ```
*
*/
aggregates: string;
private _updateAggQuery;
/**
* Returns server-calculated aggregate value for a specified property and {@link CollectionViewGroup}.
*
* The {@link aggregates} property should be defined to get the server-calculated aggregate. If aggregates property is not defined, it will return empty value ''.
*
* @param columnBinding Name of the property to aggregate on.
* @param groupItem The {@link CollectionViewGroup} instance representing the group for which the aggregation is to be calculated.
* @param aggregate The type of {@link Aggregate} to compute, that should also be defined for specified `columnBinding` in {@link aggregates}
* @returns The calculated aggregate value.
*/
getGroupAggregate(columnBinding: string, groupItem: CollectionViewGroup, aggregate?: Aggregate): any;
/**
* Gets or Sets a value that detemines whether the group data should be loaded
* on demand or at once.
*
* The default value for this property is false and should be set to true only when {@link groupOnServer} is set to true.
*/
groupLazyLoading: boolean;
/**
* This method would allow to load the items for specified group {@link CollectionViewGroup} when {@link groupLazyLoading} is enabled.
* @param item {@link CollectionViewGroup} items to load the data.
*
*/
lazyLoadGroup(item: CollectionViewGroup): void;
/**
* Gets or sets the OData version used by the server.
*
* There are currently four versions of OData services, 1.0 through 4.0.
* Version 4.0 is used by the latest services, but there are many legacy
* services still in operation.
*
* If you know what version of OData your service implements, set the
* {@link oDataVersion} property to the appropriate value (1 through 4) when
* creating the {@link ODataCollectionView} (see example below).
*
* ```typescript
* import { ODataCollectionView } from 'wijmo/wijmo.odata';
* let url = 'https://services.odata.org/Northwind/Northwind.svc/';
* let categories = new ODataCollectionView(url, 'Categories', {
* oDataVersion: 1.0, // legacy OData source
* fields: ['CategoryID', 'CategoryName', 'Description'],
* sortOnServer: false
* });
* ```
*
* If you do not know what version of OData your service implements (perhaps
* you are writing an OData explorer application), then do not specify the
* version. In this case, the {@link ODataCollectionView} will get this information
* from the server. This operation requires an extra request, but only once
* per service URL, so the overhead is small.
*/
oDataVersion: number;
/**
* Gets a value that indicates the {@link ODataCollectionView} is
* currently loading data.
*
* This property can be used to provide progress indicators.
*/
readonly isLoading: boolean;
/**
* Gets or sets a value that causes the {@link ODataCollectionView} to
* defer commits back to the database.
*
* The default value for this property is **false**, which causes
* any changes to the data to be immediately committed to the database.
*
* If you set this property to **true**, it will automatically set the
* {@link trackChanges} property to true. After this, any changes to the
* data (including edits, additions, and removals) will be tracked but
* not committed to the database until you call the {@link commitChanges}
* method to commit the changes, or the {@link cancelChanges} method
* to discard all pending changes.
*
* For example:
* ```typescript
* import { ODataCollectionView } from 'wijmo/wijmo.odata';
*
* // create data source
* let url = 'https://services.odata.org/...';
* let view = new ODataCollectionView(url, 'Categories', {
* keys: [ 'ID' ]
* });
*
* // defer commits
* view.deferCommits = true;
*
* // handle commit/cancel changes buttons
* let btnCommit = document.getElementById('btn-commit') as HTMLButtonElement,
* btnCancel = document.getElementById('btn-cancel') as HTMLButtonElement;
* btnCommit.addEventListener('click', () => view.commitChanges());
* btnCancel.addEventListener('click', () => view.cancelChanges());
* view.hasPendingChangesChanged.addHandler((s, e) => {
* btnCommit.disabled = btnCancel.disabled = !view.hasPendingChanges;
* });
* ```
*/
deferCommits: boolean;
/**
* Occurs when the {@link ODataCollectionView} starts loading data.
*/
readonly loading: Event;
/**
* Raises the {@link loading} event.
*/
onLoading(e?: EventArgs): void;
/**
* Occurs when the {@link ODataCollectionView} finishes loading data.
*/
readonly loaded: Event;
/**
* Raises the {@link loaded} event.
*/
onLoaded(e?: EventArgs): void;
/**
* Loads or re-loads the data from the OData source.
*/
load(): void;
/**
* Occurs when there is an error reading or writing data.
*/
readonly error: Event;
/**
* Raises the {@link error} event.
*
* By default, errors throw exceptions and trigger a data refresh. If you
* want to prevent this behavior, set the {@link RequestErrorEventArgs.cancel}
* parameter to true in the event handler.
*
* @param e {@link RequestErrorEventArgs} that contains information about the error.
*/
onError(e: RequestErrorEventArgs): boolean;
/**
* Occurs when the value of the {@link hasPendingChanges} property changes.
*
* See also the {@link deferCommits} property.
*/
readonly hasPendingChangesChanged: Event;
/**
* Raises the {@link hasPendingChangesChanged} event.
*/
onHasPendingChangesChanged(e?: EventArgs): void;
/**
* Returns true if this object supports a given interface.
*
* @param interfaceName Name of the interface to look for.
*/
implementsInterface(interfaceName: string): boolean;
/**
* Override {@link commitNew} to add the new item to the database.
*/
commitNew(): void;
/**
* Override {@link commitEdit} to modify the item in the database.
*/
commitEdit(): void;
/**
* Override {@link remove} to remove the item from the database.
*
* @param item Item to be removed from the database.
*/
remove(item: any): void;
/**
* Commits all pending changes to the server.
*
* Changes are contained in the {@link itemsEdited}, {@link itemsAdded},
* and {@link itemsRemoved} collections, and are automatically cleared
* after they are committed.
*
* See also the {@link deferCommits} property.
*
* @param committed Optional callback invoked when the commit operation
* has been completed. The callback takes an **XMLHttpRequest**
* parameter contains information about the request results.
*/
commitChanges(committed?: (xhr: XMLHttpRequest) => void): void;
/**
* Cancels all changes by removing all items in the {@link itemsAdded},
* {@link itemsRemoved}, and {@link itemsEdited} collections,
* without committing them to the server.
*
* This method is used with the {@link deferCommits} property.
*/
cancelChanges(): void;
/**
* Gets a value that determines whether the {@link ODataCollectionView} has
* pending changes.
*
* See also the {@link deferCommits} property and the
* {@link commitChanges} and {@link cancelChanges} methods.
*/
readonly hasPendingChanges: boolean;
/**
* Gets the total number of items in the view before paging is applied.
* With groupLazyLoading, Gets the total number of available top-level groups count.
*/
readonly totalItemCount: number;
/**
* Gets the total number of pages.
*/
readonly pageCount: number;
/**
* Gets or sets the number of items to display on a page.
*/
pageSize: number;
/**
* Raises the {@link pageChanging} event.
*
* @param e {@link PageChangingEventArgs} that contains the event data.
*/
onPageChanging(e: PageChangingEventArgs): boolean;
_getPageView(): any[];
_performRefresh(): void;
_updateHasChanges(): void;
_storeItems(items: any[], append: boolean): void;
private _storeGrpItems;
private _expandedGroups;
protected _data: any[];
private _loadExpandedGroups;
private _getItemsPromise;
private _updateSubGroups;
private _loadSubGroupsData;
_updateExpandedGroups(item: CollectionViewGroup, isCollapsed: boolean): void;
private _getFilterGroupItems;
_getReadUrl(nextLink?: string): string;
_getReadParams(nextLink?: string, grpDef?: CollectionViewGroup | boolean): any;
protected _getFilterDefintion(item?: CollectionViewGroup): string;
protected _getAggregateParams(item?: CollectionViewGroup, nextLink?: string): any;
private _getGroupItems;
private _getItems;
private _currentGroupRequests;
private _currentRequests;
protected _grpItems: any[];
protected _grpItemCount: number;
_getData(nextLink?: string, grpDef?: CollectionViewGroup | boolean, xhrCallback?: Function): void;
private _convertToDbFormat;
private _reviver;
private _convertItem;
private _getInferredDataTypes;
private _getServiceUrl;
private _saa;
private _req;
private _getODataAggCompatiability;
private _getSchema;
private _getWriteUrl;
private _asODataFilter;
private _asODataValueFilter;
private _asEquals;
private _asODataConditionFilter;
private _asODataCondition;
private _asODataValue;
private _error;
private _encodeBatch;
}
/**
* Extends the {@link ODataCollectionView} class to support loading data on
* demand, using the {@link setWindow} method.
*
* The example below shows how you can declare an {@link ODataCollectionView}
* and synchronize it with a {@link wijmo.grid.FlexGrid} control to load the
* data that is within the grid's viewport:
*
* ```typescript
* // declare virtual collection view
* let view = new wijmo.odata.ODataVirtualCollectionView(url, 'Order_Details_Extendeds', {
* oDataVersion: 4
* });
*
* // use virtual collection as grid data source
* flex.itemsSource = view;
*
* // update data window when the grid scrolls (not require from 2024v2-HF version)
* flex.scrollPositionChanged.addHandler(() => {
* let rng = flex.viewRange;
* view.setWindow(rng.topRow, rng.bottomRow);
* });
* ```
*
* The {@link ODataVirtualCollectionView} class implements a 'data window' so only
* data that is actually being displayed is loaded from the server. Items that are
* not being displayed are added to the collection as null values until a call
* to the {@link setWindow} method causes them those items to be loaded.
*
* This 'on-demand' method of loading data has advantages when dealing with large
* data sets, because it prevents the application from loading data until it is
* required. But it does impose some limitation: sorting and filtering must be
* done on the server; grouping and paging are not supported.
*
* The example below uses an {@link ODataVirtualCollectionView} to load data from
* a NorthWind OData provider service. The collection loads data on-demant,
* as the user scrolls the grid:
*
* {@sample Grid/Data-binding/VirtualOData/purejs Example}
*
*
* Grouping function can also be performed on server but only when OData version
* should be NET Core 7.0 or later. As OData added [aggregation support](https://devblogs.microsoft.com/odata/aggregation-extensions-in-odata-asp-net-core/)
* from OData 7.0.
*
* Refer to example {@sample Grid/Data-binding/VirtualODataServerGroup/purejs} that loads
* grouped data from server virtually and shows in {@link FlexGrid}.
*/
export declare class ODataVirtualCollectionView extends ODataCollectionView {
_data: any[];
_start: number;
_end: number;
_refresh: boolean;
_loadOffset: number;
_toSetWindow: any;
_pendingRequest: XMLHttpRequest;
_requestCanceled: Event;
_firstLoad: boolean;
/**
* Initializes a new instance of the {@link ODataVirtualCollectionView} class.
*
* @param url Url of the OData service (for example
* https://services.odata.org/Northwind/Northwind.svc/ ).
* @param tableName Name of the table (entity) to retrieve from the service.
* If not provided, a list of the tables (entities) available is retrieved.
* @param options JavaScript object containing initialization data (property
* values and event handlers) for the {@link ODataVirtualCollectionView}.
*/
constructor(url: string, tableName: string, options?: any);
private _groupLazyLoading;
/**
* @deprecated
* GroupLazyLoading is not supported in ODataVirtualCollectionView
*/
groupLazyLoading: boolean;
/**
* @deprecated
* lazyLoadGroup() is not supported as GroupLazyLoading is not supported in ODataVirtualCollectionView.
*/
lazyLoadGroup(item: CollectionViewGroup): void;
/**
* Sets the data window to ensure a range of records are loaded into the view.
*
* @param start Index of the first item in the data window.
* @param end Index of the last item in the data window.
*/
setWindow(start: number, end: number): void;
/**
* Occurs when the {@link ODataVirtualCollectionView} cancels a pending data request.
*/
readonly requestCanceled: Event;
/**
* Raises the {@link requestCanceled} event.
*/
onRequestCanceled(e?: EventArgs): void;
/**
* {@link ODataVirtualCollectionView} requires {@link pageOnServer} to be set to true.
*/
pageOnServer: boolean;
/**
* {@link ODataVirtualCollectionView} requires {@link sortOnServer} to be set to true.
*/
sortOnServer: boolean;
/**
* {@link ODataVirtualCollectionView} requires {@link filterOnServer} to be set to true.
*/
filterOnServer: boolean;
/**
* {@link ODataVirtualCollectionView} requires {@link canGroup} to be set to false.
*/
canGroup: boolean;
_performRefresh(): void;
_getReadParams(nextLink?: string): any;
_storeItems(items: any[], append: boolean): Promise;
_isVirtualRefreshNeeded(start: number, end: number): boolean;
_performSetWindow(start: number, end: number): void;
private _fetchSize;
}
export {};