CustomItemViewer Class
A custom dashboard item.
Declaration
export class CustomItemViewer extends baseItem
Remarks
A 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.
constructor(model, container, options)
Initializes a new instance of the CustomItemViewer
class.
Declaration
constructor(
model: CustomItem,
container: dxElement,
options: any
)
Parameters
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. |
Properties
canDrillDown Property
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.
Declaration
canDrillDown: (row?: ICustomDataRow) => boolean
Property Value
Type |
---|
(row?: ICustomDataRow) => boolean |
canMasterFilter Property
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.
Declaration
canMasterFilter: (row?: ICustomDataRow) => boolean
Property Value
Type |
---|
(row?: ICustomDataRow) => boolean |
drillDown Property
Allows you to display detail data for the custom item’s UI object. This object should be associated with a specified data row.
Declaration
drillDown: (row: ICustomDataRow) => boolean
Property Value
Type |
---|
(row: ICustomDataRow) => boolean |
iterateData Property
Iterates data rows for a custom item.
Declaration
iterateData: (action: (item: ICustomDataRow) => void) => void
Property Value
Type | Description |
---|---|
(action: (item: ICustomDataRow) => void) => void | A custom function that is executed for the specified data row. |
Remarks
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);
});
setMasterFilter Property
Allows you to set a master filter for the custom item’s UI object. This object should be associated with a specified data row.
Declaration
setMasterFilter: (row: ICustomDataRow) => boolean
Property Value
Type | Description |
---|---|
(row: ICustomDataRow) => boolean | A custom function that is executed when you pass a custom data row. |
Remarks
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);
Methods
allowExportSingleItem Method
Specifies whether end-users can export a custom item as a single dashboard item.
Declaration
allowExportSingleItem(): boolean
Returns
Type | Description |
---|---|
boolean | true, if end-users can export a custom item as a single dashboard item; otherwise, false. |
Remarks
Use the getExportInfo method to provide the export result during exporting.
clearSelection Method
Allows you to clear a selection in the custom item.
Declaration
clearSelection(): void
Remarks
Important
You need to override this method to reset the viewer selection.
contentHeight Method
Returns the item content height (without header).
Declaration
contentHeight(): number
Returns
Type | Description |
---|---|
number | An integer value that is the item content height, not including the header pane height. |
contentWidth Method
Returns the item content width.
Declaration
contentWidth(): number
Returns
Type | Description |
---|---|
number | An integer value that is the item content width. |
dispose Method
Declaration
dispose(): void
getBindingValue(propertyName) Method
Returns an array of objects that allows you to get information about the binding value.
Declaration
getBindingValue(
propertyName: string,
index?: number
): Array<ICustomItemBindingValue>
Parameters
Name | Type | Description |
---|---|---|
propertyName | string | A string value that is the name of the binding property from the meta data. |
index | number | The binding property index. Use this parameter if the current data binding is an array. |
Returns
Type | Description |
---|---|
Array<ICustomItemBindingValue> | An array of data binding values. |
getExportInfo Method
Returns an object that is used as an export result.
Declaration
getExportInfo(): CustomItemExportInfo
Returns
Type | Description |
---|---|
CustomItemExportInfo | A CustomItemExportInfo object that contain an image in the ASCII format using the Base64 scheme. |
Remarks
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.
Note
See the getExportInfo method in the FunnelD3 custom dashboard item code to find an export implementation example: FunnelD3.
getInfo Method
For internal use.
Declaration
getInfo(): any
Returns
Type |
---|
any |
getMasterFilterMode Method
Declaration
getMasterFilterMode(): string
Returns
Type |
---|
string |
getPropertyValue(propertyName) Method
Returns an array of objects that allows you to get information about the custom property value.
Declaration
getPropertyValue(
propertyName: string
): any
Parameters
Name | Type | Description |
---|---|---|
propertyName | string | A string value that is the name of the custom property from the meta data. |
Returns
Type | Description |
---|---|
any | An array of custom properties. |
initializeData(newOptions) Method
Declaration
initializeData(
newOptions: any
): void
Parameters
Name | Type |
---|---|
newOptions | any |
isSelected(row) Method
Specifies whether the custom item’s UI object is selected. This object should be associated with a specified data row.
Declaration
isSelected(
row: ICustomDataRow
): boolean
Parameters
Name | Type | Description |
---|---|---|
row | ICustomDataRow | A specified data row. |
Returns
Type | Description |
---|---|
boolean | true, if the custom item’s UI object is selected; otherwise, false. |
renderContent(element, changeExisting) Method
Renders the custom dashboard item.
Declaration
renderContent(
element: dxElement,
changeExisting: boolean,
afterRenderCallback?: any
): void
Parameters
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. |
afterRenderCallback | any | The current parameter is for internal use. |
Remarks
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.
setSelection(values) Method
Sets a selection in the custom item.
Declaration
setSelection(
values: Array<Array<any>>
): void
Parameters
Name | Type |
---|---|
values | Array<Array<any>> |
Remarks
Override this method to set the Master Filtering using API.
setSize(width, height) Method
Sets the content size.
Declaration
setSize(
width: number,
height: number
): void
Parameters
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. |
Remarks
Important
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.
subscribe(propertyName, callback) Method
Allows you to react on and subscribe to property changes.
Declaration
subscribe(
propertyName: string,
callback: (newValue: any) => void
): any
Parameters
Name | Type | Description |
---|---|---|
propertyName | string | A string value that is a name of the property from the meta data. |
callback | (newValue: any) => void |
Returns
Type |
---|
any |