Grid Toolbar Specification

Grid Toolbar Specification

Owned by

CodeX - Diyan Dimitrov

Requires approval from

Diyan Dimitrov | Date:
Stefan Ivanov | Date: 16 Sep 2020

Signed off by

Radoslav Mirchev | Date: 07 Oct 2020
Damyan Petev | Date:

Version	User	Date	Notes
0.1	-	-	Initial Draft
0.2	Danail Marinov	Jun 12, 2019	User Interface Update
0.3	Danail Marinov	Jun 13, 2019	Update Dev stories and Display Density
2.0	Stefan Ivanov	Jul 6, 2020	Adding improved stories and UI for exporting & updating spec template
3.0	Radoslav Karaivanov	Sept 16, 2020	Toolbar refactoring
3.1	Zdravko Kolev	July 24, 2021	Expose overlaySettings per action

Overview

The toolbar provides a container component located at the top of the Grid and containing default grid related interactions (such as hiding, pinning, etc). It also provides the ability to template additional UI/interactions through content projection.

Objectives

Provide a way for users to centralize grid related UI and interactions.

Acceptance criteria

Fast and easy way to initialize a default toolbar in the grid.

<igx-grid>
    <igx-grid-toolbar></igx-grid-toolbar>
</igx-grid>

Ability to template each area of the toolbar component

Title

<igx-grid>
    <igx-grid-toolbar>
        <igx-grid-toolbar-title>
            ...
        </igx-grid-toolbar-title>
    </igx-grid-toolbar>
</igx-grid>

Toolbar actions

<igx-grid>
    <igx-grid-toolbar>
        <igx-grid-toolbar-actions>
            ...
        </igx-grid-toolbar-actions>
    </igx-grid-toolbar>
</igx-grid>

Custom content provided by the user

<igx-grid>
    <igx-grid-toolbar>
        ...
    </igx-grid-toolbar>
</igx-grid>

Ability to template the default grid interactions

    <igx-grid-toolbar-exporter>
        <excel-text>Text for the excel exporter entry</excel-text>
    </igx-grid-toolbar-exporter>

Ability to reorder the zones of the toolbar (additional support for RTL)
The toolbar is static in relation to the virtualized grid body. That is if a horizontal scroll is present, it won't scroll the toolbar itself.
Ability to change the overlay setting for each action (hiding | pinning | advanced filtering | exporter)

<igx-grid-toolbar-actions>
    <igx-grid-toolbar-pinning [overlaySettings]="overlaySettingsGlobal"></igx-grid-toolbar-pinning>
    <igx-grid-toolbar-hiding [overlaySettings]="overlaySettingsAuto"></igx-grid-toolbar-hiding>
    <igx-grid-toolbar-advanced-filtering [overlaySettings]="overlaySettingsGlobal"></igx-grid-toolbar-advanced-filtering>
    <igx-grid-toolbar-exporter [overlaySettings]="overlaySettingsElastic" [exportCSV]="csv" [exportExcel]="excel">
    </igx-grid-toolbar-exporter>
</igx-grid-toolbar-actions>

public positionStrategyGlobal = new GlobalPositionStrategy({
    openAnimation: scaleInCenter,
    closeAnimation: scaleOutCenter
});
public overlaySettingsGlobal = {
    positionStrategy: this.positionStrategyGlobal,
    scrollStrategy: new AbsoluteScrollStrategy(),
    modal: true,
    closeOnEscape: true
};

Developer Stories

As a developer, I want the toolbar not to be scrollable even when the grid has horizontal scrollbars so that all functionalities it contains are always visible.

As a developer, I want to have a default template with right-aligned buttons according to the features enabled on the grid (column hiding, advanced filtering, exporting to excel, exporting to CSV...) so that if I instantiate a toolbar it is not showing empty.
As a developer, I want to be able to specify a title that will be left-aligned, so that I can use it for naming the grid e.g. "Produce Orders".
As a developer, I want to be able to access all textual content of the toolbar's controls(buttons) and be able to change(localize) them, so that I can support multiple languages.
As a developer, I want to have a threshold with which to delay any visuals and animations for operations expected to take a while, so that if finish almost instantaneously there are no observable, visual glitches.

End-user stories

As an end-user, I want to interact with the UI in the toolbar area and trigger the associated grid features, so that I can display the grid in the way I need.
As an end-user, I want to be able to interact with the grid even if some actions triggered by the toolbar are taking longer than others e.g. exporting a large set of data so that I am not stuck waiting for them to complete.
As an end-user, I want to have a clear visual indication if actions are not instantaneous e.g. exporting a large grid should show an indeterminate progress bar for as long as the exporting is running, so that I know something is in progress and can note once it is finished

Functionality

The toolbar should:

provide a way to set/customize a title
provide a default collection of widgets mapping to common grid interactions/features (hiding/pinning/exporting, etc.)
provide a way to customize (replace/customize) the default widgets for grid interactions
provide a way to inform the end-user that an action is taking place in the grid, through a visual cue

End-user experience

The toolbar height is adjusted to fit the content whether it is default or custom defined one. The UI components nested in the toolbar should inherit the Grid's Display Density. The toolbar has a minimum height defined by the content it contains by default, which can be seen below:

The toolbar width always matches the width of the grid and when the grid is narrower or wider the toolbar UI behaves in a responsive way to fit the available space e.g. prototype. The title has a maximum width of 40 characters defined and when that is not sufficient for the title it is cut with an ellipsis. When the width available for the actions becomes less than the combined width for them, their padding and margins, the actions appear in a dropdown shown from a button with three horizontal dots as can be seen on the right below.

When triggering an export of the grid via the toolbar, the export button should become disabled and an indeterminate, linear progress bar without value label should appear at the bottom of the Toolbar and run for as long as the export is taking before re-enabling the button. The button and linear progress respect the display density of the grid i.e. progress bar is 100% of the toolbar width and its bottom is always 1px below that of the toolbar so that it appears on top of the border normally present. The progress bar is 2px high and without border radius in every theme and uses the toolbar background color for its base and secondary,500 without stripes for the track.

Developer experience

enabling the toolbar with default widgets and setting a title

<igx-grid>
    <igx-grid-toolbar>
        <igx-grid-toolbar-title>{{ title }}</igx-grid-toolbar-title>
    </igx-grid-toolbar>
</igx-grid>

modifying the interaction widgets of the toolbar

<igx-grid>
    <igx-grid-toolbar>
        <igx-grid-toolbar-actions>
            <!-- Show only the pinning widget for the grid -->
            <igx-grid-toolbar-pinning></igx-grid-toolbar-pinning>
        </igx-grid-toolbar-actions>
    </igx-grid-toolbar>
</igx-grid>

enabling exporting to a csv/excel file

<igx-grid>
    <igx-grid-toolbar>
        <igx-grid-toolbar-actions>
            <igx-grid-toolbar-exporter [exportCSV]="false">
                <span excelText>Download as Excel file</span>
            </igx-grid-toolbar-exporter>
        </igx-grid-toolbar-actions>
    </igx-grid-toolbar>
</igx-grid>

enabling the progress bar indicator

<igx-grid>
    <igx-grid-toolbar [showProgress]="operationInProgress">
        ...
    </igx-grid-toolbar>
</igx-grid>

enabling different overlay settings

 <igx-grid-toolbar-actions>
    <igx-grid-toolbar-pinning [overlaySettings]="overlaySettingsGlobal"></igx-grid-toolbar-pinning>
    <igx-grid-toolbar-hiding [overlaySettings]="overlaySettingsAuto"></igx-grid-toolbar-hiding>
    ...

Localization

Given that all of the components of the toolbar now can be templated, developers can use the default Angular mechanism for localization/globalization.

Keyboard navigation

While there is a great reference point for an accessible toolbar, in our case the keyboard navigation flow follows the default DOM structure as provided by the end-user until it hits the virtualized parts of the grid.

Sample design

API

IgxGridToolbarComponent

Input properties

Name	Description	Type	Default value
showProgress	When enabled, shows the indeterminate progress bar	boolean	false

IgxGridToolbarPinningComponent

Input properties

Name	Description	Type	Default value
title	Title text for the column action component	string	Pinned columns
prompt	The placeholder text for the search input	string	Search columns...
columnListHeight	Sets the height of the column list in the dropdown	string	100%

IgxGridToolbarHidingComponent

Input properties

Name	Description	Type	Default value
title	Title text for the column action component	string	Pinned columns
prompt	The placeholder text for the search input	string	Search columns...
columnListHeight	Sets the height of the column list in the dropdown	string	100%

IgxGridToolbarExporterComponent

Input properties

Name	Description	Type	Default value
exportCSV	Show entry for CSV export	boolean	true
exportExcel	Show entry for Excel export	boolean	true
filename	The name for the exported file	string	ExportedData

Test scenarios

TODO

Accessibility

ARIA support

While there is a good reference point for toolbar in the context of a web page [example1, example2], this toolbar component has a slightly different role than the one suggested by the W3C and should generally omit some of the given guidelines in the specification.