Percent Bar

The Percent Bar Function enables numeric columns to be viewed as a 'bar' where each cell is filled as a percentage of its value against the maximum value available for that column.

In other words, the width of the bar is proportional to the value in the column.

The Percent Bar must include one of 2 properties:

  • Column Comparison - Percent Bar value is calculated by comparing the cell value to another Column

  • Ranges - sets of Min and Max values with an associated colour, so that the Percent Bar colour will vary according to which range its value falls in.

    note

    Ranges were introduced in Version 7

    caution

    If AdapTable loads a pre-version 7 Percent Bar with no Ranges or Column Comparison, it will create one range based on the miminum and maximum values in that column.

Ranges

A Range defines a minimum and maxium value and colour, so that when the cell value falls inside the range, the bar displays the appropriate colour.

This is useful when wanting a traffic light effect - e.g. 0-30: Red; 31-70: Orange; 71-100: Green

There is no limit on how many ranges can be created.

Column Comparison

As an alternative to using Ranges, the Percent Bar can be created by comparing the Cell Value to that of another column in the row.

tip

This is useful where you might want to show an Amount as a propertion of a Fill.

Key Properties

There are a number of other properties available when creating a Percent Bar. These include:

  • setting a back colour for the cell (some users like the visual effect this provides) - the default is gray

  • displaying the actual value in the cell

  • displaying the cell value as a percentage of the maximum value in the range (or the highest range if there is more than one)

  • showing the cell value (and / or the percentage value) as a Tooltip

important

Percent Bars are like 'normal' columns and can be edited (if the column is editable) and filtered (if the column is filterable) like any other column.

UI Elements

Percent Bar includes the following UI Elements:

  • Popup - Lists current Percent Bars with Edit, Delete buttons, plus Add button to start Percent Bar Wizard

  • Column Menu - The Create Percent Bar (or for existing columns Edit Percent Bar) Menu Item opens the Percent Bar wizard for that column on the second step.

  • Context Menu - Edit Percent Bar Menu Item opens Percent Bar wizard for that column on second step.

Entitlements

Percent Bar Entitlement Rules:

  • Full: Everything is available to the User

  • Hidden: Everything is hidden from the User and no Percent Bars can be seen nor appear in menus.

  • ReadOnly: User can see columns with Percent Bars but not edit or delete them, nor add others.

Percent Bar Predefined Config

The Percent Bar Config contains a list of Percent Bars:

PropertyDescription
PercentBarsCollection of Percent Bars - contain either Ranges OR a Column Comparison

Percent Bar Config Example

export default {
PercentBar: {
PercentBars: [
{
ColumnId: 'InvoicedCost',
Ranges: [
{ Min: 0, Max: 500, Color: '#ff0000' },
{ Min: 500, Max: 1000, Color: '#ffa500' },
{ Min: 1000, Max: 3000, Color: '#008000' },
],
ShowValue: false,
},
{
BackColor: '#d3d3d3',
ColumnId: 'ItemCost',
DisplayPercentageValue: true,
DisplayRawValue: true,
Ranges: [{ Min: 0, Max: 200, Color: '#87cefa' }],
ShowValue: true,
},
{
ColumnId: 'CurrentFill',
ColumnComparison: {
MinValue: 0,
MaxValue: 'Quantity',
Color: 'brown',
},
ShowValue: true,
ShowToolTip: true,
},
],
},
} as PredefinedConfig;

In this example we have created Percent Bars for 3 Columns:

  • 'InvoicedCost': has 3 Ranges (0-500 Red, 500-1000 Orange, 1000-3000 Green)
  • 'ItemCost': has 1 Range, shows both the Cell Value and the equivalent Percent Value and has a back colour.
  • 'CurrentFill': has a Column Comparison against the 'Quantity' column

Percent Bar API

The Percent Bar Api section of AdapTable API has a number of methods to enable you to create, edit, clone, delete and retrieve layouts programmatically.

MethodDescription
addPercentBar(percentBar)Adds new Percent Bar to Adaptable State
deletePercentBar(columnId)Deletes Percent Bar from Adaptable State
editPercentBar(percentBar)Edits (replaces) existing Percent Bar
editPercentBarShowValue(showValue, columnId)Whether Percent Bar additionally displays cell's value
getAllPercentBar()Retrieves all Percent Bars in Adaptable State
getPercentBarByColumn(columnId)Retrieves Percent Bar for given column
getPercentBarMaxValue(percentBar, node)Gets Maximum Value for a Node to show in Percent Bar
getPercentBarMinValue(percentBar, node)Gets Minimum Value for a Node to show in Percent Bar
getPercentBarState()Retrieves Percent Bar section from Adaptable State
showPercentBarPopup()Opens Percent Bar popup screen

FAQ

Can we see the underlying value in the cell?

Yes - you can do this either at Design Time or at Run Time.

We used to be able to see negative and positive values in the same bar - why has that changed?

In Version 7 of AdapTable we introduced Ranges. These allow you to set multiple colours for the percent bar depending on the value. one result of this is that percent bars no longer show minus values the way that they did so previously.

Can I see see a Cell Value compared to another Column?

Yes, you can use a Column Comparison.

More Information