Dashboard Utility Overview

In BBj 15.0 and higher, access to full functionality of this feature requires an active Software Asset Management (SAM) subscription. See Benefits of ‘Software Asset Management” Feature Line.

Description

In BBj 14.0 and higher, the Dashboard Utility facilitates the visualization of data via dashboard widgets that may contain all kinds of information based on

  • Bar, stacked bar, and stacked percentage bar charts
  • Pie and ring charts
  • Line, XY, and area charts
  • Grids via the BBjGrid and BBjGridExWidget
  • JasperReports
  • HTML text and websites
  • Images

Feature List

Enhancements added in BBj 20.0 and higher:

  • Adds the GridExWidget to the Dashboard Utility, based on the BBjGridExWidget plug-in which is a fast, full-featured grid that offers filtering, grouping, pinning, pivoting, and rules-based styling.

Closed Enhancements added in BBj 19.0 and higher

  • Adds the ability to create a JasperViewerWidget based on a JasperView which won't take up valuable space for the toolbar and status bar.
  • Adds a JasperViewerWidget constructor that takes a report file, connection string, and report parameters to create an auto-fillable/refreshable JasperViewerWidget
  • Adds the ability to define your own popup menus for a dashboard widget which can replace the default right-click and/or Options popup menus.
  • Adds the ability to access a DashboardWidget's WidgetControl from any DashboardWidgetEvent.  Now the developer has access to both the data and UI classes for the DashboardWidget on which the event occurred.
  • Adds the ability to control whether a dashboard program should stop execution after encountering an error filling a widget via the FillErrorAction field variable on a Dashboard, DashboardCategory, or Widget.  You can set a Dashboard, DashboardCategory, or individual widget to ignore errors, warn the user of errors, or stop execution on errors.  The default behavior as of 18.20 is to ignore errors and continue execution.  In this case, all errors will be logged and widgets will show as much information as is available.  When possible, the widgets will also display an error indicator and a description of the error that occurred.
  • Adds the ability to set  a custom image or text to display over a widget that experiences an error via the setFillErrorDisplayImage() and setFillErrorDisplayText() methods.
  • Adds a JasperViewerWidget constructor and DashboardCategory::addJasperViewerDashboardWidget() method that takes a report file, connection string, and report parameters to create an auto-fillable/refreshable JasperViewerWidget.
  • Adds the ability to create a JasperViewerWidget based on a BBJasperView which won't take up valuable space for the tool bar and status bar.
  • Adds the ability to force whether the JasperViewerWidget should show a tool bar or not via the setHasToolBar() and getHasToolBar() methods.
  • Adds getFitType() and setFitType() methods to the JasperViewerWidget.
  • Adds a getView() method to the JasperViewerWidget which returns the underlying BBJasperView, regardless of whether a BBJasperViewerControl is used.
  • Adds the ability to set multiple domain and range threshold markers to ChartWidgets via the addChartDomainMarker() and addChartRangeMarker() methods, specifying the value, color, label, label color, and label position.
  • Adds the ability to enable data item labels for all category-based charts (BarChart, AreaChart, LineChart) and XYCharts via the setChartDataItemLabels() and setChartDataItemLabelFormat() methods, with the ability to control their format, color, and position.
  • Adds the ability use shorthand hexadecimal notion, e.g. #8CF, for all methods that take a hex color string.
  • Adds the ability to format the x-axis labels for XYCharts via the setChartDomainAxisFormat() method.
  • Adds the setChartFontStyles() method which allows you to easily modify all the styles of the various chart element fonts in one convenient method.

Closed Enhancements added in BBj 18.0 and higher

  • Adds getTitle() and setTitle() methods to the DashboardWindow.
  • Adds the setBusyText() method to the DashboardWindow and DashboardControl which allows you to customize the "Creating Widgets" message.
  • Adds the ability to discern on which part of the GridWidget the user clicked via a static field named ClickTarget.  This way the developer can tell if the user clicked on a cell, a row or column header, the scrollbar (in BUI), or the corner (when a grid has row and column headers).
  • Adds the ability to set the GridWidget's column background and foreground colors.
  • Adds the ability for developers to register a callback for grid events in the GridWidget.  This supports events for the BBjGrid as well as the GridWidgetRefreshEvent that occurs immediately after the GridWidget has been filled with data.  It is also possible to get access to the underlying BBjStandardGrid from the GridWidgetRefreshEvent.

Closed Enhancements added in BBj 17.0 and higher

  • Adds the ability to get the underlying BBjControl from the DashboardWidgetFilterSelectEvent.  Now if a user enters invalid data into a filter control, the custom filter selection routine can not only warn the user but can also reset the filter back to a reasonable value.
  • Adds the ability to show the BBjBusyIndicator with a configurable message when the DashboardCategory initially creates widgets.
  • Adds the ability to set the alignment for DashboardWidget titles.
  • Adds the ability to set the alignment for the GridWidget's column headers.
  • Adds a new setAutoResizeGrid() method that causes the GridWidget to size its columns based on the header and cell text, preventing data from being truncated.
  • Adds the ability to set whether the GridWidget is horizontally and/or vertically scrollable.
  • Adds the ability to distinguish between different types of refresh in the DashboardWidgetRefreshEvent.
  • Adds the ability to modify a DashboardWidget's filters, links, and title in custom code in response to an event.
  • Adds several methods to the Dashboard's HtmlViewWidget to aid in injecting and executing JavaScript, as well as the ability to specify different HTML and JavaScript for the popped-out version of the widget.
  • Adds the ability to register callbacks for BBjHtmlEvents that occur inside a BBjHtmlViewWidget, so that custom code can be executed when the page is loaded, a hyperlink is activated, etc.
  • Adds the ability to specify custom icons for the Dashboard and DashboardWidget via the ImageList and ImageListHiRes field variables.

Closed Enhancements added in BBj 16.0 and higher

  • Adds support for the BASIS_UTILITY_DEVICE_PIXEL_RATIO global string entry to force a particular DevicePixelRatio in utilities such as the Dashboard Utility and the BBJasperViewer
  • Adds the ability for Dashboard Utility widgets to be resizable when popped out
  • Adds the ability to optionally include a JDBC connection mode string when creating and filling SQL-based widgets, making it easier to manage authentication and other connection-specific properties
  • Adds user-editable filters to Dashboard Widgets. In addition to the previous list-based filter, widgets can now have filters based off of BBjListEdit and BBjEditBox controls

Closed Enhancements added in BBj 15.0 and higher

  • Adds a new Widget Wizard that generates BBj object-oriented code to create widgets, widget sets, or widget dashboard
  • Adds tips that display detailed information when left clicking on data in a chart widget
  • Adds user-selectable widget sizing, color themes, fonts, and font size on a per-category basis for dashboard charts
  • Adds the ability to view the data that comprises a DashboardWidget, or export it to a delimited file
  • Adds the ability to override either the left click, right click, or all click events on a dashboard widget
  • Adds the ability to populate dashboard widgets with a BBjRecordSet

Dashboard Utility Performance

Virtually all performance issues for the Dashboard Utility are related to aggregating data for the widgets.  By way of example, executing a slow SQL statement or filling a very large report widget can slow down the initial display of the entire dashboard.  The Dashboard Utility offers a way to analyze widget performance via a debug timing mode that outputs Dashboard Widget query timing to the  BBjServices Debug.log.<timestamp> log file in the <BBjHome>/log directory.  See this Bugzilla entry for details regarding how to enable logging and to download a sample program that analyzes the results and presents the data in a sortable grid.

Dashboard Utility Errors

When the Dashboard Utility experiences or throws a runtime error it will typically be in one of the following categories:

  • Error 256: An invalid parameter, such as an event type, was specified for callback. Attempting to add a non-unique object such as a DashboardCategory, DashboardWidget, DashboardWidgetFilter, or DashboardWidgetLink.

  • Error 300: An error occurred when filling a widget with data, e.g. an SQL error occurred when trying to build the record set for the widget.  These errors are logged in the BBjServices Debug.log.<timestamp> log file in the <BBjHome>/log directory.  The log file entry contains a timestamp, error number, line number on which the error occurred, the error message, and information about the widget including its name and title.

  • Error 305: An error occurred when setting a widget's column width percentages.

  • Error 306: An error occurred when setting a widget's column pinning.

  • Error 310: An error occurred when trying locate a custom font for the widget.

  • Error 313: An error occurred in one of the ChartWidget's color utility methods.

  • Error 320: An error occurred loading an image. This may occur when loading an ImageWidget, or when loading an image via the setFillErrorDisplayImage() or setChartEmptyDisplayImage() methods.

  • Error 330: An error occurred locating a specified file, such as the report file specified in the JasperViewerWidget's constructor.

  • Error 340: An error occurred locating BASIS plug-in components, such as the BBjGridExWidget or the ResultSet library.  You can install these components via the BBj Plugin Manager.

Dashboard Utility Errors in BBj 18.20+

As of BBj 18.20, the Dashboard Utility handles errors differently than previous versions.  Instead of dropping to console and displaying the error that occurred, the Dashboard Utility now attempts to recover from widget-based errors and continue execution.  

For example, if there's a problem filling a ChartWidget with data due to an SQL error, the utility will log the error and continue execution. The ChartWidget will still be visible, but depending on the type of error encountered it may be empty, partially filled, or it may display the text of the error message in the widget.

You can control how the utility handles error conditions, and it is possible to set a Dashboard, DashboardCategory, or an individual widget to ignore errors, warn the user of errors, or stop execution on errors. You can specify the behavior in your application code via the FillErrorAction field variable on a Dashboard, DashboardCategory, or Widget. If you set the FillErrorAction on a Dashboard object, all added DashboardCategories and their Widgets will inherit the setting. If you set the FillErrorAction on a DashboardCategory object, all added Widgets will inherit the setting.

You may also set the "BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION" global string entry either via code or in a configuration file to control the behavior instead of changing your application code. If the FillErrorAction is set via a global string it will override all default and programmatically set values for all widgets.

Here is an example showing how to set the behavior programmatically via an instantiated dashboard object:

dashboard!.setFillErrorAction(Dashboard.getON_FILL_ERROR_WARN())

Here are two examples showing how to set the FillErrorAction via a global string:

  1) Setting the global string entry in code, before creating any dashboards or widgets:

      temp$ = STBL("BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION", "1")

  2) Setting the global string entry in the config file, without changing any code:

      SET BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION = 1

The value that you provide (1 in the examples above) corresponds to static field variables for the Dashboard object and are listed below:

Static Field Variable Value Notes
ON_FILL_ERROR_IGNORE 0 The default behavior as of BBj 18.20
ON_FILL_ERROR_WARN 1 Optional new behavior as of BBj 18.20
ON_FILL_ERROR_STOP 2 Previous default behavior prior to BBj 18.20

The Dashboard Utility has default images and text that it displays on widgets that experienced an error, and it's possible to set a custom image or text to display over a widget that experiences an error via the setFillErrorDisplayImage() and setFillErrorDisplayText() methods.

To see the Dashboard Utility in action

  • From a browser, click on one of the Dashboard Demos from the BBx BUI Showcase page (no installation of BBj required)
  • After downloading and installing a packaged version of BBj that includes the Demos, run the <bbjhome>/utils/dashboard/demoDashboardBUISetup.bbj program and choose the (R)un option to launch a BUI program that demonstrates many of the Dashboard's capabilities

Furthermore, the Dashboard Utility facilitates the ability to embed dashboard widgets in an existing BBj, Visual PRO/5, or PRO/5 application.


 

 For complete Dashboard Utility documentation, including dashboard widgets, click here.  

Example Dashboard

See Also

The complete Dashboard Utility reference documentation

Dashboard Types

Dashboard Charts and Datasets

Dashboard Chart Customization

Dashboard Utility on the IDE Wiki