Row Pinning

Row Pinning Specification

Contents

1. Overview
2. User Stories
3. Functionality
4. ARIA support
5. Assumptions and Limitations
6. References

Revision History

1. Overview

Pinned Rows are visible all the time. Vertical scrolling is applied to the rest of the rows.

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
0.4	Stamen Stoychev	April 3, 2020	Ghost rows finalization
0.5	Stefan Ivanov	April 6, 2020	Updating design with action strip
0.6	Stamen Stoychev	April 7, 2020	Updating Paging integration and chip

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 a row to the top/bottom of the grid to make it visible all the time, even when scrolling.
• Story 2: I want to unpin a row to remove it from the area at the top/bottom of the grid, which will enable the record in the scrollable grid body.
• Story 3: I want to have a clear and consistent-with-pinned-columns visual indication in order to differentiate pinned from unpinned rows.
• Story 4: I want to select several rows and pin them all at once - application scenario achievable via row selection and a grid toolbar button.

As a developer:

• Story 1: I want to programmatically pin/unpin rows by their identifier.
• Story 2: I want to have an out of the box experience for pinning rows via an action strip with predefined row pinning action.

Acceptance criteria

1. Programmatically pin rows ...

3. Functionality

3.1. End-User Experience

Initially, no columns or rows are pinned and when the user hovers over any row, it shows and action strip for the row and lets the user click on the pin action.

Once a row is pinned in a similar fashion it is possible to unpin rows via an action strip shown upon hovering over the rows in the pinned area. It is also possible to jump to the original ghost row in the scrollable area of the grid. When we have top pinning we should use "vertical_align_bottom" like is shown on the image below and when we have bottom pinning we should use "vertical_align_top".

Grids pin records in a special pin area at the top or bottom of the table body. The pin area cannot be scrolled and remains visible regardless of the scroll position of the main table body.

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

Bottom-pinned rows should appear below the scrollable grid body and above the summary rows / pager.

Pinned records are interactive but leave a disabled copy of themselves in the main body area that receives editing updates and selection styles (when its pinned counterpart is interacted with) but are otherwise non-interactive to the end-user with the exception of being expandable/collapsible in the case of a grid view supporting hierarchy (igxHierarchicalGrid, igxTreeGrid, igxGrid with Master-detail visualization). Pinned records do not display expand/collapse icons.

• igxTreeGrid

• igxHierarchicalGrid

Pinned rows display contextual UI allowing end-users to find the pinned row's disabled copy in the main table body area.

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.

• Grouping is not applied on the pinned records collection, however, the pinned records ghost rows remain in their appropriate groups.

• Paging ignores pinned rows. If the pageSize is e.g. 5 and there are 2 pinned records the total amount of records visible to the user for that page would be 7, the pager shows a page size of 5 and the total amount of pages is the same as though there were no pinned records (as the records are still displayed as disabled copies in the paged content).

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

• Exporting to MS Excel ignores pinning and exports the grid as if no rows are pinned

An action strip provides the default UI for pinning rows because they don't own specific UI to be pinned by default. 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 igxFor's display container and instead use ngFor as a structural directive. The collection passed to ngFor contains actual record references, while the igxFor collection includes special objects that refer to those records but can be recognized as copies for templating and functionality purposes. Not all pipes run for the pinned records collection. The list below details the exact behavior for affected features.

1. gridTransaction - runs separately on both collections
2. visibleColumns - runs on a combined collection
3. gridFiltering - runs separately on both collections
4. gridSort - runs separately on both collections (both pinned and unpinned columns should be sorted based on the expressions)
5. gridGroupBy - runs only on the unpinned rows collection (pinned rows should not show group by rows)
6. gridPaging - runs only on the unpinned collection
7. gridSummary - global summaries run on the original data, group by ones run on the group again with the original collection
8. gridDetails - runs only on the unpinned collection. Master rows that are pinned leave ghost copies which can be expanded/collapsed.

Ghost row specific integration and remarks

The ghost row is a disabled copy of a pinned one that appears in its original place in the scrollable area of the grid. It may be expanded if it is part of a hierarchical structure but cannot be directly edited or selected. It is decorated with disabled style and a specific template is inserted in its first data cell, regardless of whether it has user-specified template or not (similar to how expanders are added for the expand/collapse tree cells). By default this template contains a chip with the text "Pinned". The template is available for user override through the IgxPinnedIndicatorTemplateDirective.

<ng-template igxPinnedIndicatorTemplate>
    <igx-icon role="icon" fontSet="material">lock</igx-icon>
</ng-template>

As the pinned record is rendered once in the pinned area with no expander, and once in the unpinned area as a disabled row, there are specific integrations scenarios associated with the duplication of the row:

• Updating (with transactions)
  • The disabled copy row is not editable. Only the pinned row can enter edit mode.
  • Any changes applied via the pinned row should also be reflected to its copy placeholder in the unpinned area (when edited, deleted etc.).
  • Added rows should allow pinning and should also create a copy.
• Row Selection
  • The pin copy is not selectable via the UI. Its checkbox is disabled.
  • When the actual pinned row is selected, then the copy placeholder row is also marked as selected.
  • When all rows are selected via the UI all rows in the pinned and unpinned area are marked as selected (including the disabled rows.)
• Cell Selection
  • Cells in the disabled copy row are selectable and can be selected via keyboard/drag select etc.
  • Cells for both the pinned row and its disabled counterpart participate in the result of the getSelectedData method.
• Filtering
  • Both pinned and unpinned rows are filtered based on the condition. The disabled copy rows are displayed in the filtering result if they match the filtering criteria.
• Search
  • Search should mark results from both the pinned and unpinned area as separate results and should allow navigating between them (with findNext/findPrev API).

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.

6. References

Specify all referenced external sources, incl. competitors’ links. Remove before publishing outside Infragistics