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

Objectives

Allow the developer the programatically pin one or more columns to the left or right of the grid.

2. User Stories

Elaborate more on the multi-facetted use cases

Developer:

Story 1: As a citizen developer, I want…, so that I can…
Story 2: As a citizen developer, I want…, so that I can…
Story 3: As a citizen developer, I want…, so that I can…

End user:

Story 1: As an end user, I want to have a column/row pinned, so that I can see them all the time.
Story 2: As an end user, I want have columns/rows pinned to the start/end or top/bottom, so that I can position them according to my task.
Story 3: As an end user, I want…, so that I can…
Story 4: As an end user, I want…, so that I can…

Acceptance criteria

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

Programatically pin columns to the left or to the right. Adding a more than one pinned columns positions them to the left of right of the already fixed column.
Have pinned Columns always on top while horizontal scrolling is applied.
Provide API for custom UI.
Set max width of the total pinned columns as a property of the viewport of the grid.%
Set width of the total pinned columns (auto). ...

3. Functionality

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

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 are not able to pin columns through the UI of the grid. Developers should supply their own UI for pinning and unpinning.

3.2. Developer Experience

Developers are able to programatically 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 at the end of the scroll container is as easy as:

import { PinLocation } from "igniteui-angular/core/utils";
...
const col = this.grid.getColumnByName(name);
col.pin(PinLocation.End);

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;
    }
}

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

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

Options

IgxGridColumnComponent

Name	Description	Type	Default value	Valid values
pinned	Whether the column is pinned or not	bool	false	true\|false
pinLocation	The column may be pinned either from the start or at the end of the scrolling area	`PinLocation`	Start	Start\|End
~~pinnable~~	~~Specifies if the column can be pinned by the end-user from the UI~~	~~bool~~	~~false~~	~~true\|false~~

Note: PinLocation is an enum that is loaded from /core/utils

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
pinnedStartColumns	(Get) The collection of visible columns pinned at the start.	`Array<IgxColumnComponent>`
pinnedEndColumns	(Get) The collection of visible columns pinned at the end.	`Array<IgxColumnComponent>`
unpinnedColumns	(Get) The collection of unpinned columns.	`Array<IgxColumnComponent>`
startPinnedWidth	(Get) The total width of all columns pinned at the start.	number
endPinnedWidth	(Get) The total width of all columns pinned at the end.	number
unpinnedWidth	(Get) The total width of all unpinned columns.	number

IgxGridRowComponent

Name	Description	Type
pinnedStartColumns	(Get) The collection of columns pinned at the start.	`Array<IgxColumnComponent>`
pinnedEndColumns	(Get) The collection of columns pinned at the end.	`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`, location?: `PinLocation`
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	location: `PinLocation` - the location for pinning
unpin	Unpin this column	`bool` - whether the unpin is successful or not

Pinning a column will not succeed if:

The new width of the pinned areas exceed the width of the grid
The new width of the pinned areas when all pinned columns are unhidden will exceed the width of the grid
The grid does not meet the requirements for pinning to be enabled as specified in the Assumptions and Limitations section
The column is already pinned on that location (or the default one)

Unpinning a column will not succeed if:

The column is already unpinned

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
A grid with pinned columns will always have a minimal width that allows it to display its scroll container