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
Platform Architect Name | Date:

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

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

Objectives

Providing a default handling of number, string, date, boolean, currency, and percent 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 value with keyboard 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.
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.

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 or based on 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' }]
})

Set Grid's locale

<igx-column locale="'fr-FR'"
    [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 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.

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 set app LOCALE_ID or grid.locale:

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.

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.

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.

4.1. DateTime, Date and Time type test plan

Verify a proper set of pipeArgs, example:

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

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

Verify that the summary rows have applied formatting based on pipeArgs.
Verify that the Filtering UI list is populated with values based on pipeArgs and the respective type column - DateTime, Date, or Time.
Verify that while editing the DateTime, Date, or Time value, it would be incremented/decremented with up/down arrow keys.

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.