igxGrid Column Data Types and Templates Specification

Owned by

Team Name

Developer Name

Designer Name

Requires approval from

Peer Developer Name | Date:
Stefan Ivanov | Date: 12 Apr 2021

Signed off by

Radoslav Mirchev | Date: 13 Apr 2021
Konstantin Dinev | Date: 15 Nov 2022

Revision History

Version	Users	Date	Notes
1.0	Yoanna Ivanova	07/24/2020	Initial Draft
2.0	Zdravko Kolev, Yoanna Ivanova	04/09/2021	Currency, Percent, Datetime
2.1	Zdravko Kolev	04/20/2021	Update test plan
3.0	Konstantin Dinev	11/15/2022	Image
4.0	Bozhidara Pachilova	08/15/2024	Column editorOptions property

1. Overview

The different default templates for various types of data shown in different columns of the grid are crucial for ease of comprehension and distinguishing between the different meanings that columns have in large amounts of data shown in tabular form. The default value for column dataType is a string.

Number column type

Number column

String column type

String column

DateTime column type

DateTime column

Date column type

Date column

Time column type

Time column

Boolean column type

Boolean column

Currency column type

Currency column

Percent column type

Currency column

Image column type

Image column

Objectives

Providing a default handling of number, string, date, boolean, currency, percent and image column data types
Enabling data type-specific templates
RTL support and support for different display formats based on locale settings
Editing of cell's value
Increment/decrement of numeric value with keyboard arrow keys (number, currency, percent)
ARIA support

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

Default handling for Boolean data type columns.
Default handling for Currency and Percent data type columns.
Default handling for Datetime and Time data type columns.
Default handling for Image data type columns.
To be able to perform sorting with any data type columns.
To be able to perform filtering operations with any data type columns.
To be able to perform editing operations with any data type columns.
To be able to perform grouping operations with any data type columns.
To have all operations disabled by default for image data type columns.

2. User Stories

Number data type

Developer stories:

Story 1: As a developer, I want to be able to change the value programmatically through the API, so that I have control over the data.
Story 2: As a developer, I want to be able to specify the format of negative numbers e.g. -23 or (23), so that I have control over how they are displayed.
Story 3: As a developer, I want to be able to change the format of number value as an integer or non-integer number, so that I can cover different types of numbers.
Story 4: As a developer, I want to be able to enter specify the number of digits after the decimal point, so that I have control over the number format.
Story 5: As a developer, I want to be able to enter a thousand separator e.g. 1 000 000 or 1,000,000 so that end users can distinguish large numbers more precisely.
Story 6: As a developer, I want to be able to format the number value based on locale settings, so that it is shown based on the display formats that the end-user use.

End-user stories:

Story 1: As an end-user, I want to be able to enter different types of numbers e.g. integer, so that I can cover different conditions.
Story 2: As an end-user, I expect that the number column has a right horizontal alignment so that it can be distinguished from the string value.
Story 3: As an end-user, I expect that the number column has RTL support so that it can cover other language formats.

Note: When using up/down arrow keys the value should increment/decrement with a step based on the digitsInfo - minFractionDigits (The minimum number of digits after the decimal point. Default is 0.)

String data type

Developer stories:

Story 1: As a developer, I want to be able to change the value programmatically through the API, so that I have control over the data.
Story 2: As a developer, I expect that very long strings are automatically trimmed and ellipsis is added, so that they can fit the available column width.
Story 3: As a developer, I want to be able to format strings e.g. display them only as upper case, so that I have control over the display.

End-user stories:

Story 1: As an end-user, I want to be able to enter characters e.g. letters, spaces, punctuation, digits, emojis, so that I can write various combinations of characters.
Story 2: As an end-user, I want to be able to enter lowercase and uppercase letters, so that I can write names of people, cities, etc.
Story 3: As an end-user, I expect that the string column has a left horizontal alignment, so it looks like Excel.
Story 4: As an end-user, I expect that the string column has RTL support so that it supports different languages.

DateTime, Date and Time data types

Developer stories:

Story 1: As a developer, I want to be able to change the datetime portions e.g. day, month, year, hours, minutes, and seconds through the API, so that I have control over the data.

DateTime

<igx-column field="OrderDate" 
    [dataType]="'dateTime'">
</igx-column>

Date

<igx-column field="OrderDate" 
    [dataType]="'date'">
</igx-column>

Time

<igx-column field="OrderDate" 
    [dataType]="'time'">
</igx-column>

Note: This is applicable for Date and Time type columns as well. The date or time portion will be based on the column dataType.

Story 2: As a developer, I want the datetime/date/time value 'format' to change based on 'grid.locale' property. If the grid locale value is not set, value to be determined based on the global Angular application LOCALE_ID.

LOCALE_ID

import { LOCALE_ID } from '@angular/core';
...

 @Component({
    selector: 'app-component.sample',
    templateUrl: 'grid-component.sample.html',
    providers: [{provide: LOCALE_ID, useValue: 'fr-FR' }]
})

Set Grid's locale

<igx-grid locale="'fr-FR'"...>
</igx-grid>

Story 3: As a developer, I want to be able to customize the 'format' and 'timezone' of the datetime/date/time value by passing format options - leveraging the [pipeArgs] column input.

public options = {
  format: 'longTime',
  timezone: 'UTC'
};
public formatOptions = this.options;

<igx-column field="OrderDate" 
    [pipeArgs]="formatOptions" 
    [dataType]="'dateTime'">
</igx-column>

Note: This is applicable for Date and Time type columns as well. Based on the column type a certain portion of the datetime value will be used.

Story 4: As a developer, I want to still be able to pass a custom date pipe through ng-template.

<igx-grid #grid1 [data]="data | async" [autoGenerate]="true" [dataType]="'dateTime'"></igx-grid>

<!-- Through template with the Angular currency pipe -->
<ng-template let-value>
  {{ value | date:'medium'}}
</ng-template>

Note: This is applicable for Date and Time type columns as well. Based on the column type a certain portion of the datetime value will be used.

Story 5: As a developer, I want to be able to perform sorting and filtering based on the relying value. In the case of:
- DateTime column - The operation will be performed on the whole datetime value.
- Time column - The operation will be performed only on the time portion of the value, the date portion will be ignored.
- Date column - The operation will be performed only on the date portion of the value, the time portion will be ignored.

Note: The custom template should take precedence over the column data type.

Story 6: As a developer, I want to have the date pickers used in the grid to be controlled by the grid locale property. If the grid locale is “FR”, I want the same locale to be used by the igx-date-picker or igx-date-range-picker.
Story 7: As a developer, I want to be able to control the weekStart property of the date pickers used in the grid. The IColumnPipeArgs interface to include a weekStart property along with the format, display, timezone, etc.:

const pipeArgs: IColumnPipeArgs = { 
   weekStart: WEEKDAYS.Monday // or just a number 
   format: 'longDate', 
   timezone: 'UTC', 
   digitsInfo: '1.1-2' 
} 

export interface IColumnPipeArgs { 
    /** The first week day to be be displayed in calendar when filtering or editing a date column */ 
    weekStart?: WEEKDAYS | number; 
    format?: string; 
    timezone?: string; 
    digitsInfo?: string; 
    currencyCode?: string; 
    display?: string; 
}

<igx-column dataType="date" [pipeArgs]="pipeArgs"></igx-column>

Story 8: As a developer, I want to be able to customize the input format of the built-in cell editors without having to retemplate the entire editor cell. The IColumnEditorOptions interface includes a dateTimeFormat, property that can define this format.

export interface IColumnEditorOptions {
    /** A custom or a predefined format string used for the built-in editors of date/time columns */
    dateTimeFormat?: string;
}

const editorOptions: IColumnEditorOptions = {
    dateTimeFormat: 'MM/dd/YYYY',
}

<igx-column field="sampleDate" dataType="date" [editorOptions]="editorOptions"></igx-column>

Story 9: As a developer, I want the default cell editors' input format to be inferred from the column's pipeArgs.displayFormat in case I have not set the editorOptions.dateTimeFormat property. The condition for this is that the displayFormat contains only numeric date-time parts or such that can be handled by the editors.
Story 10: As a developer, I want the default cell editors' input format, if not set through the editorOptions.dateTimeFormat or pipeArgs.displayFormat properties, to fallback to the format based on the 'grid.locale' property, or the global Angular application LOCALE_ID.
Story 11: As a developer, I want the defined by me cell editors' input format to be applied to the different filter inputs (quick filter, ESF, Advanced filter) in addition to the grid cell.

End-user stories:

Story 1: As an end-user, I want to be able to set a preferred datetime value through an input, so that I can change its display value in the table.
Story 2: As an end-user, I expect that the date column has a left horizontal alignment, so it is distinguished from the number column type.
Story 3: As an end-user, when using a column of type DateTime I expect to change the cell value with an input editor that accesses both the date and time portion of the value.

Story 4: As an end-user, when using a column of type Date I expect to change the cell value with a DatePicker editor.

Story 5: As an end-user, when using a column of type Time I expect to change the cell value with a TimePicker editor.

Boolean data type

Developer stories:

Story 1: As a developer, I want to have the boolean value display as check or clear material icons instead of true or false by default, so that it is easier and quicker for the end-user to distinguish them.
Story 2: As a developer, I want to change the boolean value for the column through the API, so that I have direct control over them.
Story 3: As a developer, I want to be able to change the default way boolean columns are visualized by providing a template, so I have control over the visualization.

End-user stories:

Story 1: Аs an end-user, I want to be able to visually identify what is the current value of a boolean column so that I can distinguish the values quickly.
Story 2: Аs an end-user, I want to be able to edit the current value of a boolean column so that I can change the state.
Story 3: Аs an end-user, I expect that the boolean column has a central horizontal alignment so that the icons are more readable and visually clear.

Currency data type

Developer stories:

Story 1: As a developer, I want to have the currency value displayed with a dollar, euro, or any other currency sign based on grid.locale (if not set, grid.locale fallbacks to app LOCALE_ID)

LOCALE_ID

import { LOCALE_ID } from '@angular/core';
...

 @Component({
    selector: 'app-component.sample',
    templateUrl: 'grid-component.sample.html',
    providers: [{provide: LOCALE_ID, useValue: 'fr-FR' }]
})

Result:

Initial state

Set Grid's locale

<igx-grid [locale]="'fr-FR'" [data]="data">
</igx-grid>

Story 2: As a developer, I want to be able to customize the 'decimal point (digitsInfo)', 'currencyCode' and 'display' of the currency value by passing a format options - leveraging the [pipeArgs] column input:

public options = {
  digitsInfo: '3.4-4',
  currencyCode: 'USD',
  display: 'symbol-narrow'
};
public formatOptions = this.options;

<igx-column field="UnitsInStock" 
    [pipeArgs]="formatOptions" 
    [dataType]="'currency'">
</igx-column>

Result without pipeArgs:

Without pipeArgs

Result with pipeArgs:

With set pipeArgs

Note: When using up/down arrow keys the value should increment/decrement with a step based on the digitsInfo - minFractionDigits (The minimum number of digits after the decimal point. Default is 0.)

Story 3: As a developer, I want to be able to see the currency symbol while editing a cell. The position is based on the locale value (left or right):

In edit mode

Story 4: As a developer, I want to still be able to pass a custom currency pipe through ng-template (online sample):

<igx-grid #grid1 [data]="data | async" [autoGenerate]="true" [dataType]="'currency'"></igx-grid>

<!-- Through template with the Angular currency pipe -->
<ng-template let-value>
  {{ value | currency:'USD':'symbol':'1.0-0'}}
</ng-template>

Note: The custom template should take precedence over the column data type.

Story 5: As a developer, I want to still be able to pass a custom currency pipe through a column formatter(online sample):

  // Through column formatter property
  public formatCurrency(value: number) {
    return `$${value.toFixed(0)}`;
  }

  init(column: IgxColumnComponent, template) {
    switch (column.field) {
      ...
      case "Open Price":
        column.formatter = this.formatCurrency;
        break;
      default:
        return;
    }

Note: The [formatter] should take precedence over the column data type.

End-user stories:

Story 1: Аs an end-user, I want to be able to visually identify what is the current value of a currency column so that I can distinguish the values quickly.
Story 2: Аs an end-user, I want to be able to edit the current value of a currency column.
Story 3: As an end-user, I want to see the currency format applied to the Summary row:

Initial state

Story 4: As an end-user, I want to see the currency format applied to the Filtering UI:

Initial state

Percent data type

Developer stories:

Story 1: As a developer, I want to have the cell value displayed with percent (%) symbol when the column dataType is set to 'percent':

Initial state

Story 2: As a developer, I want to be able to customize the 'decimal point (digitsInfo)' - leveraging the [pipeArgs] column input:

public options = {
  digitsInfo: '2.2-3'
};
public formatOptions = this.options;

<igx-column field="UnitsInStock" 
    [pipeArgs]="formatOptions" 
    [dataType]="'percent'">
</igx-column>

Result without pipeArgs:

Without digits info

Result with pipeArgs:

With digits info

Note: When using up/down arrow keys the value should increment/decrement with a step based on the digitsInfo - minFractionDigits (The minimum number of digits after the decimal point. Default is 0.)

Story 3: As a developer, I want to be able to see the percent symbol while editing a cell and modify the underlying data. Also, a preview of the 'percent' equivalent should be shown:

Preview value

Story 4: As a developer, I want to still be able to pass a custom currency pipe through ng-template.

Note: The custom template should take precedence over the column data type.

Story 5: As a developer, I want to still be able to pass a custom currency pipe through a column formatter.

Note: The [formatter] should take precedence over the column data type.

End-user stories:

Story 1: Аs an end-user I want to be able to visually identify what is the value of a percent column so that I can distinguish the values from the other columns quickly.
Story 2: Аs an end-user I want to be able to edit the current value of a percent column. The underlying data source value should be edited, not a formatter equivalent of it.
Story 3: As an end-user, I want to see the percent symbol part of the Summary row.
Story 4: As an end-user, I want to be able to distinguish negative from positive percent values by text color.

Image data type

Developer stories:

Story 1: As a developer, I want to have the cell value coming as image urls displayed as images when column dataType is set to image:

[Initial state]

Story 2: As a developer, I want to have the cell value coming as image urls be picked up for image extensions and be automatically recognized as images making the column dataType image:

// Matching the below regex should result in default handing for the values as images
(/\.(gif|jpe?g|tiff?|png|webp|bmp)$/i).test(column.ProfilePicture);

<igx-column field="ProfilePicture">
</igx-column>

Story 3: As a developer, I want all column operations to be disabled for columns of dataType image, unless I explicitly provide custom strategies for handling each operation:

[Image column sorting/filtering disabled]

End-user stories:

Story 1: Аs an end-user I want to see images in grid cells when image urls are provided in the data source.

3. Functionality

3.1. End-User Experience

Number column

Initially, users see the number value display:

Initial state

Upon double-click on the cell, the users enter edit mode:

Edit

String column

Initially, users see the string value display:

Initial state

Upon double-click on the cell, the users enter edit mode:

Edit

Date column

Initially, users see the date value display:

Initial state

Upon double-click on the cell, the users enter edit mode:

Edit

Boolean column

Initially, users see a "clear" icon for false values and a "check" icon for true values:

Initial state

Upon double-click on the cell, the users enter edit mode with a checkbox:

Edit

Edit boolean type - a prototype

Dimensions

Note: Icons sizes according to display density (cosy, comfortable, compact) - remain the same.

Currency column

Initially, users see the currency value display:

Initial state

Upon double-click on the cell, the users enter edit mode:

Edit

Percent column

Initially, users see the percent value display:

Initial state

Upon double-click on the cell, the users enter edit mode:

Edit

Comfortable display density - default display density with the lowest intense and row height equal to 50px. Left and Right paddings are 24px; Minimal column width is 48px.

Comfortable

Cosy display density - the middle intense density with 40px row height. Left and Right paddings are 16px; Minimal column width is 32px.

Cosy

Compact display density - the density with highest intense and 32px row height. Left and Right paddings are 12px; Minimal column width is 24px.

Compact

Note: There is no change of the typeface when the display density is changed. Only the long string data can be shown with ellipses.

Image column

Initially, users see the currency value display:

[Image column Initial state]

3.2. Developer Experience

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

Keys	Description

3.5. API

Options

Name	Description	Type	Default value	Valid values

Methods

Name	Description	Return type	Parameters

Events

Name	Description	Cancelable	Parameters

4. Test Scenarios

Currency type test plan

Verify euro currency sign is present after grid.locale property is set to 'fr-FR'
Verify changing of the currency sign after using a different grid.locale - for example 'en-US' value.
Verify a proper set of pipeArgs, example:

public options = {
  digitsInfo: '3.4-4',
  currencyCode: 'USD',
  display: 'symbol-narrow'
};
public formatOptions = this.options;

<igx-column [pipeArgs]="formatOptions" [dataType]="'currency'">
</igx-column>

Verify that the summary rows have applied formatting based on locale and/or pipeArgs.
Verify that the Filtering UI list is populated with values that include the currency code based on locale and/or pipeArgs.
When a cell is put in edit mode - verify that the editing input group has its currency code displayed.
Verify that while editing the value is incremented/decremented with up/down arrow keys based on default step (1) or from digitsInfo - minFractionDigits.

Percent type test plan

Verify percent (%) symbol is present after column dataType is set to 'percent' value.
Verify that preview value is present on cell and row editing.
Verify a proper set of pipeArgs, example:

public options = {
  digitsInfo: '1.4-4',
};
public formatOptions = this.options;

<igx-column [pipeArgs]="formatOptions" [dataType]="'percent'">
</igx-column>

Verify that the summary rows have applied formatting based on pipeArgs.
Verify that the Filtering UI list is populated with values that include the percent symbol and formatting based on pipeArgs.
When a cell is put in edit mode - verify that the editing input group has its percent sign displayed.
Verify that while editing the value is incremented/decremented with up/down arrow keys based on default step (1) or from digitsInfo - minFractionDigits.
Verify that negative values have appropriate text color.

Image type test plan

Verify image templates are rendered when image regex is recognized without explicit data type.
Verify image templates are rendered with explicit data type.
Verify operations (sorting/filtering/grouping/summaries/editing) are off by default.

4.1. DateTime, Date and Time type test plan

Common tests

Verify a proper set of pipeArgs, example:

public options = {
  format: 'longTime',
  timezone: 'UTC'
};
public formatOptions = this.options;

// dateType could be 'dateTime', 'date' and 'time'
<igx-column [pipeArgs]="formatOptions" [dataType]="'dateTime'">
</igx-column>

Verify that the summary rows have applied formatting based on pipeArgs.
Verify that while editing the DateTime, Date, or Time value, it would be incremented/decremented with up/down arrow keys.
Verify that the value is submitted on enter press after updating it with arrow keys.
Verify editorOptions.dateTimeFormat is applied as input format for the default cell editor.
Verify pipeArgs.format is applied as input format for the default cell editor if numeric and editorOptions.dateTimeFormat is unset.
Verify the default locale format is applied as input format for the default cell editor when editorOptions/pipeArgs formats are unset.
Verify the editorOptions.dateTimeFormat/pipeArgs.format or a locale-based input format is applied for the filtering inputs (quick filter, ESF, advanced).

Filtering

[Exce-style filtering] Verify that the value input is not editable when any Unary operands are used.
[Exce-style filtering] Verify that the Filtering UI list is populated with values with a format based on the set pipeArgs.
[Quick filter] Verify that on open/close (toggle) and blur of the editor the value is not submitted for filtering (the chip should not be added).
Filter by all available conditions (IgxTimeFilteringOperand, IgxDateTimeFilteringOperand, IgxDateFilteringOperand) - Example with At, Not At, Before, After, At or Before, At or After, Empty, Not Empty, Null, Not Null

5. Accessibility

ARIA Support

When the grid is loaded and a cell of any type is selected the default aria support will be present - the elements are navigable and the values will be identified with ease by any narrator. For example, the number value will be read by its number and relevant Column header when a cell of type Currency is selected, the number value will be read with the corresponding currency sign and related column header, the same applies to the percent and date type columns.

Note: Boolean type column currently is not returning any readable value and only the column header is read.

Based on the column type when a cell is put in edit mode, the following components with editing capabilities will appear:

Number - Regular igxInput. 'Edit text numeric' and number value will be read.
DateTime - igxDateTimeEditor directive is used. 'Edit text' and the date value will be read.
Date - igxDatePicker is used when put in edit mode. 'Edit text' and the date value will be read. DatePicker ARIA spec.
Time - igxTimePicker is used when put in edit mode. 'Edit text' and the time value will be read.
Boolean - ARIA support only for the column header is present when the cell is selected. When the cell is put in edit mode 'Checkbox not checked/checked' will be read.
Currency - Edit text numeric and the numeric value will be read, without the currency sign.
Percent - Edit text numeric and the numeric value will be read, without pronouncing the percent sign.