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 for the Web Dashboard.

constructor(model, container, options)

Initializes a new instance of the CustomItemViewer class.

Declaration

constructor(
    model: DevExpress.Dashboard.Model.CustomItem,
    container: DevExpress.core.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	Custom item settings.

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?: DevExpress.Dashboard.Model.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?: DevExpress.Dashboard.Model.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: DevExpress.Dashboard.Model.ICustomDataRow) => boolean

Property Value

Type
(row: ICustomDataRow) => boolean

iterateData Property

Iterates data rows for a custom item.

Declaration

iterateData: (action: (item: DevExpress.Dashboard.Model.ICustomDataRow) => void) => void

Property Value

Type	Description
(action: (item: ICustomDataRow) => void) => void	A 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.

See the Simple Table custom dashboard item code to find an example of the iterateData implementation:

View Example: ASP.NET Core View Example: Angular View Example: React

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: DevExpress.Dashboard.Model.ICustomDataRow) => boolean

Property Value

Type	Description
(row: ICustomDataRow) => boolean	A 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:

_onClick(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);

You can find and download the full example on GitHub:

View Example: ASP.NET Core View Example: Angular View Example: React

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

Disposes of all resources associated with this CustomItemViewer.

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<DevExpress.Dashboard.Model.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
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.

See the getExportInfo method in the FunnelD3 custom dashboard item code to find an export implementation example:

View Example: ASP.NET Core View Example: Angular View Example: React

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
): DevExpress.Dashboard.Model.CustomPropertyValueType

Parameters

Name	Type	Description
propertyName	string	A string value that is the name of the custom property from the meta data.

Returns

Type	Description
CustomPropertyValueType	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: DevExpress.Dashboard.Model.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: DevExpress.core.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’s changed content; false, to render item content from scratch.
afterRenderCallback	any	The current parameter is for internal use.

Remarks

When you interact with a custom item and add changes to it, you need to update the custom item view. The renderContent method is called while item content is rendering. Override this method and add custom logic to display the item content. Use the changeExisting parameter that indicates whether to update a custom item’s changed content or render it from scratch.

If you define the ICustomItemMetaData.bindings section in the item’s metadata, the custom item content is not rendered (the renderContent method is not called) until you add at least one measure or dimension in the Web Dashboard’s UI.
If the ICustomItemMetaData.bindings section is not defined in the custom item metadata JSON, the Web Dashboard control renders the custom item initially.

Note

Do not set IDs for DOM elements in the renderContent method call. When the custom item is maximized, its viewer part (CustomItemViewer is copied with all its elements and the element ID will not be unique on the page.

setSelection(values) Method

Sets a selection in the custom item.

Declaration

setSelection(
    values: Array<Array<any>>
): void

Parameters

Name	Type
values	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