Sorting Specification

Sorting Specification

Contents

1. Overview
2. User Stories
3. Functionality
4. Test Scenarios
5. Accessibility
6. Assumptions and Limitations
7. References

Owned by

Phoenix

Developer Name

Stefan Ivanov

Requires approval from

• Peer Developer Name | Date:
• Stefan Ivanov | Date: 24 Jul 2020

Signed off by

• Radoslav Mirchev | Date:
• Radoslav Karatoaivanov | Date:

Revision history

Version	User	Date	Notes
0.1	Stefan Ivanov	28.11.18	Created Spec
0.2	Danail Marinov	16.01.19	Updated Spec
0.3	Danail Marinov	17.01.19	Updated Spec
2	Stefan Ivanov	15.07.20	Adding sort order indication
2.1	Hristo Anastasov	19.10.2021	Adding sortingOptions input property
2.2	Hristo Anastasov	22.03.2022	Decoupling sorting from grouping

1. Overview

Objectives

The sorting functionality of the grid allows the user to define the order of records in the grid by sorting a column in ascending/descending order via a sort icon in the grid header. It is also possible to sort the grid by more than one column, where a numeric indication on the icon is used to show the order in which columns have been sorted prototype

Acceptance criteria

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

...

2. User Stories

Developer Stories

• Story 1: As a developer, I want to be able to mark columns as sortable/not sortable, so that I have control over the columns that end-users may sort.
• Story 2: As a developer, I want to be able to sort columns in ascending/descending order programmatically so that I can define an initial state of the grid.
• Story 3: As a developer, I want to have ellipsis applied out of the box on the column name label when the column is too narrow and becomes sorted so that the sort icon is clearly visible.
• Story 4: As a developer, I want to be able to easily choose between single and multiple sorting modes by using an input property. If I want to be able to further customise any options for sorting, i.e. choose between Three-state or Two-state sorting, I want to be able to use the same input property.
• Story 5: As a developer, I want to be able to set sorting and grouping expressions separately, without the one affecting the other. If grouping/sorting expressions are in a conflict, grouping expressions should take precedence. Example: Column 'OrderDate' is grouped and in the grouping expressions the sort direction is 'ASC'. Trying to programatically sort the 'OrderDate' column in direction 'DESC' will apply a descending sorting indicator, but the column will be actually sorted by 'ASC'.
• Story 6: As a developer, I want to be able to disregard the sorting MODE option, by working directly with the API. Example: If sorting mode is single, I still want to be able to apply multiple sorting via API.

End-user stories

• Story 1: As an end-user, I want to know on which columns I can apply sorting so that I can distinguish them from the rest.
• Story 2: As an end-user, I want to know which columns are currently sorted/unsorted so that I can have a clear understanding of the current state of the grid.
• Story 3: As an end-user, I want to be able to distinguish whether ascending or descending order of the sorting is applied so that I have a clear understanding at a glance of the order in a particular column.
• Story 4: As an end-user, I want to know the sequence in which columns have been sorted, when sorting spans more than one column so that I can have a clear understanding of the current state of the grid. Edit: sorting sequence will not be displayed while in single sorting mode.
• Story 5: As an end user, I want to be able to group and sort columns separately, without having the one action affect the other. Examples:
  • Column A is grouped. I am no longer able to sort column A though the UI. Column A will be missing the sorting indicator in its header.
  • Column A is grouped. I sort Column B by UI. If sorting sequence is displayed, Column B is the 1st sorted column
  • Column A is grouped. Clearing the sorting expressions does not clear the grouping and Column A is still grouped.
  • Sorting mode is single. I still want to be able to group by multiple columns.

3. Functionality

3.1. End-User Experience

Unfiltered headers display an up arrow (indicating that the column is sortable) at grays,600 and when filtering is applied the arrow is colorized with secondary,500 and its direction indicates the current sort order i.e. pointing up for ascending and down for descending sort order.

Filtering row is inactive, sorting is idle.

On inactive filter row, the up/down arrow is at grayс,600

Filtering row is inactive, sorting is applied.

On inactive filter row, on applied sorting the up/down arrow is at secondary,500

Filtering row is active, sorting is idle.

On active filter row, the up/down arrow is at grayс,600

Filtering row is active, sorting is applied.

On active filter row, on applied sorting the up/down arrow is at secondary,500

If the width of the column is not enough to display the full column label and the sorting arrow, then:

If Excel Style Filtering is also enabled for a sortable column, triggering the sorting from the ESF dialog will cause the sorting icon to reflect that and the indicator to show the sequence number accordingly prototype

The display density does not affect the sorting indication, it respects the paddings defined otherwise in the header cell for the icons that appear.

In rare cases when a grid has many columns and sorting is applied on an arbitrary number of them, the indicator may need to be a two-digit number. Then, the background color of the numeral will result in part of the icon being cut off like below.

When sorting mode is Single, indicator will not be displayed.

The following handoff defines the relationship and styling characteristics of the sorting indicator with respect to the sort icon and the grid header cell.

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

Name	Description
Ctrl + Arrow up	sorts the column in ASC order (if already sorted in ASC order it unsorts the column)
Ctrl + Arrow down	sorts the column in DSC order (if already sorted in ASC order it unsorts the column)

3.5. API

Options

Name	Description	Type	Default value	Valid values
sortingOptions	An object providing a Mode property to enable choosing between single or multiple column sorting.	ISortingOptions	Mode: Multi	Mode: Single/Multi (will be enum)

<igx-grid [sortingOptions]="sortingOptions"....>

export class AppComponent {
    public sortingOptions: ISortingOptions;
    this.sortingOptions = { Mode: SortingMode.Single }
}

Methods

Name	Description	Return type	Parameters

Events

Name	Description	Cancelable	Parameters

4. Test Scenarios

Automation

• Scenario 1:
• scenario 2:

5. Accessibility

ARIA Support

RTL Support

6. Assumptions and Limitations

Assumptions	Limitation Notes

7. References

Specify all referenced external sources