igxGrid Column Data Types and Templates Specification

igxGrid Column Data Types and Templates Specification

Contents

1. Overview
2. User Stories

• Number data type
• String data type
• DateTime, Date and Time data type
• Boolean data type
• Currency data type
• Percent data type

3. Functionality
4. Test plans

• Currency type
• Percent type
• DateTime, Date and Time type

Owned by

Team Name - Team Leader Name

Requires approval from

• Peer Developer Name | Date:
• Stefan Ivanov | Date:

Signed off by

• Radoslav Mirchev | Date:
• Platform Architect Name | Date:

Revision History

Version	Users	Date	Notes
0.1	Yoanna Ivanova	Date	Initial Draft
1.0	Zdravko Kolev	02/03/2021	Currency data type column
1.1	Zdravko Kolev	02/10/2021	Percent data test plan
1.2	Zdravko Kolev	03/25/2021	Datetime data type column

1. Overview

Objectives

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.

Number column type

String column type

Date column type

Boolean column type

Currency column type

Acceptance criteria

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

...

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, currency, percent, 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 UI, 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>

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>

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 a 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>

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>

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 a 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 not confused with 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 a input editor that access both 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 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 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 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:

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:

Result with pipeArgs:

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). Image:

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. Image:

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

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':

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:

Result with pipeArgs:

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. Image:

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. Image:

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.

Upon double click on the cell, the users enter edit mode.

String column

Initially, users see the string value display.

Upon double click on the cell, the users enter edit mode.

Date column

Initially, users see the date value display.

Upon double click on the cell, the users enter edit mode.

Boolean column

Users see a "clear" icon for false values and a "check" icon for true values.

Upon double click on the cell, the users enter edit mode.

Edit boolean type - a prototype

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

• 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.

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

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

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

4. Test plans

Currency type test plan

1. Verify euro currency sign is present after grid.locale property is set to 'fr-FR'

2. Verify changing of the currency sign after using a different grid.locale - for example 'en-US' value.

3. 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>

4. Verify that the summary rows have applied formatting based on locale and/or pipeArgs.

5. Verify that the Filtering UI list is populated with values that include the currency code based on locale and/or pipeArgs.

6. When cell is put in edit mode - Verify that the editing input group has its currency code displayed.

7. Verify that while editing the value is incremented/decremented with up/down arrows keys based on default step (1) or from digitsInfo - minFractionDigits

Percent type test plan

1. Verify percent (%) symbol is present after column dataType is set to 'percent' value.

2. Verify that preview value is present on cell and row editing.

3. 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>

4. Verify that the summary rows have applied formatting based on pipeArgs.

5. Verify that the Filtering UI list is populated with values that include the percent symbol and formatting based on pipeArgs.

6. When cell is put in edit mode - Verify that the editing input group has its percent sign displayed.

7. Verify that while editing the value is incremented/decremented with up/down arrows keys based on default step (1) or from digitsInfo - minFractionDigits

8. Verify that negative values have appropriate text color.

DateTime, Date and Time type test plan

1. 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>

2. Verify that the summary rows have applied formatting based on pipeArgs.

3. Verify that the Filtering UI list is populated with values based on pipeArgs and the respective type column - DateTime, Date or Time.

4. Verify that while editing the DateTime, Date or Time value, it would be incremented/decremented with up/down arrows keys.