Row Pinning

Row Pinning Specification

Revision History

1. Overview

Pinned Rows are visible all the time. Horizontal scrolling is applied to the rest of the columns.

Version	User	Date	Notes
0.1	Stamen Stoychev	February 19, 2020	API draft
0.2	Stamen Stoychev	February 20, 2020	Integration scenarios
0.3	Stefan Ivanov	March 2, 2020	Finalizing user stories and UI

Objectives

Allows a user to pin one or more rows to the top or bottom of the grid in a similar fashion to how Excel allows freezing the first few rows of a spreadsheet e.g. end-users can pin rows via the UI and developers can configure this through the API.

2. User Stories

As an end-user:

Story 1: I want to pin one or more rows to the top/bottom of the grid to make them visible all the time, even when scrolling.
Story 2: I want to have a clear and consistent-with-pinned-columns visual indication in order to differentiate pinned from unpinned rows.
Story 3: I want to have a vertical scrollbar only over the scrollable portion of the grid to be able to scroll the unpinned rows up and down.
Story 4: I want to select several rows and pin them all at once e.g. via a grid toolbar button.

As a developer:

Story 1: I want to programmatically pin/unpin rows by their identifier.
Story 2: I want to be able to template the row to allow users to pin/unpin rows.
Story 3: I want to have an out of the box experience for selecting rows and pinning them as a group via a preset toolbar button.

Acceptance criteria

Programmatically pin rows ...

3. Functionality

3.1. End-User Experience

Initially, two columns are pinned and no rows are pinned or selected. Grid with two pinned columns

The user selects one row intending to pin it. A button in the toolbar shows allowing this action. One row is selected

The user selects another row intending to pin it. The toolbar button content updates according to the new context. A second row is selected

The user pins the two rows via the grid toolbar button. The two rows remain selected after they become pinned and the button now lets the user unpin them. The two rows are pinned and still selected

3.2. Integration with other features

When there is filtering applied, if a row does not match the criteria specified it will not be shown in the pinned rows area.
When sorting is applied on a given column, it affects the pinned and the unpinned rows independently as if they are two separate collections of records.
The pinned rows order should come either according to the order of pinning or via manipulating it thought the API.
Row pinning is also agnostic of row templates including the use of multi-row layouts.
Row pinning should work with Group By taking the pinned record out of its group and placing it in the pin area.
It should be possible to drag pinned rows e.g. from a grid to a list in a similar fashion to how the drag directive normally works.
A grid with master-detail row behavior should also support pinning rows that upon expanding would expand the height of the pin area accordingly
The Tree Grid should allow pinning rows by creating a copy of the record (without expanding/collapsing icon) in the pin area and styling the original record within the hierarchy as a disabled ghost that supports only one type of interaction: expand/collapse see interactive prototype

Tree Grid with Row Pinning

The Hierarchical Grid should allow pinning rows by:

when the pinned record is expandable: creating a copy of the record (without expanding/collapsing icon) in the pin area of its parent grid and styling the original record within the hierarchy as a disabled ghost that supports only one type of interaction: expand/collapse
when the pinned record is not expandable i.e. it is a leaf record without grids belonging to it: moving the record to the pin area of its parent grid (as if it were a record of a flat grid) without leaving a ghost

Hierarchical Grid with Row Pinning

Top-pinned rows should appear below the headers (normal headers or row filter headers) and above the scrollable grid body. Grid with top-pinned rows

Bottom-pinned rows should appear below the scrollable grid body (and summary rows if there are column summaries defined) and above the bottom border of the grid (or paging UI if pagination is switched on). If the page size is set to e.g. 10 records and we have 2 pinned rows, then the page should be adjusted to show 8 records, if the user pins another row, the page size is adjusted in real-time to 3. Grid with bottom-pinned rows

The toolbar provides UI for pinning rows. The rows don't own specific UI to be pinned by default. Developers should supply their templates and UI for pinning and unpinning rows. Below is an example of templating the subject column. Grid with a template in the first column adding an icon to the left of the text

It's up to the developer to decide if the default UI for row pinning is enabled for end-users. Otherwise pinning will be exclusive to API calls. By default, rows are always pinned one after the other (the second pinned appears under the first pinned one) regardless of the pinning position.

3.3. Developer Experience

Nothing specific is required by the developer to allow row pinning. The grid exposes API that allows pinning/unpinning a row by its id that always works. Additionally, where the row is pinned is controlled with the pinning input with the following signature:

export interface IPinningConfig {
    columns?: ColumnPinningPosition;
    rows?: RowPinningPosition;
}

@Input()
pinning: IPinningConfig;

Where RowPinningPosition is an enumeration with two options - RowPinningPosition.Top (default) and RowPinningPosition.Bottom.

Rows are pinned and unpinned using the pinRow and unpinRow methods respectively, exposed in grid-base.directive therefore available for all grid variants. Similar to the column counterparts, the row directive has pin and unpin methods that are used under the hood, as well as pinned getter/setter for maximum flexibility to the user. Pin method accept an optional index parameter. Controlling the index using the other methods of pinning is done through the onRowPinning output insertAtIndex argument.

export interface IPinRowEventArgs extends IBaseEventArgs {
    row: IgxRowDirective<T>;
    insertAtIndex: number;
    isPinned: boolean;
}

@Output()
public onRowPinning = new EventEmitter<IPinRowEventArgs>();

Feature integration

Pinned rows are rendered outside of the igxForOf display container instead of using ngFor for the template structure. This requires that they are removed from the data view being passed through the pipes in certain cases and/or included in a pinned-only pipe collection. The following specifies where they are included and where they are not:

gridTransaction - runs separately on both collections
visibleColumns - runs on a combined collection
gridFiltering - runs separately on both collections
gridSort - runs separately on both collections (both pinned and unpinned columns should be sorted based on the expressions)
gridGroupBy - runs only on the unpinned rows collection (pinned rows should not show group by rows)
gridPaging - runs only on the unpinned collection with a modified pageSize - pageSize = pageSize - pinnedRows.length
gridSummary - global summaries run on the combined collection, group by ones run only on the unpinned rows collection
gridDetails - runs separately on both collections - pinned rows are expandable and this could lead to unusable grid state. It is up to developers to decide if they want row pinning and master-details views at once. The same is true for igxHierarchicalGrid.

Note: In igxTreeGrid pinning a row essentially pins its whole subtree. This could lead to an unusable grid state.

3.3. Globalization/Localization

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

3.4. User Interface

3.5. Navigation

3.6. API

Inputs

Name	Type	Default value	Valid values	Description
pinning	IPinningConfig	{ rows: RowPinningPosition.Top }	Top / Bottom	Controls the pinning direction as a configuration object for both rows and columns
? UI

Outputs

Name	Description	Type
onRowPinning	Emitted when a column is being pinned or unpinned	IPinRowEventArgs

Methods

Name	Parameters	Return type	Description
pinRow	rowID: any, index?: number	boolean	Pins the row specified by PK or ref, at the chosen index (optional) and returns if the operation succeeded
unpinRow	rowID: any, ~~index?: number~~	boolean	Unpins the row specified by PK or ref, ~~at the chosen index (optional)~~ and returns if the operation succeeded

Note: unpinRow should not allow defining a custom index to unpin as we do not want to allow the user to change the original order of the data and pollute it. Unpinned row should go in its original location in the data.

4. ARIA Support

Specify only if applicable

5. Assumptions and Limitations

Excel does not support frozen rows at the bottom. When RowPinningPosition.Bottom is used, all pinned rows will appear as frozen at the top in Excel.