Web Components Tree Grid Toolbar
The Ignite UI for Web Components Toolbar in is a container for UI operations in the Web Components Tree Grid. The Web Components toolbar is located at the top of the Web Components component, i.e., the IgcTreeGridComponent
and it matches its horizontal size. The toolbar container can host any custom content or set of predefined UI controls. The default set for the Web Components Tree Grid includes:
- Ocultação de coluna
- Fixação de coluna
- Exportação do Excel
- Filtragem avançada
The toolbar and the predefined UI components support Web Components events and expose API for developers.
Web Components Toolbar Grid Example
The predefined Actions
and title
UI components are added inside the IgcGridToolbar
and this is all needed to have a toolbar providing default interactions with the corresponding Grid features:
<igc-tree-grid id="treeGrid" primary-key="ID" foreign-key="ParentID" auto-generate="true">
<igc-grid-toolbar>
<igc-grid-toolbar-title>Tree Grid Toolbar</igc-grid-toolbar-title>
<igc-grid-toolbar-actions>
<igc-grid-toolbar-advanced-filtering><igc-grid-toolbar-advanced-filtering>
<igc-grid-toolbar-hiding></igc-grid-toolbar-hiding>
<igc-grid-toolbar-pinning></igc-grid-toolbar-pinning>
<igc-grid-toolbar-exporter></igc-grid-toolbar-exporter>
</igc-grid-toolbar-actions>
</igc-grid-toolbar>
</igc-tree-grid>
[!Note] As seen in the code snippet above, the predefined
Actions
UI components are wrapped in theIgcGridToolbarActions
container. This way, the toolbar title is aligned to the left of the toolbar and the actions are aligned to the right of the toolbar.
Obviamente, cada uma dessas interfaces do usuário pode ser adicionada independentemente uma da outra ou pode não ser adicionada. Dessa forma, o contêiner da barra de ferramentas será renderizado vazio:
<igc-tree-grid primary-key="ID" foreign-key="ParentID" auto-generate="true">
<igc-grid-toolbar>
</igc-grid-toolbar>
</igc-tree-grid>
Para obter uma visão abrangente de cada um dos componentes padrão da interface do usuário, continue lendo a seção Recursos abaixo.
Características
The toolbar is great at separating logic/interactions which affects the grid as a whole.
As shown above, it can be configured to provide default components for controlling, column hiding, column pinning, advanced filtering and exporting data from the grid.
These features can be enabled independently from each other by following a pattern similar to the card component of the Ignite UI for Web Components suite.
Listed below are the main features of the toolbar with example code for each of them.
Title
Setting a title for the toolbar in your grid is achieved by using the IgcGridToolbarTitle
.
Users can provide anything from simple text to more involved templates.
<igc-grid-toolbar>
<igc-grid-toolbar-title>Grid toolbar title</igc-grid-toolbar-title>
</igc-grid-toolbar>
Actions
The IgcGridToolbarActions
is where users can place actions/interactions in relation to the parent grid.
As with the title portion of the toolbar, users can provide anything inside that template part, including the default
toolbar interaction components.
<igc-grid-toolbar>
<igc-grid-toolbar-actions>
<!-- ... -->
</igc-grid-toolbar-actions>
</igc-grid-toolbar>
Fixação de coluna
The IgcGridToolbarPinning
component provides the default UI for interacting with column pinning in the grid.
The component is setup to work out of the box with the parent grid containing the toolbar as well as several input properties for customizing the UI, such as the component title, the placeholder for the component input and the height of the dropdown itself.
<igc-grid-toolbar>
<igc-grid-toolbar-actions>
<igc-grid-toolbar-pinning
title="Grid pinned columns"
prompt="Filter column collection"
column-list-height="400px">
</igc-grid-toolbar-pinning>
</igc-grid-toolbar-actions>
</igc-grid-toolbar>
Ocultação de coluna
The IgcGridToolbarHiding
provides the default UI for interacting with column hiding. Exposes the same input properties for customizing the UI, such as the component
title, the placeholder for the component input and the height of the dropdown itself.
<igc-grid-toolbar>
<igc-grid-toolbar-actions>
<igc-grid-toolbar-hiding
title="Grid column hiding"
prompt="Filter column collection"
column-list-height="400px">
</igc-grid-toolbar-hiding>
</igc-grid-toolbar-actions>
</igc-grid-toolbar>
Filtragem avançada
Toolbar Advanced Filtering component provides the default UI for the Advanced Filtering feature. The component exposes a way to change the default text of the button.
<igc-grid-toolbar>
<igc-grid-toolbar-actions>
<igc-grid-toolbar-advanced-filtering>Custom text for the toggle button</igc-grid-toolbar-advanced-filtering>
</igc-grid-toolbar-actions>
</igc-grid-toolbar>
Data Exporting
As with the rest of the toolbar actions, exporting is provided through a IgcGridToolbarExporter
out of the box.
The toolbar exporter component exposes several input properties for customizing both the UI and the exporting experience.
These range from changing the display text, to enabling/disabling options in the dropdown to customizing the name of the generated file. For full reference, consult the API documentation for the ToolbarExporter
.
Here is a snippet showing some of the options which can be customized through the Web Components template:
<igc-grid-toolbar>
<igc-grid-toolbar-actions>
<igc-grid-toolbar-exporter export-csv="true" export-excel="true" filename="exported_data">
</igc-grid-toolbar-exporter>
</igc-grid-toolbar-actions>
</igc-grid-toolbar>
In addition to changing the exported filename, the user can further configure the exporter options by waiting for the ToolbarExporting
event and customizing the options entry in the event properties.
[!Note] By default when exporting to CSV the exporter exports using a comma separator and uses a '.csv' extension for the output file. You can customize these exporting parameters by subscribing to events of the exporter or changing the values of the exporter options fields. You can also cancel the export process by setting the cancel field of the event args to true.
O snippet de código a seguir demonstra a assinatura do evento de exportação da barra de ferramentas e a configuração das opções do exportador:
<igc-tree-grid id="treeGrid"></igc-tree-grid>
constructor() {
var treeGrid = document.getElementById('treeGrid') as IgcTreeGridComponent;
treeGrid.addEventListener("toolbarExporting", this.configureExport);
}
public configureExport(evt: CustomEvent<IgcGridToolbarExportEventArgs>) {
const args = evt.detail;
const options: IgcExporterOptionsBase = args.options;
if (options) {
options.fileName = `Report_${new Date().toDateString()}`;
(args.exporter as any).columnExporting.subscribe((columnArgs: any) => {
columnArgs.cancel = columnArgs.header === 'Name';
});
}
}
O exemplo a seguir demonstra como personalizar os arquivos exportados:
Exporting Indicator
When using the default toolbar exporter component, whenever an export operation takes place the toolbar will show a progress indicator while the operation is in progress.
Moreover, users can set the toolbar ShowProgress
property and use for their own long running operations or just as another way to signify an action taking place in the grid.
The sample belows uses has significant amount of data, in order to increase the time needed for data export so the progressbar can be seen. Additionally it has another button that simulates a long running operation in the grid:
Custom Content
Se a parte de ações do componente da barra de ferramentas não for suficiente para um caso de uso específico, a própria barra de ferramentas terá uma projeção de conteúdo geral em que os usuários podem fornecer interface do usuário adicional. Se o usuário precisar da respectiva instância de grade para chamadas ou associações de API, ele poderá criar uma variável de referência de modelo.
Aqui está um trecho de exemplo:
<igc-tree-grid id="grid">
<igc-grid-toolbar>
<igc-grid-toolbar-title>title</igx-grid-toolbar-title>
<!--
Everything between the toolbar tags except the default toolbar components/directives
will be projected as custom content.
-->
<igc-grid-toolbar-actions>
</igc-grid-toolbar-actions>
</igc-grid-toolbar>
</igc-tree-grid>
O exemplo a seguir demonstra como adicionar um botão adicional à barra de ferramentas para limpar o conjunto de classificação clicando nos cabeçalhos das colunas:
Styling
Além dos temas predefinidos, a grade pode ser ainda mais personalizada ao definir algumas das propriedades CSS disponíveis. Caso você queira alterar algumas das cores, precisa definir uma classe para a grade primeiro:
<igc-tree-grid class="grid"></igc-tree-grid>
Em seguida, defina as propriedades CSS relacionadas para essa classe:
.grid {
--ig-grid-toolbar-background-color: #2a2b2f;
--ig-grid-toolbar-title-text-color: #ffcd0f;
--ig-grid-toolbar-dropdown-background: #2a2b2f;
}
Demo
API References
O serviço Grid Toolbar tem mais algumas APIs para explorar, listadas abaixo.
IgcTreeGridComponent
Events:ToolbarExporting
Additional Resources
Nossa comunidade é ativa e sempre acolhedora para novas ideias.