Column Pinning

Column Pinning Specification

Contents

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

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

Objectives

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

2. User Stories

Developer:

• Story 1: As a citizen developer, I want to programatically pin/unpin a column, so that I can provide pinned columns for the user.
• Story 2: As a citizen developer, I want have a sufficient API, so that I can provide a custom UI for the end user.

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 viewport 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 pin a column a part a multicolumn 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.

TO CONSIDER

• Story 10: 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

1. Programatically pin columns to the left. Adding more than one pinned columns positions them to the right of the already fixed column.
2. Have pinned Columns always on top while horizontal scrolling is applied.
3. Provide API for custom UI.
4. Set max width of the total pinned columns as a property of the viewport of the grid.%
5. 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 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 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;
    }
}

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

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

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

2. IgxGridRowComponent

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

3. IgxGridColumnComponent

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

Methods

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

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

6. References

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