Format Column

A Format Column is a column that is given specific Style and / or Display Format properties that are always (i.e. unconditionally) rendered.

important

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:

Style

Users set the Column's style by selecting the fore, back and border colours and various font properties.

note

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.

tip

For numeric columns 2 special styles - Gradient Column and Percent Bar - can be applied

Scope

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.

Column Styles

Format Column offers complex styles applied in place of the more basic Style.

warning

This is only applicable if the Scope is a single, numeric column

Gradient

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.

Ranges

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.

tip

Set ReverseGradient to true in Ranges where you want the cell to be darker the lower the cell value

Column Comparison

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.

note

This is useful where you might want to show fill the Gradient using the cell Value as a % fill of another column's value.

Percent Bar

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.

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 Numeric Style can be created by comparing each Cell Value to that of another column in the row.

note

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

note

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.

important

These 2 styles were introducted in Adaptable Rx and replace the deprecated Percent Bar and Gradient Column modules

tip

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 Column

Checkbox Columns are boolean columns where AdapTable will automatically display a checkbox - checked if the cell value is true.

note

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.

Display Format

The Display Format sets how the value in the column will be formatted, so it matches the precise requirements of users.

warning

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:

    • Prefix
    • Suffix
    • Fraction Separator
    • Integer Separator
    • Fraction Digits
    • Integer Digits
    • Multiplier
    • 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).

    note

    The full list of available DateTime patterns is here

Settings

Cell Alignment

The Format Column can be set so that contents in the cells will align to the left, right or center.

Header Name

The Header (aka caption) of the Column can be set to a new value.

caution

This does not effect the ColumnId property which is how the column is referenced in Predefined Config

UI Elements

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 Column Menu Item which starts the Format Column wizard; for columns already displaying as a Format Column it says Edit Format Column.

Entitlements

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.

const demoConfig: PredefinedConfig = {
FormatColumn: {
FormatColumns: [
// Set a Style and Cell Alignment for OrderId
{
Scope: {
ColumnIds: ['currency'],
},
Style: {
BackColor: '#d4fb79',
ForeColor: '#8b0000',
},
CellAlignment: 'Center',
},
// Set a Time-based Display Format for LastUpdatedTime
{
Scope: {
ColumnIds: ['LastUpdatedTime'],
},
DisplayFormat: {
Formatter: 'DateFormatter',
Options: {
Pattern: 'HH:mm:ss',
},
},
},
// Set both a Style and a (Date-based) Display Format for OrderDate
{
Scope: {
ColumnIds: ['OrderDate'],
},
Style: {
FontWeight: 'Bold',
FontSize: 'XSmall',
FontStyle: 'Italic',
},
DisplayFormat: {
Formatter: 'DateFormatter',
Options: {
Pattern: 'yyyyMMdd',
},
},
},
// Set Display Format of negative parentheses for ChangeLastOrder
// and change the Header (caption) to 'Order Change'
{
Scope: {
ColumnIds: ['ChangeLastOrder'],
},
HeaderName: 'Order Change',
DisplayFormat: {
Formatter: 'NumberFormatter',
Options: {
Parentheses: true,
},
},
},
// Set a Display Format of £ and 2 dp for InvoicedCost
{
Scope: {
ColumnIds: ['InvoicedCost'],
},
DisplayFormat: {
Formatter: 'NumberFormatter',
Options: {
FractionDigits: 2,
Prefix: '£',
},
},
},
// Set Display Format of $ with 'AUD' suffix and integer space separator for OrderCost
{
Scope: {
ColumnIds: ['OrderCost'],
},
DisplayFormat: {
Formatter: 'NumberFormatter',
Options: {
FractionDigits: 2,
IntegerSeparator: ' ',
Prefix: '$',
Suffix: '(AUD)',
},
},
},
// Set the Cell Aligment of the 'Bid' Column to the right
{
Scope: {
ColumnIds: ['bid'],
},
CellAlignment: 'Right',
},
// Set text in the 'Country' Column to be upper case
{
Scope: {
ColumnIds: ['country'],
},
DisplayFormat: {
Formatter: 'StringFormatter',
Options: {
Case: 'Upper',
},
},
CellAlignment: 'Center',
},
// Set Amount to use a Gradient Numeric Style using 3 Ranges
// with the bottom (red) range displaying a reverse Gradient
{
Scope: {
ColumnIds: ['Amount'],
},
ColumnStyle: {
GradientStyle: {
CellRanges: [
{
Min: 0,
Max: 50,
Color: 'Red',
ReverseGradient: true,
},
{
Min: 50,
Max: 100,
Color: 'orange',
},
{
Min: 100,
Max: 150,
Color: 'DarkGreen',
},
],
},
},
CellAlignment: 'Center',
},
// Set Fill to use a Percent Bar Numeric Style comparing the cell to Amount
// Show both cell text and percent value (on gray background) and a tooltip
{
Scope: {
ColumnIds: ['Fill'],
},
ColumnStyle: {
PercentBarStyle: {
ColumnComparison:{
MinValue: 0,
MaxValue: 'Amount',
Color: 'Brown'
},
CellText: ['CellValue', 'PercentageValue'],
ToolTipText: ['PercentageValue'],
BackColor: 'Gray'
},
},
},
],
},
} as PredefinedConfig;

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

FAQ

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:

  • Flashing Alert

  • Quick Search

  • Conditional Style

  • Format Column

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.

More Information