@itwin/presentation-components
Version:
React components based on iTwin.js Presentation library
170 lines • 8.96 kB
TypeScript
/** @packageDocumentation
* @module Tree
*/
import "../common/DisposePolyfill.js";
import { DelayLoadedTreeNodeItem, PageOptions, TreeNodeItem } from "@itwin/components-react";
import { IModelConnection } from "@itwin/core-frontend";
import { FilterByTextHierarchyRequestOptions, HierarchyRequestOptions, InstanceFilterDefinition, Node, NodeKey, NodePathElement, Paged, Ruleset } from "@itwin/presentation-common";
import { DiagnosticsProps } from "../common/Diagnostics.js";
import { IPresentationTreeDataProvider } from "./IPresentationTreeDataProvider.js";
/**
* Properties for creating a `PresentationTreeDataProvider` instance.
* @public
* @deprecated in 5.7. All tree-related APIs have been deprecated in favor of the new generation hierarchy
* building APIs (see https://github.com/iTwin/presentation/blob/33e79ee8d77f30580a9bab81a72884bda008db25/README.md#the-packages).
*/
export interface PresentationTreeDataProviderProps extends DiagnosticsProps {
/** IModel to pull data from. */
imodel: IModelConnection;
/** Id of the ruleset to use when requesting content or a ruleset itself. */
ruleset: string | Ruleset;
/**
* Paging size for obtaining nodes.
*
* Presentation data providers, when used with paging, have ability to save one backend request for size / count. That
* can only be achieved when `pagingSize` property is set on the data provider and it's value matches size which is used when
* requesting nodes. To help developers notice this problem, data provider emits a warning similar to this:
* ```
* PresentationTreeDataProvider.pagingSize doesn't match pageOptions in PresentationTreeDataProvider.getNodes call. Make sure you set PresentationTreeDataProvider.pagingSize to avoid excessive backend requests.
* ```
* To fix the issue, developers should make sure the page size used for requesting data is also set for the data provider:
* ```TS
* const pagingSize = 10;
* const provider = new TreeDataProvider({imodel, ruleset, pagingSize});
* // only one backend request is made for the two following requests:
* provider.getNodesCount();
* provider.getNodes({ start: 0, size: pagingSize });
* ```
*/
pagingSize?: number;
/**
* The limit for how many ECInstances should be loaded for a single hierarchy level. If the limit is exceeded, the data
* provider returns a single `PresentationInfoTreeNodeItem` asking the user to apply filtering to reduce the size of the
* hierarchy level.
*
* Specifying the limit is useful when creating unlimited size result sets is not meaningful - this allows the library
* to return early as soon as the limit is reached, instead of creating a very large result that's possibly too large to
* be useful to be displayed to end users.
*
* **Warning:** The data provider has no way of knowing whether hierarchy level filtering is enabled at the component
* level - API consumers, when using this attribute, should make sure to enable filtering or otherwise large hierarchy levels
* will become impossible to filter-down.
*
* @see [Hierarchies' filtering and limiting]($docs/presentation/hierarchies/FilteringLimiting.md)
* @note Requires `@itwin/presentation-frontend` peer dependency to be at least `4.0`, otherwise has no effect.
*/
hierarchyLevelSizeLimit?: number;
/** Should grouping nodes have a suffix with grouped nodes count. Defaults to `false`. */
appendChildrenCountForGroupingNodes?: boolean;
/**
* Callback which provides a way to customize how data is mapped between [Node]($presentation-common) and [TreeNodeItem]($components-react).
*/
customizeTreeNodeItem?: (item: Partial<DelayLoadedTreeNodeItem>, node: Partial<Node>) => void;
/**
* By default the provider uses [PresentationManager]($presentation-frontend) accessed through `Presentation.presentation` to request
* node counts, nodes and filter them. The overrides allow swapping some or all of the data source entry points thus
* making the provider request data from custom sources.
*/
dataSourceOverrides?: Partial<PresentationTreeDataProviderDataSourceEntryPoints>;
/**
* Callback for when the hierarchy limit is exceeded while loading nodes.
*/
onHierarchyLimitExceeded?: () => void;
}
/**
* Definitions of methods used by [[PresentationTreeDataProvider]] to get nodes' data.
* @public
* @deprecated in 5.7. All tree-related APIs have been deprecated in favor of the new generation hierarchy
* building APIs (see https://github.com/iTwin/presentation/blob/33e79ee8d77f30580a9bab81a72884bda008db25/README.md#the-packages).
*/
export interface PresentationTreeDataProviderDataSourceEntryPoints {
/** @deprecated in 4.0 The entry point is not used anymore, it's usage has been replaced by [[getNodesIterator]]. */
getNodesCount?: (requestOptions: HierarchyRequestOptions<IModelConnection, NodeKey>) => Promise<number>;
/** @deprecated in 5.2 The entry point is not used anymore, it's usage has been replaced by [[getNodesIterator]]. */
getNodesAndCount?: (requestOptions: Paged<HierarchyRequestOptions<IModelConnection, NodeKey>>) => Promise<{
nodes: Node[];
count: number;
}>;
getNodesIterator: (requestOptions: Paged<HierarchyRequestOptions<IModelConnection, NodeKey> & {
maxParallelRequests?: number;
batchSize?: number;
}>) => Promise<{
total: number;
items: AsyncIterableIterator<Node>;
}>;
getFilteredNodePaths: (requestOptions: FilterByTextHierarchyRequestOptions<IModelConnection>) => Promise<NodePathElement[]>;
}
/**
* Presentation Rules-driven tree data provider.
* @public
* @deprecated in 5.7. All tree-related APIs have been deprecated in favor of the new generation hierarchy
* building APIs (see https://github.com/iTwin/presentation/blob/33e79ee8d77f30580a9bab81a72884bda008db25/README.md#the-packages).
*/
export declare class PresentationTreeDataProvider implements IPresentationTreeDataProvider, Disposable {
#private;
private _unregisterVariablesChangeListener?;
private _dataSource;
private _diagnosticsOptions?;
private _onHierarchyLimitExceeded?;
private _props;
hierarchyLevelSizeLimit?: number;
/** Constructor. */
constructor(props: PresentationTreeDataProviderProps);
/** Destructor. Must be called to clean up. */
[Symbol.dispose](): void;
/** @deprecated in 5.7. Use `[Symbol.dispose]` instead. */
dispose(): void;
get props(): Readonly<PresentationTreeDataProviderProps>;
/** Id of the ruleset used by this data provider */
get rulesetId(): string;
/** [IModelConnection]($core-frontend) used by this data provider */
get imodel(): IModelConnection;
/**
* Paging options for obtaining nodes.
* @see `PresentationTreeDataProviderProps.pagingSize`
*/
get pagingSize(): number | undefined;
set pagingSize(value: number | undefined);
/** Called to get base options for requests */
private createBaseRequestOptions;
/** Called to get options for node requests */
private createPagedRequestOptions;
/** Creates options for nodes requests. */
createRequestOptions(parentKey: NodeKey | undefined, instanceFilter?: InstanceFilterDefinition): {
instanceFilter?: InstanceFilterDefinition | undefined;
sizeLimit?: number | undefined;
parentKey?: NodeKey | undefined;
rulesetOrId: Ruleset | string;
rulesetVariables?: import("@itwin/presentation-common").RulesetVariable[] | undefined;
imodel: IModelConnection;
locale?: string;
unitSystem?: import("@itwin/core-quantity").UnitSystemKey;
};
/**
* Returns a [NodeKey]($presentation-common) from given [TreeNodeItem]($components-react).
*
* **Warning**: Returns invalid [NodeKey]($presentation-common) if `node` is not a [[PresentationTreeNodeItem]].
*
* @deprecated in 4.0. Use [[isPresentationTreeNodeItem]] and [[PresentationTreeNodeItem.key]] to get [NodeKey]($presentation-common).
*/
getNodeKey(node: TreeNodeItem): NodeKey;
/**
* Returns nodes
* @param parentNode The parent node to return children for.
* @param pageOptions Information about the requested page of data.
*/
getNodes(parentNode?: TreeNodeItem, pageOptions?: PageOptions): Promise<DelayLoadedTreeNodeItem[]>;
/**
* Returns the total number of nodes
* @param parentNode The parent node to return children count for.
*/
getNodesCount(parentNode?: TreeNodeItem): Promise<number>;
private _getNodesAndCount;
/**
* Returns filtered node paths.
* @param filter Filter.
*/
getFilteredNodePaths(filter: string): Promise<NodePathElement[]>;
private setupRulesetVariablesListener;
}
//# sourceMappingURL=DataProvider.d.ts.map