diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 2ce05fea..048a9b7a 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -399,6 +399,49 @@ module.exports = config({ ['/en/developer-guide/applications/controls/quicklookupedit.md', 'Quick Lookup Edit'], ['/en/developer-guide/applications/controls/rating.md', 'Rating'], ['/en/developer-guide/applications/controls/treeview.md', 'Tree View'], + { + title: 'Virtual Dataset', + collapsable: true, + children: [ + ['/en/developer-guide/applications/controls/VirtualDataset/general.md', 'General'], + { + title: 'Client Extensibility', + collapsable: true, + children: [ + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/general.md', 'General'], + { + title: 'API', + collapsable: true, + children: [ + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/globals.md', 'General'], + { + title: 'interfaces', + collapsable: true, + children: [ + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDataset.md', 'IDataset'], + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDatasetEventListeners.md', 'IDatasetEventListeners'], + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDataProvider.md', 'IDataProvider'], + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDataProviderEventListeners.md', 'IDataProviderEventListeners'], + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IRecord.md', 'IRecord'] + ] + }, + { + title: 'classes', + collapsable: true, + children: [ + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/FetchXmlDataProvider.md', 'FetchXmlDataProvider'], + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/MemoryDataProvider.md', 'MemoryDataProvider'], + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/Record.md', 'Record'], + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/Dataset.md', 'Dataset'], + ['/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/DataProvider.md', 'DataProvider'], + ] + } + ] + } + ] + } + ] + }, ['/en/developer-guide/applications/controls/wbs.md', 'WBS - Work Breakdown Structure'] ] }, diff --git a/src/.vuepress/public/.attachments/applications/Controls/virtualdataset.png b/src/.vuepress/public/.attachments/applications/Controls/virtualdataset.png new file mode 100644 index 00000000..85f0bec7 Binary files /dev/null and b/src/.vuepress/public/.attachments/applications/Controls/virtualdataset.png differ diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/DataProvider.md b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/DataProvider.md new file mode 100644 index 00000000..37b69f34 --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/DataProvider.md @@ -0,0 +1,63 @@ +Base class for all Data Providers. + +## Extended by + +- [`FetchXmlDataProvider`](FetchXmlDataProvider.md) +- [`MemoryDataProvider`](MemoryDataProvider.md) + +## Implements + +- [`IDataProvider`](../interfaces/IDataProvider.md) + +## Constructors + +### new DataProvider() + +> **new DataProvider**(`dataSource`, `columns`, `options`?): [`DataProvider`](DataProvider.md) + +Creates an instance of DataProvider. + +#### Parameters + +• **dataSource**: `any` + +• **columns**: `Column` & `object`[] + +• **options?**: [`IDataProviderOptions`](../interfaces/IDataProviderOptions.md) + +#### Returns + +[`DataProvider`](DataProvider.md) + +#### Defined in + +src/utils/dataset/data-providers/DataProvider.ts:41 + + +### addEventListener() + +> **addEventListener**\<`K`\>(`event`, `eventListener`): `void` + +Allows to define listener method that will trigger when specific event occurs. + +#### Type Parameters + +• **K** *extends* keyof [`IDataProviderEventListeners`](../interfaces/IDataProviderEventListeners.md) + +#### Parameters + +• **event**: `K` + +• **eventListener**: [`IDataProviderEventListeners`](../interfaces/IDataProviderEventListeners.md)\[`K`\] + +#### Returns + +`void` + +#### Implementation of + +[`IDataProvider`](../interfaces/IDataProvider.md).[`addEventListener`](../interfaces/IDataProvider.md#addeventlistener) + +#### Defined in + +src/utils/dataset/data-providers/DataProvider.ts:139 \ No newline at end of file diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/Dataset.md b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/Dataset.md new file mode 100644 index 00000000..e999cb8b --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/Dataset.md @@ -0,0 +1,544 @@ +Uses Data Provider and is passed as dataset parameter to PCF's + +## Implements + +- [`IDataset`](../interfaces/IDataset.md) + +## Constructors + +### new Dataset() + +> **new Dataset**(`dataProvider`): [`Dataset`](Dataset.md) + +Creates an instance of Dataset. + +#### Parameters + +• **dataProvider**: `DataProvider` + +#### Returns + +[`Dataset`](Dataset.md) + +#### Defined in + +src/utils/dataset/Dataset.ts:28 + +## Accessors + +### columns + +> `get` **columns**(): `Column` & `object`[] + +Metadata about a column in a dataset. If the column name ends with `__virtual`, it tells the provider it should not try to fetch column metadata from its Data Source. +In this case, you need to specify all the necessary metadata yourself. + +#### Returns + +`Column` & `object`[] + +Metadata about a column in a dataset. If the column name ends with `__virtual`, it tells the provider it should not try to fetch column metadata from its Data Source. +In this case, you need to specify all the necessary metadata yourself. + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`columns`](../interfaces/IDataset.md#columns) + +#### Defined in + +src/utils/dataset/Dataset.ts:31 + +*** + +### error + +> `get` **error**(): `boolean` + +True if encountered error while data retrieval + +#### Returns + +`boolean` + +True if encountered error while data retrieval + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`error`](../interfaces/IDataset.md#error) + +#### Defined in + +src/utils/dataset/Dataset.ts:43 + +*** + +### errorMessage + +> `get` **errorMessage**(): `string` + +The error message associated with the last encountered error, if applicable + +#### Returns + +`string` + +The error message associated with the last encountered error, if applicable + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`errorMessage`](../interfaces/IDataset.md#errormessage) + +#### Defined in + +src/utils/dataset/Dataset.ts:46 + +*** + +### filtering + +> `get` **filtering**(): `Omit`\<`Filtering`, `"getFilter"`\> & `object` + +Filter state for a dataset. + +#### Returns + +`Omit`\<`Filtering`, `"getFilter"`\> & `object` + +Filter state for a dataset. + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`filtering`](../interfaces/IDataset.md#filtering) + +#### Defined in + +src/utils/dataset/Dataset.ts:88 + +*** + +### linking + +> `get` **linking**(): `Linking` + +Related entity info + +#### Returns + +`Linking` + +Related entity info + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`linking`](../interfaces/IDataset.md#linking) + +#### Defined in + +src/utils/dataset/Dataset.ts:58 + +*** + +### loading + +> `get` **loading**(): `boolean` + +Indicate if the dataset property is in loading state or not + +#### Returns + +`boolean` + +Indicate if the dataset property is in loading state or not + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`loading`](../interfaces/IDataset.md#loading) + +#### Defined in + +src/utils/dataset/Dataset.ts:49 + +*** + +### records + +> `get` **records**(): `object` + +Map of IDs to the full record object. + +#### Returns + +`object` + +Map of IDs to the full record object. + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`records`](../interfaces/IDataset.md#records) + +#### Defined in + +src/utils/dataset/Dataset.ts:102 + +*** + +### sortedRecordIds + +> `get` **sortedRecordIds**(): `string`[] + +IDs of the records in the dataset, order by the query response result + +#### Returns + +`string`[] + +IDs of the records in the dataset, order by the query response result + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`sortedRecordIds`](../interfaces/IDataset.md#sortedrecordids) + +#### Defined in + +src/utils/dataset/Dataset.ts:123 + +*** + +### sorting + +> `get` **sorting**(): `SortStatus`[] + +The sorting status for the current query. + +> `set` **sorting**(`sort`): `void` + +The sorting status for the current query. + +#### Parameters + +• **sort**: `SortStatus`[] + +#### Returns + +`SortStatus`[] + +The sorting status for the current query. + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`sorting`](../interfaces/IDataset.md#sorting) + +#### Defined in + +src/utils/dataset/Dataset.ts:52 + +## Methods + +### addEventListener() + +> **addEventListener**\<`K`\>(`event`, `eventListener`): `void` + +Allows to define listener method that will trigger when specific event occurs. + +#### Type Parameters + +• **K** *extends* keyof [`IDatasetEventListeners`](../interfaces/IDatasetEventListeners.md) + +#### Parameters + +• **event**: `K` + +• **eventListener**: [`IDatasetEventListeners`](../interfaces/IDatasetEventListeners.md)\[`K`\] + +#### Returns + +`void` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`addEventListener`](../interfaces/IDataset.md#addeventlistener) + +#### Defined in + +src/utils/dataset/Dataset.ts:197 + +*** + +### clearSelectedRecordIds() + +> **clearSelectedRecordIds**(): `void` + +Clear selected record ids list + +#### Returns + +`void` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`clearSelectedRecordIds`](../interfaces/IDataset.md#clearselectedrecordids) + +#### Defined in + +src/utils/dataset/Dataset.ts:130 + +*** + +### getDataProvider() + +> **getDataProvider**(): `DataProvider` + +Returns a data provider instance. + +#### Returns + +`DataProvider` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`getDataProvider`](../interfaces/IDataset.md#getdataprovider) + +#### Defined in + +src/utils/dataset/Dataset.ts:173 + +*** + +### getDataSource() + +> **getDataSource**(): `any` + +Gets the Data Source. + +#### Returns + +`any` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`getDataSource`](../interfaces/IDataset.md#getdatasource) + +#### Defined in + +src/utils/dataset/Dataset.ts:40 + +*** + +### getMetadata() + +> **getMetadata**(): `null` \| `EntityMetadata` + +Gets the associated entity metadata. + +#### Returns + +`null` \| `EntityMetadata` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`getMetadata`](../interfaces/IDataset.md#getmetadata) + +#### Defined in + +src/utils/dataset/Dataset.ts:158 + +*** + +### getSelectedRecordIds() + +> **getSelectedRecordIds**(): `string`[] + +Retrieves all selected record ids + +#### Returns + +`string`[] + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`getSelectedRecordIds`](../interfaces/IDataset.md#getselectedrecordids) + +#### Defined in + +src/utils/dataset/Dataset.ts:133 + +*** + +### getTargetEntityType() + +> **getTargetEntityType**(): `string` + +Get DataSet target entity logical name + +#### Returns + +`string` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`getTargetEntityType`](../interfaces/IDataset.md#gettargetentitytype) + +#### Defined in + +src/utils/dataset/Dataset.ts:142 + +*** + +### getTitle() + +> **getTitle**(): `string` + +Retrieves the view display name used by the dataset property + +#### Returns + +`string` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`getTitle`](../interfaces/IDataset.md#gettitle) + +#### Defined in + +src/utils/dataset/Dataset.ts:145 + +*** + +### getViewId() + +> **getViewId**(): `string` + +Gets Id of view used by the dataset property + +#### Returns + +`string` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`getViewId`](../interfaces/IDataset.md#getviewid) + +#### Defined in + +src/utils/dataset/Dataset.ts:148 + +*** + +### openDatasetItem() + +> **openDatasetItem**(`entityReference`): `void` + +Open dataSet item for a given EntityReference. It will check if there is a command with command button id "Mscrm.OpenRecordItem". +If there is, it will execute the command, otherwise it will just navigate to the associated form of the entityReference + +#### Parameters + +• **entityReference**: `EntityReference` + +entity reference + +#### Returns + +`void` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`openDatasetItem`](../interfaces/IDataset.md#opendatasetitem) + +#### Defined in + +src/utils/dataset/Dataset.ts:151 + +*** + +### refresh() + +> **refresh**(): `Promise`\<`void`\> + +Refreshes the dataset based on filters, sorting, linking, new column. New data will be pushed to control in another 'updateView' cycle. + +#### Returns + +`Promise`\<`void`\> + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`refresh`](../interfaces/IDataset.md#refresh) + +#### Defined in + +src/utils/dataset/Dataset.ts:154 + +*** + +### setDataSource() + +> **setDataSource**(`dataSource`): `void` + +Allows you to change the initial Data Source. + +#### Parameters + +• **dataSource**: `any` + +#### Returns + +`void` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`setDataSource`](../interfaces/IDataset.md#setdatasource) + +#### Defined in + +src/utils/dataset/Dataset.ts:37 + +*** + +### setMetadata() + +> **setMetadata**(`metadata`): `void` + +Allows you to change the initial associated entity metadata. + +#### Parameters + +• **metadata**: `EntityMetadata` + +#### Returns + +`void` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`setMetadata`](../interfaces/IDataset.md#setmetadata) + +#### Defined in + +src/utils/dataset/Dataset.ts:161 + +*** + +### setSelectedRecordIds() + +> **setSelectedRecordIds**(`ids`): `void` + +Set the ids of the selected records + +#### Parameters + +• **ids**: `string`[] + +List of recordId's + +#### Returns + +`void` + +#### Implementation of + +[`IDataset`](../interfaces/IDataset.md).[`setSelectedRecordIds`](../interfaces/IDataset.md#setselectedrecordids) + +#### Defined in + +src/utils/dataset/Dataset.ts:138 diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/FetchXmlDataProvider.md b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/FetchXmlDataProvider.md new file mode 100644 index 00000000..6a908791 --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/FetchXmlDataProvider.md @@ -0,0 +1,33 @@ +Allows you to use fetchXml as a Data Source. + +## Extends + +- `DataProvider` + +## Constructors + +### new FetchXmlDataProvider() + +> **new FetchXmlDataProvider**(`fetchXml`, `columns`?, `options`?): [`FetchXmlDataProvider`](FetchXmlDataProvider.md) + +Creates an instance of FetchXmlDataProvider. + +#### Parameters + +• **fetchXml**: `string` + +• **columns?**: `Column` & `object`[] + +• **options?**: [`IDataProviderOptions`](../interfaces/IDataProviderOptions.md) + +#### Returns + +[`FetchXmlDataProvider`](FetchXmlDataProvider.md) + +#### Overrides + +`DataProvider.constructor` + +#### Defined in + +src/utils/dataset/data-providers/FetchXmlDataProvider.ts:21 \ No newline at end of file diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/MemoryDataProvider.md b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/MemoryDataProvider.md new file mode 100644 index 00000000..49467b74 --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/MemoryDataProvider.md @@ -0,0 +1,33 @@ +Allows you to use in-memory array as Data Source. + +## Extends + +- `DataProvider` + +## Constructors + +### new MemoryDataProvider() + +> **new MemoryDataProvider**(`dataSource`, `columns`, `options`?): [`MemoryDataProvider`](MemoryDataProvider.md) + +Creates an instance of MemoryDataProvider. + +#### Parameters + +• **dataSource**: `object`[] + +• **columns**: `Column` & `object`[] + +• **options?**: [`IDataProviderOptions`](../interfaces/IDataProviderOptions.md) + +#### Returns + +[`MemoryDataProvider`](MemoryDataProvider.md) + +#### Overrides + +`DataProvider.constructor` + +#### Defined in + +src/utils/dataset/data-providers/memory-provider/MemoryDataProvider.ts:16 \ No newline at end of file diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/Record.md b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/Record.md new file mode 100644 index 00000000..eaf03cbc --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/classes/Record.md @@ -0,0 +1,159 @@ +Instance of a record, + +## Implements + +- [`IRecord`](../interfaces/IRecord.md) + +## Constructors + +### new Record() + +> **new Record**(`recordId`, `dataProvider`): [`Record`](Record.md) + +Creates an instance of Record. + +#### Parameters + +• **recordId**: `string` + +• **dataProvider**: `DataProvider` + +#### Returns + +[`Record`](Record.md) + +#### Defined in + +src/utils/dataset/data-providers/Record.ts:24 + +## Methods + +### getFormattedValue() + +> **getFormattedValue**(`columnName`): `null` \| `string` + +Get the current formatted value of this record column. + +#### Parameters + +• **columnName**: `string` + +Column name of the record + +#### Returns + +`null` \| `string` + +#### Implementation of + +[`IRecord`](../interfaces/IRecord.md).[`getFormattedValue`](../interfaces/IRecord.md#getformattedvalue) + +#### Defined in + +src/utils/dataset/data-providers/Record.ts:34 + +*** + +### getNamedReference() + +> **getNamedReference**(): `EntityReference` + +Get the object that encapsulates an Entity Reference as a plain object + +#### Returns + +`EntityReference` + +#### Implementation of + +[`IRecord`](../interfaces/IRecord.md).[`getNamedReference`](../interfaces/IRecord.md#getnamedreference) + +#### Defined in + +src/utils/dataset/data-providers/Record.ts:199 + +*** + +### getRawData() + +> **getRawData**(): `object` + +Retrieves the raw record data. + +#### Returns + +`object` + +#### Implementation of + +[`IRecord`](../interfaces/IRecord.md).[`getRawData`](../interfaces/IRecord.md#getrawdata) + +#### Defined in + +src/utils/dataset/data-providers/Record.ts:213 + +*** + +### getRecordId() + +> **getRecordId**(): `string` + +Get the record ID + +#### Returns + +`string` + +#### Implementation of + +[`IRecord`](../interfaces/IRecord.md).[`getRecordId`](../interfaces/IRecord.md#getrecordid) + +#### Defined in + +src/utils/dataset/data-providers/Record.ts:107 + +*** + +### save() + +> **save**(): `Promise`\<`void`\> + +Saves the record. + +#### Returns + +`Promise`\<`void`\> + +#### Implementation of + +[`IRecord`](../interfaces/IRecord.md).[`save`](../interfaces/IRecord.md#save) + +#### Defined in + +src/utils/dataset/data-providers/Record.ts:209 + +*** + +### setValue() + +> **setValue**(`columnName`, `value`): `void` + +Sets the value of a given column. + +#### Parameters + +• **columnName**: `string` + +• **value**: `any` + +#### Returns + +`void` + +#### Implementation of + +[`IRecord`](../interfaces/IRecord.md).[`setValue`](../interfaces/IRecord.md#setvalue) + +#### Defined in + +src/utils/dataset/data-providers/Record.ts:123 diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/globals.md b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/globals.md new file mode 100644 index 00000000..a99174f9 --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/globals.md @@ -0,0 +1,20 @@ +--- +Author: Dominik Brych +--- +# API + +## Classes + +- [Dataset](classes/Dataset.md) +- [FetchXmlDataProvider](classes/FetchXmlDataProvider.md) +- [MemoryDataProvider](classes/MemoryDataProvider.md) +- [Record](classes/Record.md) + +## Interfaces + +- [IDataProvider](interfaces/IDataProvider.md) +- [IDataProviderEventListeners](interfaces/IDataProviderEventListeners.md) +- [IDataProviderOptions](interfaces/IDataProviderOptions.md) +- [IDataset](interfaces/IDataset.md) +- [IDatasetEventListeners](interfaces/IDatasetEventListeners.md) +- [IRecord](interfaces/IRecord.md) diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDataProviderEventListeners.md b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDataProviderEventListeners.md new file mode 100644 index 00000000..7b19ff8b --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDataProviderEventListeners.md @@ -0,0 +1,43 @@ +Allows you to define callbacks that will trigger during specific events. + +## Properties + +### onCellValueChanged() + +> **onCellValueChanged**: (`record`, `columnName`) => `void` + +Triggers when column value has been changed. + +#### Parameters + +• **record**: [`IRecord`](IRecord.md) + +• **columnName**: `string` + +#### Returns + +`void` + +#### Defined in + +src/utils/dataset/data-providers/interfaces.ts:179 + +*** + +### onRecordSaved() + +> **onRecordSaved**: (`record`) => `void` + +Triggers when record has been saved. + +#### Parameters + +• **record**: [`IRecord`](IRecord.md) + +#### Returns + +`void` + +#### Defined in + +src/utils/dataset/data-providers/interfaces.ts:174 diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDatasetEventListeners.md b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDatasetEventListeners.md new file mode 100644 index 00000000..1a1ed9ab --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/API/interfaces/IDatasetEventListeners.md @@ -0,0 +1,65 @@ +Allows you to define callbacks that will trigger during specific events. + +## Properties + +### onDatasetItemOpened() + +> **onDatasetItemOpened**: (`dataset`, `entityReference`) => `void` + +Triggers when record has been opened by a PCF. + +#### Parameters + +• **dataset**: [`IDataset`](IDataset.md) + +• **entityReference**: `EntityReference` + +#### Returns + +`void` + +#### Defined in + +src/utils/dataset/interfaces.ts:15 + +*** + +### onNewDataLoaded() + +> **onNewDataLoaded**: (`dataset`) => `void` + +Triggers when new load has been loaded, for example after a `refresh` or `loadExactPage` events. + +#### Parameters + +• **dataset**: [`IDataset`](IDataset.md) + +#### Returns + +`void` + +#### Defined in + +src/utils/dataset/interfaces.ts:20 + +*** + +### onRecordsSelected() + +> **onRecordsSelected**: (`dataset`, `selectedRecordIds`) => `void` + +Triggers when some record/s has been selected by the PCF. + +#### Parameters + +• **dataset**: [`IDataset`](IDataset.md) + +• **selectedRecordIds**: `string`[] + +#### Returns + +`void` + +#### Defined in + +src/utils/dataset/interfaces.ts:10 diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/general.md b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/general.md new file mode 100644 index 00000000..d2380b57 --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/ClientExtensibility/general.md @@ -0,0 +1,73 @@ +--- +Author: Dominik Brych +--- +# Client Extensibility + +You can extend the PCF functionalities by acessing it's API from a client script. You can access the API by registering an [`addOnOutputChange`](https://learn.microsoft.com/en-us/power-apps/developer/model-driven-apps/clientapi/reference/controls/addonoutputchange) callback. +When your callback fires, you can retrieve the dataset instance. You can then use it's API to manipulate the control and register event handlers. Please refer to our [API docs](API/globals.md) to learn more. + + +
+Client Script Example + +```javascript +let notificationIds = []; +function onFormLoad(executionContext) { + const formContext = executionContext.getFormContext(); + const control = formContext.getControl('talxis_clientextensibilitybindingfield'); + control.addOnOutputChange((executionContext) => { + const control = executionContext.getFormContext().getControl('talxis_clientextensibilitybindingfield'); + const dataset = control.getOutputs()['talxis_clientextensibilitybindingfield.fieldControl.DatasetControl'].value; + //init, settings you apply to dataset here will be applied before first data fetch + dataset.addEventListener('onNewDataLoaded', (dataset) => { + Object.values(dataset.records).map(record => { + record.setValue('talxis_sum__virtual', calculateSum(record)); + }) + dataset.render(); + }); + dataset.addEventListener('onRecordsSelected', (dataset, ids) => { + notificationIds.map(id => Xrm.App.clearGlobalNotification(id)); + notificationIds = []; + ids.map(id => { + const notification = + { + type: 2, + level: 1, + message: `Record ${dataset.records[id].getFormattedValue('talxis_name')} with id ${id} has been selected.` + } + + Xrm.App.addGlobalNotification(notification).then( + function success(result) { + notificationIds.push(result); + } + ); + }) + }); + dataset.addEventListener('onDatasetItemOpened', (dataset, entityReference) => { + const alertStrings = { text: `Sample client script logic for opening of record ${entityReference.name}`, title: "Open" }; + const alertOptions = { height: 120, width: 260 }; + Xrm.Navigation.openAlertDialog(alertStrings, alertOptions); + }); + + dataset.getDataProvider().addEventListener('onCellValueChanged', (record, columnName) => { + switch (columnName) { + case 'talxis_decimal': + case 'talxis_wholenone': { + record.setValue('talxis_sum__virtual', calculateSum(record)); + dataset.render(); + } + } + }); + dataset.getDataProvider().addEventListener('onRecordSaved', (record) => { + console.log(record.getRecordId(), 'has just been saved'); + }); + }) +} + +const calculateSum = (record) => { + const value1 = record.getValue('talxis_decimal') ?? 0; + const value2 = record.getValue('talxis_wholenone') ?? 0; + return value1 + value2; +} +``` +
\ No newline at end of file diff --git a/src/en/developer-guide/applications/controls/VirtualDataset/general.md b/src/en/developer-guide/applications/controls/VirtualDataset/general.md new file mode 100644 index 00000000..afbcaee6 --- /dev/null +++ b/src/en/developer-guide/applications/controls/VirtualDataset/general.md @@ -0,0 +1,342 @@ +--- +Author: Dominik Brych +--- +# Virtual Dataset + +Virtual Dataset allows you to bind a Dataset Base Control to a field while providing your own custom Data Source. We currently have two Data Providers - Memory and FetchXml. Memory Provider allows you to work with a collection of data that you have stored in memory and FetchXml Provider allows you to do the same thing with data retrieved through FetchXml. Both of these providers support basic Dataset features, which include: + +- **Sorting** +- **Filtering** +- **Paging** +- **Editing** +- **Quick Find** + +![Attachments Grid Displayed On Form](/.attachments/applications/Controls/virtualdataset.png) + +NOTE: Due to a bug in Power Apps maker, this PCF can only be bind manually through Form Xml! + +## Data Providers + +Static binding allows you to choose between two providers - **FetchXml** and **Memory**. After you select a provider, you need to specify it's Data Source through additional static binding. + +### FetchXml Data Provider + +FetchXml provider expects a valid FetchXml string as Data Source. + +### Memory Data Provider + +Memory Data Provider expects a stringified JSON array as input. The array should contain key-value pairs consisting of column name and it's value. This is the exact same structure you would see in a raw OData response. This means OptionSets are represented by a number, lookups have GUIDs and etc. This applies to each data type. If you are not sure what value should be used for a specific Data Type, run an OData query against some entity containing fields of this data type and see what you get back. + +
+OData response Example +
+ +```json +{ + "@odata.context":"https://devbox-1959.crm4.dynamics.com/api/data/v9.1/$metadata#talxis_fields", + "value":[ + { + "@odata.etag":"W/\"4363703\"", + "talxis_file_name":null, + "_owninguser_value":"e86450b3-5882-ef11-ac20-000d3abee5ab", + "talxis_clientextensibilitydatasource":null, + "talxis_singlelinetext":"Text", + "talxis_clientextensibilitybindingfield":null, + "talxis_name":"Batch 1", + "talxis_dateandtime":"1972-01-15T00:00:00Z", + "_transactioncurrencyid_value":"13292e9f-7881-ef11-ac21-000d3a2b5e17", + "talxis_clientextensibilitymetadata":null, + "exchangerate":1, + "talxis_currency_base":998472, + "talxis_singlelineemail":"test@test.cz", + "versionnumber":4363703, + "talxis_file":null, + "talxis_singlelineurl":"https://www.seznam.cz", + "talxis_image":null, + "talxis_multiple":"Multiple Text", + "statecode":0, + "talxis_image_timestamp":null, + "talxis_wholeduration":710135, + "talxis_twooptions":true, + "_createdonbehalfby_value":null, + "utcconversiontimezonecode":null, + "statuscode":1, + "talxis_multiselectoptionsetcolorful":"742070000,742070001", + "talxis_fetchxmlbindingfield":null, + "talxis_memorybindingfield":null, + "talxis_clientextensibilitycolumns":null, + "talxis_optionsetcolorful":742070000, + "modifiedon":"2024-10-12T10:34:53Z", + "talxis_wholenone":991020, + "talxis_image_url":null, + "talxis_fetchxmldata":null, + "_ownerid_value":"e86450b3-5882-ef11-ac20-000d3abee5ab", + "talxis_fieldid":"6c9e8489-1086-ef11-ac21-6045bd91c897", + "_owningteam_value":null, + "_modifiedonbehalfby_value":null, + "createdon":"2024-10-09T07:31:46Z", + "talxis_twooptionscolorful":false, + "talxis_imageid":null, + "_owningbusinessunit_value":"551c1778-4881-ef11-ac21-000d3a2b5e17", + "timezoneruleversionnumber":0, + "talxis_dateandtimetzi":null, + "talxis_multiselectoptionset":"742070000,742070001", + "talxis_fetchxmlcolumns":null, + "_createdby_value":"e86450b3-5882-ef11-ac20-000d3abee5ab", + "talxis_fetchxmlentitymetadata":null, + "talxis_singlelinephone":"123456789", + "talxis_dateonly":"1968-09-02T00:00:00Z", + "_talxis_parentfield_value":"ac6aa5c8-4086-ef11-ac21-000d3abee5ab", + "_modifiedby_value":"e86450b3-5882-ef11-ac20-000d3abee5ab", + "overriddencreatedon":null, + "importsequencenumber":null, + "talxis_decimal":2000000, + "talxis_currency":998472, + "talxis_memorydata":null, + "talxis_optionset":742070000, + "talxis_memorycolumns":null, + "talxis_memoryentitymetadata":null + } + ] +} +``` +
+ +
+ +> **_NOTE:_** You always need to include the @OData and @Microsoft fields for lookups. You should not do that for any other Data Types (dates, optionsets etc.), we calculate these values on client automatically + +## Columns + +Columns binding can be used to specify metadata for each column. It expects a stringified JSON array containing objects of column metadata. This object is based on the [PCF Dataset Column interface](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/column). If you do not specify metadata for a column, it will not be visible in the UI. + + +
+Example Columns Definition + +```json +[ + { + "name": "datetime", + "alias": "datetime", + "dataType": "DateAndTime.DateAndTime", + "displayName": "Date Time", + "order": 0, + "visualSizeFactor": 300 + }, + { + "name": "mail", + "alias": "mail", + "dataType": "SingleLine.Email", + "displayName": "Mail", + "order": 1, + "visualSizeFactor": 300, + "metadata": { + "IsValidForUpdate": true + } + }, + { + "name": "lookup", + "alias": "lookup", + "dataType": "Lookup.Simple", + "displayName": "Lookup", + "order": 2, + "visualSizeFactor": 300, + "metadata": { + "Targets": ["customLookup"] + } + }, + { + "name": "optionset", + "alias": "optionset", + "dataType": "OptionSet", + "displayName": "OptionSet", + "order": 3, + "visualSizeFactor": 300, + "metadata": { + "OptionSet": [ + { + "Color": "red", + "Label": "Option 1", + "Value": 1 + }, + { + "Color": "blue", + "Label": "Option 2", + "Value": 2 + } + ] + } + } +] +``` +
+
+ +The [PCF Dataset Column interface](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/reference/column) has also been extended with a `metadata` prop. This allows you to define/override [Xrm Attribute Metadata](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/attributemetadata?view=dataverse-latest) for each column. For example, you can see that we are setting Options for OptionSets in our example through `metadata` prop. That way, the provider will know what Label to use if we would request formatted value for that column. + +Depending on which provider you choose, a different minimal amount of props is required for the column to show in the UI: + +- FetchXml Provider: `name` and `isHidden` +- Memory Provider: `name`, `displayName` and [`dataType`](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/manifest-schema-reference/type) + +You can also specify virtual columns by ending the column name with `__virtual` suffix. This will let the provider know that it should not try to fetch any metadata for the column and it is up to you to specify them. You can then perform actions (`setValue`, `getValue`) on this column, just like on the classic one. + +## Entity Metadata + +Entity Metadata binding allows you to define/override any [Xrm Entity Metadata](https://learn.microsoft.com/en-us/dotnet/api/microsoft.xrm.sdk.metadata.entitymetadata?view=dataverse-sdk-latest). For example, you can change the `DisplayCollectionName`, so the UI can better describe your dataset. For Memory Provider, it is **required** to specify the `PrimaryIdAttribute` prop. The binding accepts a stringified JSON object that corresponts to the [Xrm Entity Metadata](https://learn.microsoft.com/en-us/dotnet/api/microsoft.xrm.sdk.metadata.entitymetadata?view=dataverse-sdk-latest) interface. + +## Bindings Summary + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property NameDescriptionOf TypeInputOutputUsageRequired
bindingFieldBinding FieldSingleLine.TextN/AN/Aboundtrue
DataProviderData Provider that the control will use to fetch data.Enum ("Memory" | "FetchXml")"FetchXml"N/Ainputtrue
DataData Source depending on the provider (FetchXml for FetchXml Provider, JSON array for Memory Provider).Multiple"<fetch><entity name="account"><attribute name="name"/></entity></fetch>"N/Ainputtrue
ColumnsJSON array containing the column definitions.Multiple[{"name": "name", "isHidden": false}]N/Ainputtrue
Entity MetadataOptional property allowing you to override/define Entity MetadataMultiple{"DisplayCollectionName": "Custom Collection Name"}N/Ainputfalse
HeightCan be used to force the control to always stay at fixed height.SingleLine.Text500pxN/Ainputfalse
EnableEditingEnable or disable editing functionality in the control.Enum ("Yes" | "No")"Yes"N/Ainputfalse
EnablePaginationEnable or disable pagination in the control.Enum ("Yes" | "No")"Yes"N/Ainputfalse
EnableFilteringEnable or disable filtering options in the control.Enum ("Yes" | "No")"Yes"N/Ainputfalse
EnableSortingEnable or disable sorting options in the control.Enum ("Yes" | "No")"Yes"N/Ainputfalse
EnableNavigationEnable or disable navigation options in the control.Enum ("Yes" | "No")"Yes"N/Ainputfalse
EnableOptionSetColorsEnable or disable OptionSet colors in the control.Enum ("Yes" | "No")"No"N/Ainputfalse
SelectableRowsDefines if and how rows can be selected.Enum ("None" | "Single" | "Multiple")"Single"N/Ainputfalse
EnableQuickFindEnable or disable the Quick Find feature in the control.Enum ("Yes" | "No")"No"N/Ainputfalse
+ +> **_NOTE:_** You can quickly demo the control locally through [PCF local harness](https://learn.microsoft.com/en-us/power-apps/developer/component-framework/debugging-custom-controls). Just make sure you switch the `_mock` variable `true`. + + + + + + + +