A custom dashboard item.
export class CustomItemViewer extends baseItemA custom item is a separate JavaScript extension that is integrated into the Web Dashboard and provides standard item functionality such as data shaping operations, interactivity, export, etc.
To learn more about custom items, go to Create a Custom Item.
See also: Custom Items on GitHub.
Initializes a new instance of the CustomItemViewer class.
constructor(model: CustomItem, container: dxElement, options: any)| Name | Type | Description |
|---|---|---|
| model | CustomItem | A custom item model. |
| container | dxElement | A container where the item content is rendered. It is an HTML Element or a jQuery Element when you use jQuery. |
| options | any | A custom item options. |
Indicates whether end-users can drill down by clicking on the custom item's UI object. This object should be associated with a specified data row.
canDrillDown: (row?: ICustomDataRow) => boolean| Type | Description |
|---|---|
| (row?: ICustomDataRow) => boolean |
Indicates whether end-users can filter data by clicking on the custom item's UI object. This object should be associated with a specified data row.
canMasterFilter: (row?: ICustomDataRow) => boolean| Type | Description |
|---|---|
| (row?: ICustomDataRow) => boolean |
Allows you to display detail data for the custom item's UI object. This object should be associated with a specified data row.
drillDown: (row: ICustomDataRow) => boolean| Type | Description |
|---|---|
| (row: ICustomDataRow) => boolean |
Iterates data rows for a custom item.
iterateData: (action: (item: ICustomDataRow) => void) => void| Type | Description |
|---|---|
| (action: (item: ICustomDataRow) => void) => void | A custom function that is executed for the specified data row. |
Use the ICustomDataRow.getDisplayText and ICustomDataRow.getValue properties to get a value and a display name of the data row, respectively.
Refer to SimpleTable GitHub page to find an example of iterateData implementation:
this.iterateData(function(rowDataObject) {
var valueTexts = rowDataObject.getDisplayText('customDimensions').concat(rowDataObject.getDisplayText('customMeasure'));
_this._addTableRow(valueTexts, false);
});
Allows you to set a master filter for the custom item's UI object. This object should be associated with a specified data row.
setMasterFilter: (row: ICustomDataRow) => boolean| Type | Description |
|---|---|
| (row: ICustomDataRow) => boolean | A custom function that is executed when you pass a custom data row. |
The following code is a snippet from the Funnel D3 item's source code and shows the interactivity implementation:
FunnelD3Item.prototype._onClick = function(e) {
if (!this._hasArguments() || !e.label) return;
var row = e.label.raw.data;
if (this.canDrillDown(row)) this.drillDown(row); else if (this.canMasterFilter(row)) {
this.setMasterFilter(row);
this._update();
}
};
Pass null in the setMasterFilter method to clear the master filter:
this.setMasterFilter(null);
Specifies whether end-users can export a custom item as a single dashboard item.
allowExportSingleItem(): boolean| Type | Description |
|---|---|
| boolean | true, if end-users can export a custom item as a single dashboard item; otherwise, false. |
Use the getExportInfo method to provide the export result during exporting.
Allows you to clear a selection in the custom item.
clearSelection(): voidYou need to override this method to reset the viewer selection.
Returns the item content height (without header).
contentHeight(): number| Type | Description |
|---|---|
| number | An integer value that is the item content height, not including the header pane height. |
Returns the item content width.
contentWidth(): number| Type | Description |
|---|---|
| number | An integer value that is the item content width. |
dispose(): voidReturns an array of objects that allows you to get information about the binding value.
getBindingValue(propertyName: string, index?: number): Array<ICustomItemBindingValue>| Name | Type | Description |
|---|---|---|
| propertyName | string | A string value that is the name of the binding property from the meta data. |
| Name | Type | Default | Description |
|---|---|---|---|
| index | number | null | The binding property index. Use this parameter if the current data binding is an array. |
| Type | Description |
|---|---|
| Array<ICustomItemBindingValue> | An array of data binding values. |
Returns an object that is used as an export result.
getExportInfo(): CustomItemExportInfo| Type | Description |
|---|---|
| CustomItemExportInfo | A CustomItemExportInfo object that contain an image in the ASCII format using the Base64 scheme. |
Override this method and provide an object containing the image field. Encode the image in the ASCII format using the Base64 scheme to display a custom item in the exported document.
Note that getExportInfo is a synchronous method and it cannot be used with libraries exporting data asynchronously. You can export your custom item to an image when the custom item rendering is updated and caches the resulting image. After that return the cached image in the getExportInfo method.
See the getExportInfo method in the FunnelD3 custom dashboard item code to find an export implementation example: FunnelD3.
For internal use.
getInfo(): any| Type | Description |
|---|---|
| any |
getMasterFilterMode(): string| Type | Description |
|---|---|
| string |
Returns an array of objects that allows you to get information about the custom property value.
getPropertyValue(propertyName: string): any| Name | Type | Description |
|---|---|---|
| propertyName | string | A string value that is the name of the custom property from the meta data. |
| Type | Description |
|---|---|
| any | An array of custom properties. |
initializeData(newOptions: any): void| Name | Type | Description |
|---|---|---|
| newOptions | any |
Specifies whether the custom item's UI object is selected. This object should be associated with a specified data row.
isSelected(row: ICustomDataRow): boolean| Name | Type | Description |
|---|---|---|
| row | ICustomDataRow | A specified data row. |
| Type | Description |
|---|---|
| boolean | true, if the custom item's UI object is selected; otherwise, false. |
Renders the custom dashboard item.
renderContent(element: dxElement, changeExisting: boolean, afterRenderCallback?: any): void| Name | Type | Description |
|---|---|---|
| element | dxElement | A container where the item content is rendered. It is an HTML Element or a jQuery Element when you use jQuery. |
| changeExisting | boolean | true, to update only a custom item changed content; false, to render an item content from scratch in any case. |
| Name | Type | Default | Description |
|---|---|---|---|
| afterRenderCallback | any | null | The current parameter is for internal use. |
When you interact with a custom item and add some changes in it, you need to update the custom item view. The renderContent method is called while item content is rendering. Override this method and provide a custom logic to display the item content. Use the changeExisting parameter that indicates whether to update a custom item changed content or render it from scratch in any case.
Sets a selection in the custom item.
setSelection(values: Array<Array<any>>): void| Name | Type | Description |
|---|---|---|
| values | Array<Array<any>> |
Override this method to set the Master Filtering using API.
Sets the content size.
setSize(width: number, height: number): void| Name | Type | Description |
|---|---|---|
| width | number | An integer value that is the pane width, including header. |
| height | number | An integer value that is the pane height, including header. |
You need to override this method to update the content size (for instance, when a dashboard layout is changed). The method override's code should call the base setSize method.
Allows you to react on and subscribe to property changes.
subscribe(propertyName: string, callback: (newValue: any) => void): any| Name | Type | Description |
|---|---|---|
| propertyName | string | A string value that is a name of the property from the meta data. |
| callback | (newValue: any) => void |
| Type | Description |
|---|---|
| any |