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.
Ranges were introduced in Version 7
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.
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.
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.
This is useful where you might want to show an Amount as a propertion of a Fill.
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
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.
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 BarMenu Item opens Percent Bar wizard for that column on second step.
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:
|PercentBars||Collection of Percent Bars - contain either Ranges OR a Column Comparison|
Percent Bar Config Example
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.
|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|
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.