Skip to content

Column Actions

Stamen Stoychev edited this page Aug 2, 2020 · 8 revisions

Column Actions Component Specification

Contents

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

Revision History

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.

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

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

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:

  1. Title - may be hidden
  2. An input used to filter the column list
  3. The column list with checkbox the state of which indicates the state of the column related to the action
  4. 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

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

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

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

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:

  • aria-checked if checked.
  • aria-labelledby, which point to the label holding the header text or field name of the related column.
Assumptions Limitation Notes

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

Clone this wiki locally