-
Notifications
You must be signed in to change notification settings - Fork 162
IgxExcelExporterService Specification
Feature specification for the IgxExcelExporterService feature.
| Version | User | Date | Notes |
|---|---|---|---|
| 1.0 | DDavidkov | 2/22/2018 | Initial Draft |
| 1.1 | DDavidkov | 3/27/2018 | Updating to reflect final implementation |
We want to provide an option to export the IgniteUI for Agular Grid to excel. By default the resulting xlsx file will fully represent the exported grid. This means that it will contain all the columns and rows visible to the end user, in the order they are shown. All the filtered and hidden rows and columns shouldn't be a part of the exported xlsx file. Features that affect the UI of the grid, such as summaries or pinned columns, will also be reflected in the exported grid using native excel features whenever possible.
However, we will also allow the developers to specify if they want to export hidden columns or filtered out rows. The developers will also be able to prevent the exporting of columns and rows that are visible in the grid and change values of the exported cells. We will provide options for setting the width and the height of the rows and columns in the exported file, while choosing reasonable defaults if such settings are not provided.
Another option available to the developer will be to export arrays with homogeneous object, string, number or date data directly to excel.
We will only support xlsx format and the exporter will always create a new file with one sheet containing a table element with the exported data.
NOTE: When exporting an IgxHierarchicalGrid or a grid with multi-column headers, the exported data would not be displayed in a table element.
Developer:
- As a developer, I want to provide options for exporting the grid to Excel.
- As a developer, I want to be able to control which columns and rows are exported with options to change the exported data.
- As a developer, I want additional features that affect the UI of the grid to also be reflected in the exported Excel file.
- As a developer, I want to be able to export homogeneous array data to excel.
- As a developer, I want to be able to export hierarchical grid.
- As a developer, I want to be able to export grid with multi-column headers.
- As a developer, I want to be able to export grouped grid.
- As a developer, I want to be able to specify the width and height of columns and rows in the excel file.
End user:
- As an end user, I want to be able to export the grid I am working on directly in excel.
- As an end user, I want the exported grid to closely represent the grid shown on the screen.
- Be able to export the grid and the resulting excel file to closely represent it.
- Be able to prevent any column or row from exporting.
- Be able to specify the column width and the row height in the exported excel file.
- Be able to export homogeneous array data.
The exporter will provide means of exporting the grid to excel files.
3.1. End User Experience
The user will not be directly aware of the existence of the exporter as it will have no UI. They will be able to export the grid through button clicks or other means provided by the developer.
3.2. Developer Experience
The exporter is a service, injectable into the component that is being developed. From there the developer may call the export methods of the service to export their grid or array data. The exporter will also need an IgxEcelExporterOptions object to be provided. The IgxEcelExporterOptions will only require a name for the excel file, but it will also have properties that can be used to modify the layout of the exported excel, such as whether hidden columns or filtered out rows should be exported. We will also provide cancelable events for RowExporting and ColumnExporting in which, if canceled, will prevent the row/column from exporting.
3.3. Globalization/Localization
The exporter will be able to export grids/data that contains non Latin characters supported by Excel.
3.4. User Interface
There is no user interface for this feature.
3.5. API
| Name | Description | Type | Default value | Valid values |
|---|---|---|---|---|
| ignoreFiltering | Specifies whether filtered out rows should be exported | Boolean | false | true/false |
| ignoreColumnsVisibility | Specifies whether hidden columns should be exported | Boolean | false | true/false |
| ignoreColumnsOrder | Specifies if the exporter should ignore the current column order in the grid | Boolean | false | true/false |
| ignorePinning | Specifies if column pinning should be ignored. If ignoreColumnsOrder is set to true, this option will always be considered as set to true | Boolean | false | true/false |
| ignoreSorting | Specifies whether the exported data should be sorted as in the provided grid. | Boolean | false | true/false |
| ignoreGrouping | Specifies whether the exported data should be grouped as in the provided grid. | Boolean | false | true/false |
| ignoreMultiColumnHeaders | Specifies whether the exported data should include multi column headers as in the provided grid. | Boolean | false | true/false |
| columnWidth | Specifies the width of the columns in the exported excel file. If left unspecified or 0, the width of the largest string in the column will be used | Number | undefined | Any valid Number greater than or equal to 0 or undefined |
| rowHeight | Specifies the height of the rows in the exported excel file. If left unspecified or 0, the default height of the excel rows will be used | Number | undefined | Any valid Number greater than or equal to 0 or undefined |
| Name | Description | Type | Default value | Valid values |
|---|---|---|---|---|
| rowData | Contains the array with values that will be exported for this row. Can be modified by the developer, which will be reflected in the excel file, but it won't affect the grid in any way | Array | N/A | N/A |
| rowIndex | The index of the row in the exported excel file. Modifications to this option won't affect the exported file | Number | N/A | Any valid Number greater than or equal to 0 |
| cancel | Specifies whether the exporting of the row should be canceled | Boolean | false | true/false |
| Name | Description | Type | Default value | Valid values |
|---|---|---|---|---|
| header | The header of the exported column. Can be modified by the developer, which will be reflected in the excel file, but it won't affect the grid in any way. | String | N/A | Any valid string |
| columnIndex | The index of the column in the exported excel file. Can be modified by the developer, which will be reflected in the excel file, but it won't affect the grid in any way. | Number | N/A | Any valid Number greater than or equal to 0 |
| cancel | Specifies whether the exporting of the column should be canceled | Boolean | false | true/false |
| Name | Description | Type | Default value | Valid values |
|---|---|---|---|---|
| xlsx | The JSZip file representing the exported excel file | JSZip | N/A | N/A |
| Name | Description | Return type | Parameters |
|---|---|---|---|
| export | Exports the provided grid to excel | void | The IgxGrid component to be exported and the IgxExcelExporterOptions object |
| exportData | Exports the provided data to excel | void | The array containing the data to be exported and the IgxExcelExporterOptions object |
| Name | Description | Cancelable | Event arguments |
|---|---|---|---|
| onRowExport | Emitted when an excel row is being exported | True | RowExportingEventArgs |
| onColumnExport | Emitted when an excel column is being exported | True | ColumnExportingEventArgs |
| onExportEnded | Emitted when the excel file has been exported | False | ExcelExportEndedEventArgs |