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.


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
  • JasperReports
  • HTML text and websites
  • Images

In BBj 15.00 and higher, the Dashboard Utility offers the following enhancements:

  • 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 Dashboard Widget, 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

In BBj 16.00 and higher, the Dashboard Utility offers the following enhancements:

  • 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

In BBj 17.00 and higher, the Dashboard Utility offers the following enhancements:

  • 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

In BBj 18.00 and higher, the Dashboard Utility offers the following enhancements:

  • 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.

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 throws a runtime error it will typically be in one of the following categories:

  • 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, and the error message.

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

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

  • Error 303: An error occurred in one of the ChartWidget's color utility 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

Dashboard Types

Dashboard Charts and Datasets

Dashboard Chart Customization



Copyright BASIS International Ltd. BBj®, Visual PRO/5®, PRO/5®, and BBx® are registered trademarks.