ViewerApiExtensionOptions Interface

Provides options for customizing the ViewerApiExtension.

Declaration

export interface ViewerApiExtensionOptions

Properties

onDashboardTitleToolbarUpdated Property

Specifies a handler for the event that occurs before the dashboard title toolbar is updated.

Declaration

onDashboardTitleToolbarUpdated?: (args: DashboardTitleToolbarUpdatedEventArgs) => void

Property Value

Type	Description
(args: DashboardTitleToolbarUpdatedEventArgs) => void	A function that is executed when the dashboard title toolbar is updated.

Remarks

Handle the DashboardTitleToolbarUpdated event to customize the dashboard title. For instance, you can add custom command buttons, create additional menus, add static texts, etc. The DashboardItemCaptionToolbarOptions class contains options used to customize a dashboard title’s elements (the ViewerToolbarItem objects).

Use the following event handlers depending on the platform:

HTML JavaScript: ViewerApiExtensionOptions.onDashboardTitleToolbarUpdated
ASP.NET Core: DashboardViewerApiOptionBuilder.OnDashboardTitleToolbarUpdated
ASP.NET MVC: DashboardControlClientSideEvents.DashboardTitleToolbarUpdated
ASP.NET Web Forms: ASPxClientDashboard.DashboardTitleToolbarUpdated

More information: Dashboard Title in the Web Dashboard.

onItemActionAvailabilityChanged Property

Specifies a handler for the event that occurs after the available interactivity actions have changed for the specific dashboard item.

Declaration

onItemActionAvailabilityChanged?: (args: ItemActionAvailabilityChangedEventArgs) => void

Property Value

Type	Description
(args: ItemActionAvailabilityChangedEventArgs) => void	A function that is executed after the available interactivity actions have changed for the specific dashboard item.

onItemCaptionToolbarUpdated Property

Specifies a handler for the event that occurs before the dashboard item caption toolbar is updated.

Declaration

onItemCaptionToolbarUpdated?: (args: ItemCaptionToolbarUpdatedEventArgs) => void

Property Value

Type	Description
(args: ItemCaptionToolbarUpdatedEventArgs) => void	A function that is executed when the dashboard item caption toolbar is updated.

Remarks

Handle the ItemCaptionToolbarUpdated event to customize the dashboard item’s caption. For instance, you can add custom command buttons, create additional menus, add static texts, etc. The DashboardItemCaptionToolbarOptions class contains options used to customize a dashboard item caption’s elements (the ViewerToolbarItem objects).

Use the following event handlers depending on the platform:

HTML JavaScript: ViewerApiExtensionOptions.onItemCaptionToolbarUpdated
ASP.NET Core: DashboardViewerApiOptionBuilder.OnItemCaptionToolbarUpdated
ASP.NET MVC: DashboardControlClientSideEvents.ItemCaptionToolbarUpdated
ASP.NET Web Forms: ASPxClientDashboard.ItemCaptionToolbarUpdated

More information: Dashboard Item Caption in the Web Dashboard.

onItemClick Property

Specifies a handler for the event that occurs when a user clicks a dashboard item.

Declaration

onItemClick?: (args: ItemClickEventArgs) => void

Property Value

Type	Description
(args: ItemClickEventArgs) => void	A function that is executed when a user clicks a dashboard item.

Remarks

See the following examples that show how to use the onItemClick property:

View Example: ASP.NET Core View Example: ASP.NET Web Forms View Example: ASP.NET MVC

onItemDrillDownStateChanged Property

Specifies a handler for the event that occurs when a drill-down/drill-up is performed.

Declaration

onItemDrillDownStateChanged?: (args: ItemDrillDownStateChangedEventArgs) => void

Property Value

Type	Description
(args: ItemDrillDownStateChangedEventArgs) => void	A function that is executed when a drill-down is performed.

Remarks

The ItemDrillDownStateChanged event is raised when an end-user performs drill-down or drill-up in a certain dashboard item. To determine the component name of this dashboard item, use the ItemName event parameter. Other event parameters include the following:

ItemDrillDownStateChangedEventArgs.action returns the action performed in the dashboard item. For example, ‘Down’ identifies a drill-down while ‘Up’ identifies a drill-up.
ItemDrillDownStateChangedEventArgs.values returns values from the current drill-down hierarchy. In OLAP mode, the ItemDrillDownStateChangedEventArgs.values property returns unique names instead of values.

WebDashboardDrillDownScheme

onItemElementCustomColor Property

Specifies a handler for the event allowing you to color the required dashboard item elements using the specified colors.

Declaration

onItemElementCustomColor?: (args: ItemElementCustomColorEventArgs) => void

Property Value

Type	Description
(args: ItemElementCustomColorEventArgs) => void	A function that is executed when coloring the required dashboard item elements.

Example

The following example shows how to color the dashboard item’s elements on the client. To do this, handle the ViewerApiExtensionOptions.onItemElementCustomColor event, get the item’s multidimensional data, and apply the color to the dashboard item’s element based on the condition.

The image below displays the dashboard items whose values are colored based on their values:

Chart: For 2014, values that exceed 30k are colored green, values below 17k are red, and values that fall into the range between 170k and 30k are gray.
Pies: Values below 80k are colored yellow.

View Example: ASP.NET Core View Example: ASP.NET Web Forms

ItemElementCustomColor_Web

elementCustomColor.js
Index.cshtml

function onBeforeRender(sender) {
    window['control'] = sender;

    var viewerApiExtension = control.findExtension('viewerApi');

    if (viewerApiExtension)
        viewerApiExtension.on('itemElementCustomColor', setColors);
}

function setColors(args) {

    var argumentAxis = 'Argument',
        seriesAxis = 'Series';

    var viewerApiExtension = control.findExtension('viewerApi');

    var chartClientData = viewerApiExtension.getItemData("chartDashboardItem1"),
        pieClientData = viewerApiExtension.getItemData("pieDashboardItem1");
    var currentElement = args.getTargetElement();

    if (args.itemName === "chartDashboardItem1") {
        var year = currentElement.getAxisPoint(seriesAxis).getValue();
        var value = chartClientData.getSlice(currentElement.getAxisPoint(argumentAxis)).
            getSlice(currentElement.getAxisPoint(seriesAxis)).
            getMeasureValue(chartClientData.getMeasures()[0].id).getValue();
        // For 2015, values that exceed 80k are colored in green, values below 40k are colored in red, 
        // and values that fall into the range between 40k and 80k are colored in gray.
        if (year == 2014) {
            if (value > 30000) {
                args.setColor("#336633");
            }
            else if (value < 17000) {
                args.setColor("#993300");
            }
            else if (value >= 17000 && value <= 30000) {
                args.setColor("#999999");
            }
        }
    }

    if (args.itemName === "pieDashboardItem1") {
        var value = pieClientData.getSlice(currentElement.getAxisPoint(argumentAxis)).
            getMeasureValue(pieClientData.getMeasures()[0].id).getValue();
        if (value < 80000)
            args.setColor("#fdb400");
    }
};

@page
@using DevExpress.DashboardWeb

<div style="position: absolute; left: 0; top: 0; right: 0; bottom: 0;">
@(Html.DevExpress().Dashboard("dashboardControl1")
    .ControllerName("DefaultDashboard")
    .Width("100%")
    .Height("100%")
    .WorkingMode(WorkingMode.Viewer)
    .OnBeforeRender("onBeforeRender")
)
</div>

onItemMasterFilterStateChanged Property

Specifies a handler for the event that occurs when the master filter state is changed.

Declaration

onItemMasterFilterStateChanged?: (args: ItemMasterFilterStateChangedEventArgs) => void

Property Value

Type	Description
(args: ItemMasterFilterStateChangedEventArgs) => void	A function that is executed when the master filter state is changed.

Remarks

The ViewerApiExtensionOptions.onItemMasterFilterStateChanged event occurs when filtering is applied or the state of the master filter item changes. Its e.values property allows you to obtain the selected values for the dashboard item that causes the event.

For instance, for the dashboard in the image below, the e.values property returns the following objects for the Grid dashboard item:

[['UK', 'Anne Dodsworth'], ['USA', 'Andrew Fuller']]

MasterFiltering_API_Web

For the Range Filter dashboard item, the e.values property returns the Date objects for minimum and maximum values in the selected range. The minimum is Sun Feb 01 2015 and the maximum is Sun Jan 31 2016.

The ViewerApiExtensionOptions.onItemActionAvailabilityChanged event occurs after the available interactivity actions are changed for the specific dashboard item.

onItemSelectionChanged Property

Specifies a handler for the event that occurs after the selection within the dashboard item is changed.

Declaration

onItemSelectionChanged?: (args: ItemSelectionChangedEventArgs) => void

Property Value

Type	Description
(args: ItemSelectionChangedEventArgs) => void	A function that is executed after the selection within the dashboard item is changed.

onItemVisualInteractivity Property

Specifies a handler for the event allowing you to provide custom visual interactivity for data-bound dashboard items that support element selection and highlighting.

Declaration

onItemVisualInteractivity?: (args: ItemVisualInteractivityEventArgs) => void

Property Value

Type	Description
(args: ItemVisualInteractivityEventArgs) => void	A function that is executed when you provide custom visual interactivity for data-bound dashboard items that support element selection and highlighting.

Remarks

The code snippet below shows how to add custom interactivity to dashboards:

View Example

See Also

Custom Interactivity in the Web Dashboard

onItemWidgetCreated Property

Specifies a handler for the event that occurs when the underlying UI/Data Visualization widget is created.

Declaration

onItemWidgetCreated?: (args: ItemWidgetEventArgs) => void

Property Value

Type	Description
(args: ItemWidgetEventArgs) => void	A function that is executed when the client widget is created.

Remarks

The Web Dashboard uses DevExtreme widgets to visualize dashboard item data. The onItemWidgetCreated property allows you to access these widgets and customize their settings. See Access to Underlying Widgets for details.

The ItemWidgetEventArgs.itemName property returns the component name of the dashboard item whose widget you can customize. Use the ItemWidgetEventArgs.getWidget property to access the corresponding underlying widget.

When the dashboard item is re-rendered, all events connected to dashboard item’s life cycle (onItemWidget…) are fired again.

Note

The onItemWidgetCreated event is not fired for a custom dashboard item.

See Also

Access to Underlying Widgets in DashboardControl

onItemWidgetOptionsPrepared Property

Specifies a handler for the event allowing you to access underlying UI/Data Visualization widgets and configure their options.

Declaration

onItemWidgetOptionsPrepared?: (args: ItemWidgetOptionEventArgs) => void

Property Value

Type	Description
(args: ItemWidgetOptionEventArgs) => void	A function that is executed before the client widget is prepared.

Remarks

Use the DashboardItemBaseEventArgs.dashboardItem property to get the dashboard item for which the event is raised. The options property provides access to its underlying widget’s options.

The example shows how to customize options of underlying widgets. Handle the onItemWidgetOptionsPrepared event to do the following:

Highlight a hovered grid row in the underlying dxDataGrid.
Disable a standard tooltip that appears when a user hovers over a chart’s series point.
Create a custom tooltip that appears when a user clicks a label on the chart’s argument axis. The onArgumentAxisClick property executes a function that invokes the custom tooltip.
Enable the animation for the dxChart and dxPieChart widgets.
Display a legend in the dxPieChart widget.

View Example

import { GridItem, ChartItem, PieItem} from 'devexpress-dashboard/model';
// ...
function customizeWidgetOptions(e) {
  if (e.dashboardItem instanceof GridItem) {
    e.options.hoverStateEnabled = true
  };
  if (e.dashboardItem instanceof ChartItem) {  
    e.options.tooltip = {
      enabled: false
    };
    e.options.animation = {
      enabled: true,
      duration: 1000
    };
    e.options.onArgumentAxisClick = function (info) {
      info.component.getAllSeries()[0].getPointsByArg(info.argument)[0].showTooltip()
    }
  };  
  if (e.dashboardItem instanceof PieItem) {    
    e.options.legend = {
      visible: true,
      border: {
          visible: true
      }
    };
    e.options.animation = {
      enabled: true,
      duration: 1000
    };
  }
}

onItemWidgetUpdated Property

Specifies a handler for the event that occurs when the underlying UI/Data Visualization widget is redrawn after the data used in this widget is changed.

Declaration

onItemWidgetUpdated?: (args: ItemWidgetEventArgs) => void

Property Value

Type	Description
(args: ItemWidgetEventArgs) => void	A function that is executed when the client widget is updated.

Remarks

When the dashboard item is re-rendered, all events connected to dashboard item’s life cycle (onItemWidget…) are fired again.

Note

The onItemWidgetUpdated event is not fired for a custom dashboard item.

See Also

Access to Underlying Widgets in DashboardControl

onItemWidgetUpdating Property

Specifies a handler for the event allowing you to access underlying UI/Data Visualization widgets.

Declaration

onItemWidgetUpdating?: (args: ItemWidgetEventArgs) => void

Property Value

Type	Description
(args: ItemWidgetEventArgs) => void	A function that is executed when the client widget is about to be updated.

Remarks

The Web Dashboard uses DevExtreme widgets to visualize dashboard items’ data. The onItemWidgetCreated property allows you to access these widgets and customize their settings. See Access to Underlying Widgets for details.

The ItemWidgetEventArgs.itemName property returns the component name of the dashboard item whose widget can be customized. Use the ItemWidgetEventArgs.getWidget property to access the corresponding underlying widget.

When the dashboard item is re-rendered, all events connected to dashboard item’s life cycle (onItemWidget…) are fired again.

Note

The onItemWidgetUpdating event is not fired for a custom dashboard item.

See Also

Access to Underlying Widgets in DashboardControl

onSelectedTabPageChanged Property

Specifies a handler for the event that occurs when the selected tab page is changed.

Declaration

onSelectedTabPageChanged?: (args: SelectedTabPageChangedEventArgs) => void

Property Value

Type	Description
(args: SelectedTabPageChangedEventArgs) => void	A function that is executed when the selected tab page is changed.