@itwin/presentation-core-interop

Copyright © Bentley Systems, Incorporated. All rights reserved. See LICENSE.md for license terms and full copyright notice.

The @itwin/presentation-core-interop package acts as a layer between itwinjs-core packages and presentation packages:

• @itwin/presentation-hierarchies
• @itwin/unified-selection

Having this interop layer helps us evolve both sides without affecting one another in a major way.

API

createIModelKey

Attempts to create a unique identifier for the given iModel. In majority of cases that's going to be the key property, but if it's not set (e.g. when using BlankConnection) - name property is used instead. Finally, if both are empty - the function will throw an error.

Example:

import { IModelConnection } from "@itwin/core-frontend";
import { createIModelKey } from "@itwin/presentation-core-interop";

IModelConnection.onOpen.addListener((imodel: IModelConnection) => {
  const key = createIModelKey(imodel);
  console.log(`IModel opened: "${key}"`);
});

createECSqlQueryExecutor

Maps an iModel in the form of itwinjs-core IModelDb or IModelConnection to an instance of ECSqlQueryExecutor, used in @itwin/presentation-hierarchies and @itwin/unified-selection packages.

Example:

import { IModelConnection } from "@itwin/core-frontend";
import { createECSqlQueryExecutor } from "@itwin/presentation-core-interop";

const imodel: IModelConnection = getIModelConnection();
const executor = createECSqlQueryExecutor(imodel);
for await (const row of executor.createQueryReader({ ecsql: MY_QUERY })) {
  console.log(row);
}

createECSchemaProvider

Maps an instance of itwinjs-core iModel (either IModelConnection or IModelDb) to an instance of ECSchemaProvider, used in @itwin/presentation-hierarchies, @itwin/unified-selection and other packages.

The created provider caches the class hierarchy and hidden classes trees for its lifetime (see ECSchemaProvider.getHiddenClassesTree). Concurrent requests share a single computation, and failed computations are retried on the next request. Create one provider per iModel and share it between consumers; after schema changes, recreate the provider and consumers holding it. Individual schema views still refresh on access when marked outdated, but this does not rebuild the cached class hierarchy or hidden classes trees.

Example:

import { IModelConnection } from "@itwin/core-frontend";
import { createECSchemaProvider } from "@itwin/presentation-core-interop";

const imodel: IModelConnection = getIModelConnection();
const schemaProvider = createECSchemaProvider(imodel);
// the created schema provider may be used in `@itwin/presentation-hierarchies` or `@itwin/unified-selection` packages

createValueFormatter

Creates an instance of IPrimitiveValueFormatter that knows how to format primitive property values using their units' information. The formats and units used come from a FormatsProvider and UnitsProvider registered by the end product (e.g. IModelApp.formatsProvider / IModelApp.quantityFormatter on the frontend), while the kind of quantity's persistence unit is resolved from the iModel itself.

Example:

import { IModelApp } from "@itwin/core-frontend";
import { createValueFormatter } from "@itwin/presentation-core-interop";

const imodel = getIModelConnection();
const metricFormatter = createValueFormatter({
  formatsProvider: IModelApp.formatsProvider,
  unitsProvider: IModelApp.quantityFormatter,
  imodel,
  unitSystem: "metric",
});
const imperialFormatter = createValueFormatter({
  formatsProvider: IModelApp.formatsProvider,
  unitsProvider: IModelApp.quantityFormatter,
  imodel,
  unitSystem: "imperial",
});

// Define the raw value to be formatted
const value = 1.234;

// Define the `KindOfQuantity` to use for formatting:
// <KindOfQuantity
//   typeName="FlowRate"
//   displayLabel="Flow Rate"
//   persistenceUnit="u:CUB_M_PER_SEC"
//   relativeError="1e-05"
//   presentationUnits="f:DefaultRealU(4)[u:LITRE_PER_MIN];f:DefaultRealU(4)[u:GALLON_PER_MIN]"
// />
const koqName = `${KOQ_SCHEMA_NAME}.FlowRate`;

// Not passing `koqName` formats the value without units using the default formatter:
expect(await metricFormatter({ type: "Double", value })).toBe("1.23");

// Metric formatter formats the value in liters per minute:
expect(await metricFormatter({ type: "Double", value, koqName })).toBe("74040.0 L/min");

// Imperial formatter formats the value in gallons per minute:
expect(await imperialFormatter({ type: "Double", value, koqName })).toBe("19559.2988 gal/min");

registerTxnListeners

Registers a number of transaction listeners on either the backend TxnManager or the frontend BriefcaseTxns and calls the given onChange function whenever there's a change in an iModel holding the transaction manager.

Example:

import { BriefcaseDb } from "@itwin/core-backend";
import { registerTxnListeners } from "@itwin/presentation-core-interop";
import { HierarchyProvider } from "@itwin/presentation-hierarchies";

const imodel: BriefcaseDb = getIModel();
const provider: HierarchyProvider & { notifyDataSourceChanged: () => void } = getHierarchyProvider();

// register the listeners
const unregister = registerTxnListeners(imodel.txns, () => {
  // notify provided about the changed data
  provider.notifyDataSourceChanged();
  // the provider is expected to raise `hierarchyChanged` event, which in turn
  // should trigger an update in the UI that uses this provider
});

// clean up on iModel close
imodel.onClosed.addOnce(() => unregister());

createLogger

Maps the itwinjs-core Logger class to an ILogger interface used by Presentation packages.

Example:

import { Logger as CoreLogger } from "@itwin/core-bentley";
import { createLogger as createPresentationLogger } from "@itwin/presentation-core-interop";
import { setLogger as setPresentationLogger } from "@itwin/presentation-hierarchies";

setPresentationLogger(createPresentationLogger(CoreLogger));