Column Actions

Column Actions Component 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	July 1, 2020	Initial draft
0.2	Stamen Stoychev	August 2, 2020	Finalizing spec

Objectives

Allow users to create a simple dropdown component containing a list of grid columns with checkboxes controlling one of their boolean properties.

2. User Stories

Developer:

Story 1: As a developer, I want to display a dropdown that contains columns and let the end-user hide them on check.
Story 2: As a developer, I want to display a dropdown that contains columns and let the end-user pin them on check.

End user:

Acceptance criteria

A generic component that ngFor-s a list of items (columns) with checkboxes.
A filter field on top of the list that hides items that don't meet the criteria the end user typed in
Check all/uncheck all buttons at the bottom.
Two predefined directives that provide the specific onCheck/Check All/Uncheck All and the list of columns to display.

3. Functionality

3.1. End User Experience

3.2. Developer Experience

Developers that need to display the igxColumnActions component may do it with the following template:

<igx-column-actions IgxColumnActionsBase></igx-column-actions>

Here the IgxColumnActionsBase represents one of its derivative directives - IgxColumnPinning, IgxColumnHiding or a custom one. The directives inject the component and assign their instance to the public property actionsDirective so that they may be accessed through an interface determined by the IgxColumnActionsBase by the IgxColumnActions component.

The directives expose functions/properties that determine:

Which columns have the specified action allowed
What should check and uncheck do
What should check all/uncheck all do
The button strings
Some specifics such as pinning showing only top level columns in multi-column header scenario

Users should be able to implement an IgxColumnActionsBase derivative that controls other column properties (selection, groupby, etc) by simply implementing all abstract methods inherited.

Migration from igxColumnHidingComponent and igxColumnPinningComponent to igxColumnActionsComponent

If users need to migrate from the old components to the new one, they have to be aware of the following API name changes and some breaking ones.

Current Name	Future Name
`disableShowAll`	`uncheckAllDisabled`
`disableHideAll`	`checkAllDisabled`
`disableFilter`	`hideFilter`
`showAllText`	`uncheckAllText`
`hideAllText`	`checkAllText`
`showAllColumns`	`uncheckAllColumns`
`hideAllColumns`	`checkAllColumns`

Breaking changes

columnItems - from the list of checked columns to a list of shown columns
onColumnVisibilityChanged event - removed

3.3. Globalization/Localization

igxGrid exposes a few inputs that specify texts for each of the two predefined column action implementations (Hiding, Pinning) . These are currently not localized as they default to empty strings.

Input	Description	Default
hiddenColumnsText	Text to append at the end of the Toolbar Hiding button	empty
pinnedColumnsText	Text to append at the end of the Toolbar Pinning button	empty
columnHidingTitle	Text to apply as the title input for the hiding actions component	empty
columnPinningTitle	Text to apply as the title input for the pinning actions component	empty

igxGridToolbar exposes an additional input affecting the defaults of the column actions components. This defaults to a localizable string.

Input	Description	Default
filterColumnsPrompt	Text to show as the filter input prompt	igx_grid_toolbar_actions_filter_prompt

Finally the two buttons in the column actions has localized labels that are populated by the directives.

IgxColumnHidingDirective

Input	Description	Default
uncheckAllLabel	Label of the uncheck all button for hiding	igx_grid_hiding_uncheck_all_label
checkAllLabel	Label of the check all button for hiding	igx_grid_hiding_check_all_label

IgxColumnPinningDirective

Input	Description	Default
uncheckAllLabel	Label of the uncheck all button for pinning	igx_grid_pinning_uncheck_all_label
checkAllLabel	Label of the check all button for pinning	igx_grid_pinning_check_all_label

3.4. User Interface

The component has the following UI:

Note: The button is part of the default igxTooolbar component template

It includes:

Title - may be hidden
An input used to filter the column list
The column list with checkbox the state of which indicates the state of the column related to the action
Check all/Uncheck all buttons with labels corresponding to the action

Note: Columns that have the associated action disabled do not appear in the list.

3.5. Navigation

Navigation is achieved by TAB and SHIFT + TAB. The tab sequence is:

Filter field
Each of the checkboxes representing columns
The check all button
The uncheck all button

Toggle is achieved with ENTER.

3.6. API

Inputs

IgxColumnActionsComponent

Name	Description	Type	Default value
columns	A list of grid columns to provide an action for	`Array<IgxColumnComponent>`	`[]`
title	The title of the column actions component	`string`	`''`
filterColumnsPrompt	The prompt that is displayed in the filter input	`string`	`''`
hideFilter	Shows/hides the filter input	`bool`	`false`
filterCriteria	The criteria to filter the column list by	`string`	`''`
columnDisplayOrder	The display order of the columns in the list	`ColumnDisplayOrder`*	`DisplayOrder`
columnsAreaMaxHeight	The max height of the columns area	`string`	`'100%'`
uncheckAllText	The text of the button that unchecks all columns	`string`	`'Uncheck All'`
checkAllText	The text of the button that checks all columns	`string`	`'Check All'`
indentation	The indentation of columns in the column list based on their hierarchy level	`number`	`30`

Note: Where ColumnDisplayOrder is an enumeration with two possible values - Alphabetical and DisplayOrder.

Properties

IgxColumnActionsComponent

Name Description Type Get/Set?

columnItems A list of grid columns present in the dropdown as an array of checkboxes Array<IgxCheckboxComponent> get

Methods

IgxGridComponent

Name	Description	Return type	Parameters
uncheckAllColumns	Unchecks all columns and performs the associated action	`undefined`
checkAllColumns	Checks all columns and performs the associated action	`undefined`

Outputs

N/A

4. ARIA Support

Filter Input element has:

aria-describedBy, which points to the column actions title element.

When used inside the grid toolbar for hiding/pinning then the columnHidingTitle/columnPinningTitle need to be set on the grid for the title elements to have content. If the column actions component is used independently, then its title property should be set.

Checkboxes have: