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

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

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

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

3.1. End User Experience

3.2. Developer Experience

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

Options

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

1. IgxGridComponent

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

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

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
   unpinColumn	Unpin the specified column	bool - whether the unpin is successful or not

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