Tutorial 46: How to use Gauge Chart

This tutorial describes how to use the gauge chart.

Formspider gauge chart component (also known as dial chart or speedometer chart) uses a single needle to show information as a reading on a dial. On the gauge chart, the value for the needle is read on a colored data range. This chart type is often used in executive dashboard reports to show key business indicators. It’s a great tool to help visualize percentages, as well as other fixed-range amounts for end users.

Formspider gauge chart consists of the chart definition (maximum/minimum value, title, interval marker’s count/label…) and the color ranges definition (bands). It can display a value provided by a datasource or it can be used without a datasource binding, through the api_chart.setValue API.

The following example shows a gauge chart and its attributes:

Gauge chart and its attributes

The attributes of the chart definition are as follows:

Attribute Description Example Value
title title of the gauge chart Fix Percentage
minimumValue first value to be displayed on the gauge axis 0
maximumValue last value to be displayed on the gauge axis 100
majorTicks count of the major interval markers to be displayed on the gauge axis. Major interval markers divide the segment between minimumValue and maximumValue into equal parts. Two major interval markers are statically displayed for the minimumValue and the maximumValue, therefore a majorTicks value lesser than 2 will be ignored by Formspider. 6
minorTicks count of the minor interval markers to be displayed between two consecutive major intervals. Minor intervals divide the segment between two consecutive major intervals into equal parts. 1
unitsLabel label to be displayed as the unit of the chart value %
unitsLabelPosition position of the units label relative to chart value (Left or Right) Right
majorTicksLabel determines whether a label will be displayed or for each major interval marker Y
ticksColor color of the interval markers (majorTicks and minorTicks) White

The attributes of the band definition are as follows:

Attribute Description Example Value
minimumValue first value of the range 0
maximumValue last value of the range 60
color color of the range Red

Open Formspider IDE and click “New Application” under the “File” menu. The “New Application” dialog shows up. Enter “gaugeChart” as the name of the application and “HR” as its Datasource Schema name.  If you are using Formspider Online, you do not need to enter database schema name since your account is already configured to use your online database. Leave other fields empty and click “OK”. This creates the “gaugeChart” application with a default mainframe (called “mainFrame”) and a default panel (called “mainPanel”).

Creating Model

Create a Datasource Definition for your chart. Expand the Datasource Definitions accordion, select the “Datasource Definitions” node and click the “+” button. Alternatively, you may right click the “Datasource Definitions” node and select “New” from the pop up menu. The “New Datasource Definition” Dialog shows up. Enter “gaugeDS” as “Name” and select “Query” radio button from “Based On” section, this selection means that you will enter a SQL query to retrieve data from the HR schema.

Creating “gaugeDS” datasource definition

Select the “Query” node in the navigation tree on the left. Enter the following “SQL Statement” to the datasource definition:

select bugs.*
      ,round((bugs.fixed / bugs.found) * 100) as percentage
from
(
  select 'FS Alpha 0.1' as build_name, 110 as found, 75 as fixed from dual
  union all
  select 'FS Alpha 0.2', 78, 12 from dual
  union all
  select 'FS Beta 0.5', 150, 85 from dual
  union all
  select 'FS Beta 0.7', 55, 50 from dual
  union all
  select 'FS 1.0', 99, 75 from dual
  union all
  select 'FS 1.1', 25 , 25 from dual
) bugs

Entering Query for “gaugeDS” datasource definition

Click “OK” to save and close the “New Datasource Definition” dialog. This creates the “gaugeDS” datasource definition and the “gaugeDS1″ datasource. You will use the “gaugeDS1” datasource as the datasource of your chart.

Creating User Interface

Double click the “mainPanel” under the “Panels” node of the “Containers” navigation tree to open it in the editor. Add a gauge chart with a range from 0 to 100 , having 6 major interval markers (each major interval having 1 minor interval marker) and 3 bands colored red, yellow and green. The panel XML looks like:

<panel>
  <tableLayout>
    <row>
      <cell childWidth="280" childHeight="210">
        <gaugeChart name="gaugeChart" title="Fix Percentage" dataSource="gaugeDS1" valueColumn="PERCENTAGE" minimumValue="0" maximumValue="100" unitsLabel="%" unitsLabelPosition="Right" minorTicks="1" majorTicks="6" majorTicksLabel="Y" ticksColor="White">
          <bands>
            <band color="Red" minimumValue="0" maximumValue="60"/>
            <band color="Yellow" minimumValue="60" maximumValue="80"/>
            <band color="Green" minimumValue="80" maximumValue="100"/>
          </bands>
        </gaugeChart>
      </cell>
    </row>
  </tableLayout>
</panel>

Press “Run on Web” button to run your application. Note that the gauge chart displays the value 68, which is the value of the percentage column for the current row of your “gaugeDS1” datasource.

Gauge chart displayed

Refreshing Gauge Chart

When the value of the datasource column bound to the gauge chart changes, the chart won’t be automatically refreshed by Formspider. Instead, the gauge chart component should be refreshed using the api_chart.refresh API.

For instance, you have to refresh your chart when the current row of the “gaugeDS1” datasource is changed. To achieve this, you will call the api_chart.refresh API whenever the current row of the “gaugeDS1” datasource is changed.

In your datasource schema, create a package called “gaugeChart_pkg” and open your newly created “gaugeChart_pkg” package in your favorite PL/SQL Editor. Add a procedure named “refreshGaugeChart” and ensure that the procedure is exposed in the package specification. This procedure uses api_chart.refresh API to refresh the gauge chart.

procedure refreshGaugeChart is
begin
  api_chart.refresh('mainPanel.gaugeChart');
end;

In Formspider IDE, expand the “Actions” accordion, select the “Actions” node, click the “+” button to create a new action. Alternatively, you may right click the “Actions” node and select “New” from the pop up menu. The “New Action” dialog shows up. Enter “refreshGaugeChart” as the action name and “gaugeChart_pkg.refreshGaugeChart” as the procedure. Click “OK” to save your action.

Creating “refreshGaugeChart” action

To refresh the chart whenever the current row of the datasource is changed, you will use “Current Row Changed” event of the “gaugeDS1” datasource. Expand “Datasource Definitions” root node from “Datasource Definitions” accordion. Expand “gaugeDS” and “Datasources” nodes respectively and double-click “gaugeDS1” node to edit “gaugeDS1” datasource, the edit dialog is opened. Select “Events” tab and choose “refreshGaugeChart” from “Current Row Changed” combobox. Click “OK” to save your change.

Assigning “refreshGaugeChart” action to “Current Row Changed” event of the “gaugeDS1” datasource

To be able to change the current row of the “gaugeDS1” from the UI, open the “mainPanel” XML and add a grid displaying “Build Name”, “Bug Found”, “Bug Fixed” and “Fix Percentage” information using the “gaugeDS1” datasource.

<panel>
  <tableLayout>
    <row>
      <cell childWidth="280" childHeight="210">
        <gaugeChart name="gaugeChart" title="Fix Percentage" dataSource="gaugeDS1" valueColumn="PERCENTAGE" minimumValue="0" maximumValue="100" unitsLabel="%" unitsLabelPosition="Right" minorTicks="1" majorTicks="6" majorTicksLabel="Y" ticksColor="White">
          <bands>
            <band color="Red" minimumValue="0" maximumValue="60"/>
            <band color="Yellow" minimumValue="60" maximumValue="80"/>
            <band color="Green" minimumValue="80" maximumValue="100"/>
          </bands>
        </gaugeChart>
      </cell>
    </row>
    <row>
      <cell hAlign="Full" vAlign="Full">
        <grid dataSource="gaugeDS1">
          <column headerLabel="Build Name">
            <textLabel column="BUILD_NAME"/>
          </column>
          <column headerLabel="Bug Found">
            <textLabel column="FOUND"/>
          </column>
          <column headerLabel="Bug Fixed">
            <textLabel column="FIXED"/>
          </column>
          <column headerLabel="Fix Percentage">
            <textLabel column="PERCENTAGE"/>
          </column>
        </grid>
      </cell>
    </row>
  </tableLayout>
</panel>

Run the application again, note that when you select a row from the grid, the gauge chart is refreshed following the percentage value of the selected row as expected.

Gauge chart refreshed following the current percentage value