Grid Toolbar Specification
- Grid Toolbar Specification
CodeX - Diyan Dimitrov
- Diyan Dimitrov | Date:
- Stefan Ivanov | Date:
- Radoslav Mirchev | Date:
- 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 |
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.
Provide a way for users to centralize grid related UI and interactions.
- 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.
- 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.
- 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
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
R.K.: I suppose this section has to be changed now we decided to not bind the height of the toolbar to the display density property.
The toolbar has fixed-height Display Density variations. The UI components nested in the toolbar may not inherit Grid's Display Density. For example, Grid and Toolbar in Comfortable Display Density would have Search input in Cosy. If the user needs to have Comfortable Search Input, it is recommended to be put outside of the grid, as it is shown in this sample: https://www.infragistics.com/products/ignite-ui-angular/angular/components/grid/search.html
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.
- 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>Given that all of the components of the toolbar now can be templated, developers can use the default Angular mechanism for localization/globalization.
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.
| Name | Description | Type | Default value |
|---|---|---|---|
| showProgress | When enabled, shows the indeterminate progress bar | boolean | false |
| 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% |
| 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% |
| 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 |
TODO
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.
The toolbar should follow the direction set by the theme engine.
As of the current version of this document, there are not major limitations which should be listed in this section.
https://material.io/guidelines/components/data-tables.html#data-tables-specs