Conditional Formatter - Documentation | www.HtmlElements.com

Overview

Conditional Formatter represents a Smart Utility that allows formatting an array of data of type string, number or date. Depending on the condition property. Creating an instance of this class allows the user to preset all necessary formatting properties before calling the 'format' method.

To instantiate a Conditional Formatter object, the user has to include the following files to the head of the page:

  • smart.element.js - the base class;
  • smart.format.js - the JS file containing the class Conditional Formatter.

Initialization

A Conditional Formatter object can be instantiated by calling the ConditionalFormatter class constructor. It can also be instantiated by passing an argument, a JSON Array of objects representing the data to be formatted.

Example:

const data = [
    { columnOne: 'stringOne', columnTwo: new Date(2016,7,12), columnThree: 18, columnFour: 'letterA', columnFive: 12.5},
    { columnOne: 'stringTwo', columnTwo: new Date(2015,5,1), columnThree: 4, columnFour: 'letterB', columnFive: 7.4},
    { columnOne: 'stringThree', columnTwo: new Date(2017, 1, 23), columnThree: 5, columnFour: 'letterC', columnFive: 99.999}
];

const formatter = new Smart.Utilities.ConditionalFormatter(data);

Properties

ConditionalFormatter class provides the following properties:

  • data - the JSON Array containing the data for formatting. This property can be set when creating an instance of the ConditionalFormatter.

    Example:

    const formatter = new Smart.Utilities.ConditionalFormatter();

formatter.data = [
    { columnOne: 'stringOne', columnTwo: new Date(2016,7,12), columnThree: 18, columnFour: 'letterA', columnFive: 12.5},
    { columnOne: 'stringTwo', columnTwo: new Date(2015,5,1), columnThree: 4, columnFour: 'letterB', columnFive: 7.4},
    { columnOne: 'stringThree', columnTwo: new Date(2017, 1, 23), columnThree: 5, columnFour: 'letterC', columnFive: 99.999}
];
  • columns - Determines the columns which data will be formatted. Columns is of type Array and accepts one or many strings that represent the names of the columns.

    Example:

    const formatter = new Smart.Utilities.ConditionalFormatter(data);

formatter.columns = ['columnOne', 'columnFour'];
  • condition - Determines the type of formatting. There are several available formatting modes:
    • between - Matches all items that are between the 'min' and 'max' properties. This condition applies only to columns of type Number and Date.
    • contains - Matches all items that contain the value of the comparator in them.
    • doesNotContain - Matches all items that do not contain the value of the comparator in them.
    • duplicate - Matches all duplicate items.
    • dateOccur - Matches all items that correspond to the comparator. This condition applies only to columns of type Date.
    • equal - Matches all items that are equal to the comparator.
    • notEqual - Matches all items that are NOT equal to the comparator.
    • greaterThan - Matches all items that are greater than the comparator.
    • lessThan - Matches all items that are less than the comparator.
    • topNItems - Matches the top N items. N is determines by the comparator. Comparator must be a numeric value.
    • bottomNItems - Matches the bottom N items. N is determines by the comparator. Comparator must be a numeric value.
    • topNPercent - Matches the top N percent of items. N is determines by the comparator. Comparator must be a numeric value.
    • bottomNPercent - Matches the top N items. N is determines by the comparator. Comparator must be a numeric value.
    • aboveAverage - Matches all items that are above average. The average itself is not highlighted.
    • belowAverage - Matches all items that are below average. The average itself is not highlighted.
    • odd - Matches all odd items.
    • even - Matches all event items.
    • everyN - Matches every N item. N is determines by the comparator. Comparator must be a numeric value.
    • colorScale - Applies a Heat Map to all items in the column. The heat scale is calculated based on the min and max value in the column. Min and max values can be changed by setting the corresponding properties. The heat map can consist of 1 color by settings the color property or a colorScheme of multiple colors (from 2 to 5) by passing a numeric value to the colorScheme property: or by passing a string representing the name of the colorScheme:
    • colorBar - Applies a colored Progress Bar to all items indicating it's value compared to the column's min and max. The progress range is automatically calculated based on the min and max values in the column unless the user explicitly sets the min and max properties. Color Bars can have one color or use a colorScheme with multiple colors just like the colorScale:
    • iconSet - Applies a color icon to all items in the column. The color and direction of the icon is determined by the value of the cell compared to the column's min and max. The range is automatically calculated given the values in the column unless the user explicitly sets them through the min and max properties.

    Example:

    const formatter = new Smart.Utilities.ConditionalFormatter(data);

formatter.condition = 'iconSet';
  • comparator - the comparator is the value used for comparason based on the condition.

    The comparator is used only by conditions that require it. Here's the list of conditions that use the comparator:
    • contains - comparator should be of type string.
    • doesNotContain - comparator should be of type string.
    • dateOccure - comparator should be of type string and must match one of the following predefined values:
      • yesterday - matches all dates from the day before today.
      • today - matches all dates from today.
      • tomorrow - matches all dates from the day after today.
      • last7Days - matches last 7 days from today (including today).
      • lastWeek - matches all week days from last week.
      • thisWeek - matches all week days from this week.
      • nextWeek - matches all week days from next week.
      • lastMonth - matches all week days from last month.
      • thisMonth - matches all week days from this month.
      • nextMonth - matches all week days from next month.
      • lastYear - matches all week days from last year.
      • thisYear - matches all week days from this year.
      • nextYear - matches all week days from next year.
    • equal - comparator should be of type string/number.
    • notEqual - comparator should be of type string/number.
    • greaterThan - comparator should be of type number.
    • lessThan - comparator should be of type number.
    • topNItems - comparator should be of type number. Represents N in the condition.
    • bottomNItems - comparator should be of type number. Represents N in the condition.
    • topNPercent - comparator should be of type number. Represents N in the condition.
    • bottomNPercent - comparator should be of type number. Represents N in the condition.
    • everyN - comparator should be of type number. Represents N in the condition.

    Example:

    const formatter = new Smart.Utilities.ConditionalFormatter(data);

formatter.condition = 'contains';
formatter.comparator = 'a';
  • min/max - the properties are used only by a some conditions that require a range limit. In the case where the target column contains dates the min and max values represent dates in miliseconds.

    The min and max properties are used by the following conditions:
    • between - min and max should be of type number.
    • colorScale - min and max should be of type number.
    • colorBar - min and max should be of type number.
    • iconSet - min and max should be of number.
    • odd - min and max should be of type number.
    • event - min and max should be of type number.
    • everyN - min and max should be of type number.

    Example:

    const formatter = new Smart.Utilities.ConditionalFormatter(data);

formatter.condition = 'between';
formatter.min = 10;
formatter.max = 20;

//Column contains Dates
formatter.min = new Date(2018, 1 ,1).getTime();
formatter.max = new Date(2018, 11 ,1).getTime();
  • color - Determines the formatting color. Can be any hex code of an actual color. Color property is not set by default. All formatting conditions require a color except 'colorScale', 'colorBar' and 'iconSet' which use a colorScheme instead.

    Example:

    const formatter = new Smart.Utilities.ConditionalFormatter(data);

formatter.color = '#63BE7B'; //Green
  • colorScheme - Determines the colorScheme that will be used by the conditions : 'colorScale', 'colorBar', 'iconSet'. Accepts a number representing the index of one of the predefined colorScales or a string describing the name of the predefined colorScheme. Here's the list of all predefined colorSchemes: 
    { name: 'scheme01', colors: ['#307DD7', '#AA4643', '#89A54E', '#71588F', '#4198AF'] },
{ name: 'scheme02', colors: ['#7FD13B', '#EA157A', '#FEB80A', '#00ADDC', '#738AC8'] },
{ name: 'scheme03', colors: ['#E8601A', '#FF9639', '#F5BD6A', '#599994', '#115D6E'] },
{ name: 'scheme04', colors: ['#D02841', '#FF7C41', '#FFC051', '#5B5F4D', '#364651'] },
{ name: 'scheme05', colors: ['#25A0DA', '#309B46', '#8EBC00', '#FF7515', '#FFAE00'] },
{ name: 'scheme06', colors: ['#0A3A4A', '#196674', '#33A6B2', '#9AC836', '#D0E64B'] },
{ name: 'scheme07', colors: ['#CC6B32', '#FFAB48', '#FFE7AD', '#A7C9AE', '#888A63'] },
{ name: 'scheme08', colors: ['#3F3943', '#01A2A6', '#29D9C2', '#BDF271', '#FFFFA6'] },
{ name: 'scheme09', colors: ['#1B2B32', '#37646F', '#A3ABAF', '#E1E7E8', '#B22E2F'] },
{ name: 'scheme10', colors: ['#5A4B53', '#9C3C58', '#DE2B5B', '#D86A41', '#D2A825'] },
{ name: 'scheme11', colors: ['#993144', '#FFA257', '#CCA56A', '#ADA072', '#949681'] },
{ name: 'scheme12', colors: ['#105B63', '#EEEAC5', '#FFD34E', '#DB9E36', '#BD4932'] },
{ name: 'scheme13', colors: ['#BBEBBC', '#F0EE94', '#F5C465', '#FA7642', '#FF1E54'] },
{ name: 'scheme14', colors: ['#60573E', '#F2EEAC', '#BFA575', '#A63841', '#BFB8A3'] },
{ name: 'scheme15', colors: ['#444546', '#FFBB6E', '#F28D00', '#D94F00', '#7F203B'] },
{ name: 'scheme16', colors: ['#583C39', '#674E49', '#948658', '#F0E99A', '#564E49'] },
{ name: 'scheme17', colors: ['#142D58', '#447F6E', '#E1B65B', '#C8782A', '#9E3E17'] },
{ name: 'scheme18', colors: ['#4D2B1F', '#635D61', '#7992A2', '#97BFD5', '#BFDCF5'] },
{ name: 'scheme19', colors: ['#844341', '#D5CC92', '#BBA146', '#897B26', '#55591C'] },
{ name: 'scheme20', colors: ['#56626B', '#6C9380', '#C0CA55', '#F07C6C', '#AD5472'] },
{ name: 'scheme21', colors: ['#96003A', '#FF7347', '#FFBC7B', '#FF4154', '#642223'] },
{ name: 'scheme22', colors: ['#5D7359', '#E0D697', '#D6AA5C', '#8C5430', '#661C0E'] },
{ name: 'scheme23', colors: ['#16193B', '#35478C', '#4E7AC7', '#7FB2F0', '#ADD5F7'] },
{ name: 'scheme24', colors: ['#7B1A25', '#BF5322', '#9DA860', '#CEA457', '#B67818'] },
{ name: 'scheme25', colors: ['#0081DA', '#3AAFFF', '#99C900', '#FFEB3D', '#309B46'] },
{ name: 'scheme26', colors: ['#0069A5', '#0098EE', '#7BD2F6', '#FFB800', '#FF6800'] },
{ name: 'scheme27', colors: ['#FF6800', '#A0A700', '#FF8D00', '#678900', '#0069A5'] },

//Classic Color Scales
{ name: 'scheme28', colors: ['#63BE7B', '#FDD17F', '#F8696B'] },
{ name: 'scheme29', colors: ['#F8696B', '#FDD17F', '#63BE7B'] },
{ name: 'scheme30', colors: ['#63BE7B', '#FCFCFF', '#F8696B'] },
{ name: 'scheme31', colors: ['#F8696B', '#FCFCFF', '#63BE7B'] },
{ name: 'scheme32', colors: ['#5A8AC6', '#FCFCFF', '#F8696B'] },
{ name: 'scheme33', colors: ['#F8696B', '#FCFCFF', '#5A8AC6'] },
{ name: 'scheme34', colors: ['#FCFCFF', '#F8696B'] },
{ name: 'scheme35', colors: ['#F8696B', '#FCFCFF'] },
{ name: 'scheme36', colors: ['#63BE7B', '#FCFCFF'] },
{ name: 'scheme37', colors: ['#FCFCFF', '#63BE7B'] },
{ name: 'scheme38', colors: ['#63BE7B', '#FFEF9C'] },
{ name: 'scheme39', colors: ['#FFEF9C', '#63BE7B'] },

//Additional
{ name: 'scheme40', colors: ['#000000', '#8b0000 ', '#FFFF00', '#FFFFFF'] }, //Incandescent
{ name: 'scheme41', colors: ['#63BE7B', '#FDD17F ', '#F8696B', '#FF69B4'] }, //4 colors 
{ name: 'scheme42', colors: ['#63BE7B', '#FDD17F ', '#FDD17F', '#F8696B'] }, //4 colors, 2 are the same
{ name: 'scheme00', colors: ['#63BE7B', '#FDD17F', '#FDD17F', '#FDD17F', '#F8696B'] }, //5 colors, 3 are the same

    Example

    const formatter = new Smart.Utilities.ConditionalFormatter(data);

//by index
formatter.colorScheme = 0;

//or by name
formatter.colorScheme = 'scheme01';

Methods

ConditionalFormatter contains the following methods:

  • format - the main method that formats the cells based on the condition and returns an object of keys and values. Every key of the returned object represents the name of a formatted column. Every value represent an object with keys that match the row numbers (indexes) and values containing the inline styles that have to be applied.

    Format method can be called without any arguments if the columns, condition, color and comparator(if necessary) properties are already set.

    Example:

    const formatter = new Smart.Utilities.ConditionalFormatter(data);

formatter.condition = 'topNItems';
formatter.comparator = 5;
formatter.color = '#FF69B4';
formatter.columns = ['columnThree', 'columnFive']; //Multiple Column formatting

const dataStyles = formatter.format();

    Format method can also be called by passing three arguments: condition, columns, comparator.

    Example:

    const formatter = new Smart.Utilities.ConditionalFormatter(data);

formatter.colorScheme = 'scheme28';

//colorScale doesn't need a comparator
const dataStyles = formatter.format('colorScale', ['columnThree']);

Output

The result from calling the format function is an object with the following structure: 

{
    columnName: {
        rowIndex: { 
            {
                styleName: styleValue
            }
        },
        ...
    },
    ...
}
  • columnName - the name of the column that is being checked. If columns property is set to more than one column the resulted object will contain more than one key - value pair, one for every column.
    • rowIndex - a number that represents the actual index of the row inside the column that has to be formatted with the styles that are located in the value argument of the object.
      • styleName - The key of the object. Represents the name of the style, for example: 'background-color' or '--icon-set-rotation-angle' (a custom CSS variable), etc.
      • styleValue - The value of the object. Represents the value of the styleName, for example: '#F8696B' ( HEX representation of a color), '90deg' ( a rotation angle for a transform operation), etc.

Note:

Since some of the styles returned from the object can be Custom CSS Variables it is recommended to apply the styles via the HTMLElement.style.setProperty() method, like so: 
const gridCell = document.getElementById('gridCell');

gridCell.style.setProperty('--icon-set-rotation-angle', '90deg');