A Format Column is a column that is given specific Style and / or Display Format properties that are always (i.e. unconditionally) rendered.
Format Column differs from the Conditional Styles Module because the latter only applies the style when a particular condition is met.
However Format Column will always style the column irrespective of the data contained in the cell.
Format Column Properties
The Format Column Module enables a number of changes to be made to a column. These include:
Users set the Column's style by selecting the fore, back and border colours and various font properties.
The style in a Format Column has lowest last level of style-application preference, so any Flashing Alerts, Quick Search highlights or Conditional Styles will be applied ahead of it.
For numeric columns 2 special styles - Gradient Column and Percent Bar - can be applied
This defines where the style is applied. Options are:
one (or more) Columns
one (or more) DataTypes (e.g. String, Number, Date etc)
an entire Row (Scope of 'All')
See Scope for more information.
Format Column offers complex styles applied in place of the more basic Style.
This is only applicable if the
Scope is a single, numeric column
The Gradient Numeric Style enables a Column to be styled dynamically so that each cell is coloured according to its value in relation to a minimum and maximum value.
The minimum and values to create the gradient for each cell can come from Ranges or a Column Comparison.
A Range defines a minimum and maxium value and colour, so that the cell is coloured using the cell value against the range's boundaries.
There is no limit on how many ranges can be created.
ReverseGradient to true in Ranges where you want the cell to be darker the lower the cell value
As an alternative to using Ranges, the Gradient Numeric Style can be created by comparing each Cell Value to that of another column in the row.
This is useful where you might want to show fill the Gradient using the cell Value as a % fill of another column's value.
The Percent Bar Numeric Style enables numeric columns to be viewed as a 'bar' where each cell is filled - and coloured - 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.
As with the Gradient style, a Percent Bar must include either Ranges or a Column Comparison.
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 Numeric Style can be created by comparing each 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.
Percent Bar Properties
3 other properties are available when creating a Percent Bar Numeric Style:
Cell back colour (default is gray)
Show cell value as actual value, percentage value or not at all
Show a Tooltip providing cell value or percentage value or not at all
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.
These 2 styles were introducted in Adaptable Rx and replace the deprecated Percent Bar and Gradient Column modules
By default Format Columns do not style when the row is grouped, as it rarely makes sense to do so.
To change this behaviour set
IncludeGroupedRows to true when defining the Format Column.
Checkbox Columns are boolean columns where AdapTable will automatically display a checkbox - checked if the cell value is true.
If the Column is ReadOnly the checkbox is disabled but the check mark remains visible
All that is required is simply to provide a list of boolean columnIds which should display a checkbox.
When a checkbock is clicked / unclicked the CheckboxColumnClickedEvent is fired by AdapTable.
The Display Format sets how the value in the column will be formatted, so it matches the precise requirements of users.
Setting a Display Format does NOT change the underlying cell value.
Display Formats can be set for:
Numeric Columns: users can use the Number Formatter to set values for:
- Fraction Separator
- Integer Separator
- Fraction Digits
- Integer Digits
- Negative Parentheses
String Columns: users can use the String Formatter to:
- trim text
- set to upper case
- set lower case.
Date Columns: users can use the Date Formatter to set their own date pattern (or select one of the presets).
The full list of available DateTime patterns is here
The Format Column can be set so that contents in the cells will align to the left, right or center.
The Header (aka caption) of the Column can be set to a new value.
This does not effect the ColumnId property which is how the column is referenced in Predefined Config
Format Column includes the following UI Elements:
Popup - Shows a list of existing Format Columns with Edit and Delete buttons. Plus an Add button to start the Format Column Wizard which facilitates the creation and editing of Format Columns. Each row in the popup is fully editable.
Column Menu - Numeric columns have a
Create Format ColumnMenu Item which starts the Format Column wizard; for columns already displaying as a Format Column it says
Edit Format Column.
Format Column Entitlement Rules:
Full: Everything is available to the User
Hidden: Everything is hidden from the User
ReadOnly: User can see Format Column styles defined in Predefined Config but not add, edit, delete them
Format Column Predefined Config
The Format Column section of Predefined Config enables the provision of multiple formats at design-time.
In this example we have created 7 Format Columns:
- Order Id has Visual Style of lime green with a red fore colour and a CellAlignment of 'Center'
- LastUpdatedTime has Display Format with pattern of 'HH:mm:ss' to show just time
- Order Date has a Visual Style of bold and italicised and with a smaller font and a Display Format with pattern of 'yyyyMMdd'
- ChangeLastOrder has Display Format to show negative numbers in parantheses and new Header text
- InvoicedCost has Display Format to show '£' sign and 2 decimal places
- OrderCost has Display Format to separate integer thousands with a space, a '$' prefix and '(AUD)' suffix
- Bid has a CellAlignment of 'Center'
- Country has Display Format to show text in upper case
- Amount has a Gradient Numeric Style with 3 Ranges
How does this Module differ from the Conditional Styles Module?
The Conditional Styles Module applies the style on when a particular condition is met. Format Column will always style the column; it is best used when a user wants a particular column to have a distinctive background or font.
If a Conditional Style condition is met, which style will get applied?
The Conditional Style will take preference over a Format Column Style. The order of preference for styles is:
Can I apply more than one Format to a column?
No. A column can only have one Format Column
Can we show a currency in the Display Format?
Yes. Create a prefix (or suffix) as appropriate
Can we set negative numbers to appear in parentheses?
Yes. Check the Parentheses checkbox in the Display Format stage of the wizard.
Can we show percentages?
Yes, this is a common requirement which is typically done by setting the Multiplier property to 100 and the Suffix to '%'
Can divide numbers e.g. show 50,000 as 50K?
Yes, use the multiplier as a divider (so in this case it would be 0.001) and then add a suffice of 'K'
Can we see just the time portion of a Date?
Yes. Set the Display Format to show the time portion only (e.g. see the 'HH:mm:ss' preset which displays the time using a 24 hour clock)
If we show no fractions do you round the number?
Yes, AdapTable will round the number automatically e.g. setting 11.87 to 0 fractions will display '12'.
Gradient Style FAQ
Can I merge Gradient and Percent Bar styles for the same column?
No, they are 2 separate ways of displaying column data and each has a separate implementation - although both share common properties. You need to use one or the other.
Percent Bar Style FAQ
Can we see the underlying value in the cell?
Yes - you can do this either at Design Time or at Run Time.
Can I see see a Cell Value compared to another Column?
Yes, you can use a Column Comparison.