Column Pinning

Column Pinning Specification

Revision History

1. Overview

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

Version	User	Date	Notes
0.1	Stamen Stoychev	March 6, 2018	API draft
0.2	Stamen Stoychev	March 7, 2018	API changes, developer experience notes
0.3	Stanka Bozalieva	March 8, 2018	Screenshots, stories updates
0.4	Stamen Stoychev	March 12, 2018	Removing right pinning, stories fixes
0.5	Stamen Stoychev	October 25, 2019	Removing pinning limitations
0.6	Petko Bozhinov	February 17, 2020	Adds information about IPinningConfig
0.7	Deyan Kamburov	February 19, 2020	Add right pinning and update spec

Objectives

Allow the developer the programmatically pin one or more columns to one of the sides(left or right) of the grid.

2. User Stories

Developer:

Story 1: As a developer, I want to programmatically pin/unpin a column, so that I can provide pinned columns for the user.
Story 2: As a developer, I want to have a sufficient API, so that I can provide a custom UI for the end-user.
Story 3: As a developer, I expect out of the box UI in the toolbar dropdown for column pinning to pin/unpin all columns at once.

End user:

Story 1: As an end user, I want to have one or more columns pinned, so that I can see them all the time.
Story 2: As an end user, I want to visually identify pinned columns, so that I can differentiate them from the rest of the grid.
Story 3: As an end user, I want to have the horizontal scroll next to the pinned columns area, so that I can scroll the corresponding area.
Story 4: As an end user, I want a browser scroll to be applied to the entire grid if the view-port is below the min width of the grid, so that I can see the pinned columns pinned.
Story 5: As an end user, I want a pager to be applied to the entire grid, so that I can see the pinned columns pinned.
Story 6: As an end-user, I want summaries for pinned columns to be styled as part of the pinned column, so that I can see them as such.
Story 7: As an end-user, I want summaries/column headers and all appropriate for pinned columns to be styled as part of the pinned column so that I can see them as such.
Story 8: As an end-user, I don't want to pin a column a part a multi-column group, so that I can see them as part of a group. I want to pin the entire group.
Story 9: As an end-user, I want to be able to filter pinned columns, so that I can interact with them as the rest of the columns.
Story 10: As an end-user, I want to be able to see all the pinned columns within the grid view-port and at the same time see the horizontal scroll, so that I can horizontally scroll the rest of the unpinned columns.
Story 11: As an end-user, I want to pin all columns but two, so I need a pin all button that would "check" all dropdown items and let me uncheck the two I want to leave unpinned.
Story 12: As an end-user, I want to unpin all the currently pinned columns so that my grid content is fully scrollable.

TO CONSIDER

Story 13: As an end user, I want to be able to resizing/move/groupby/hide/exportable pinned columns, so that I can interact with them as the rest of the columns.? or we can lock them?

Acceptance criteria

Programmatically pin columns to the left. Adding more than one pinned columns positions them to the right of the already fixed column.
Have pinned Columns always on top while horizontal scrolling is applied.
Provide API for custom UI.
Set width of the total pinned columns (auto).

3. Functionality

3.1. End User Experience

End users are able to pin and therefore leave columns always visible while scrolling the grid horizontally achieving greater usability of the control. All features that are available for unpinned columns are available for pinned columns as well.

End users should be able to see at unpinned columns as at least 20% of the entire grid width, so that they are able to see the horizontal scroll. But the pinning feature won't refuse to pin a column even if the unpinned area becomes too small or invisible.

The toolbar provides UI for pinning columns. The columns don't own specific UI to be pinned. Developers should supply their own UI for pinning and unpinning.

Pin/Unpin All Prototype

3.2. Developer Experience

Developers are able to programmatically pin or unpin columns as long as the API requirements are met and none of the limitations apply to the application scenario.

Pinning a column is as easy as:

const col = this.grid.getColumnByName(name);
col.pin();

Developers can also subscribe to an event emitted before pinning completes to modify the order of the pinned columns. For example if column "Name" should always be pinned first:

<igx-grid #grid [data]="localData" [autoGenerate]="true" (onColumnPinning)="columnPinning($event)"></igx-grid>

public columnPinning(event) {
    if (event.column.field === "Name") {
        event.insertAtIndex = 0;
    }
}

Change the pinning configuration to pin columns to the end:

<igx-grid [pinning]="pinningConfig">
</igx-grid>

public pinningConfig: IPinningConfig = { columns: ColumnPinningPosition.End };

3.3. Globalization/Localization

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

3.4. User Interface

screenshot-2018-3-7 the best fastest angular data grid in the world

3.5. Navigation

Pinning columns modifies their order and in turn requires that navigation takes that into account. A new calculated property visibleIndex is introduced for the IgxGridColumnComponent that returns the index of the column in the context of the combined collection of pinned and unpinned ones. All navigation routines should use that to determine the next item to the left or right of the current one.

3.6. API

3.7. Initial pinning configuration

The initial pinning configuration uses the IPinningConfig interface. That interface allows the developer to choose a predefined pinning configuration, thanks to its properties, which are the following:

rows (either Top or Bottom)
columns (either Left or Right)

Note: The pinning doesn't allow to apply a column pinning to the both opposite sides at a time, i.e. no left and right column pinning can occur at a time, as well as no top and bottom row pinning are allowed simultaneously.

Options

IgxGridColumnComponent

Name	Description	Type	Default value	Valid values
pinned	Whether the column is pinned or not	bool	false	true\|false
~~pinnable~~	~~Specifies if the column can be pinned by the end-user from the UI~~	~~bool~~	~~false~~	~~true\|false~~

Note: pinnable should be used to enable UI for the feature. Without UI it should be skipped. Columns will always be pinnable from the API but it may disallow pinning based on grid configuration or other criteria.

Properties

IgxGridComponent

Name	Description	Type
pinnedColumns	(Get) The collection of visible pinned columns.	`Array<IgxColumnComponent>`
unpinnedColumns	(Get) The collection of unpinned columns.	`Array<IgxColumnComponent>`
pinnedWidth	(Get) The total width of all pinned columns.	number
unpinnedWidth	(Get) The total width of all unpinned columns.	number
pinning	The pinning configuration specifying where to pin columns and rows	IPinningConfig

IgxGridRowComponent

Name	Description	Type
pinnedColumns	(Get) The collection of visible pinned columns.	`Array<IgxColumnComponent>`
unpinnedColumns	(Get) The collection of unpinned columns.	`Array<IgxColumnComponent>`

IgxGridColumnComponent

Name Description Type

visibleIndex (Get) The visible index of the column including all pinned or unpinned columns before its position. number

Methods

IgxGridComponent

Name	Description	Return type	Parameters
pinColumn	Pin the specified column	`bool` - whether the pin is successful or not	columnName: `string`
unpinColumn	Unpin the specified column	`bool` - whether the unpin is successful or not	columnName: `string`

IgxGridColumnComponent

Name Description Return type Parameters

pin Pin this column bool - whether the pin is successful or not

unpin Unpin this column bool - whether the unpin is successful or not

Pinning and unpinning will be unsuccessful if the columns is already in the desired state.

Note - pin|unpin use the pinColumn|unpinColumn igxGridComponent methods internally

Events

Name	Description	Cancelable	Parameters
onColumnPinning	Emitted when pinning is requested, before the execution completes. Users may edit the arguments.insertAtIndex property to change the position of the column in the pinned area.		column: `IgxGridColumnComponent`, insertAtIndex: `number`

4. ARIA Support

Specify only if applicable

5. Assumptions and Limitations

Assumptions	Limitation Notes
Column Pinning is only available in grids with horizontal scrollbars	Pinning only makes sense when the grid can be scrolled horizontally

6. References

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

Test Plan Overview

Grid with different sizes and different column sizes (%, px, null)
Grid Feature Integration Scenarios
- Resizing
- Moving
- Grouping
- Search
- Summaries
- Hiding
- Filtering – Test with UI elements rendered in the header ( like Filter row).
- Multi-column headers
- Multi-row layout
- Master-Detail
- Selection (cell selection, row selection, multi-cell selection)
- Keyboard navigation