CSV Exporter Service Specification

Overview

Character separated values formats allow storing tabular data in plain text. A file in such a format consists of lines. Each line is a data record and each record consists of one or more fields separated from each other by a certain character. These types of files are generally used for exchanging data between programs operating on incompatible formats.

Objectives

Provide an option to export IgniteUI for Angular Grid component to a character separated values format. By default the resulting text file will fully represent the exported grid, meaning that it will contain the data from all the columns and rows visible to the end user, in the order they are shown. All the filtered out and hidden rows and columns shouldn't be a part of the exported file.

However, we will also allow the developers to specify whether they want to honor or ignore certain features when exporting the grid. The developers will also be able to prevent the exporting of columns and rows, that are visible in the grid, and/or change values prior to exporting.

Another option available to the developer will be to export arrays with homogeneous object, string, number or date data.

We will only support ".csv", ".tsv" and ".tab" file formats and the exporter will always create a new file with the exported data.

User Stories

Developer:

As a developer, I want to provide options for exporting the IgxGridComponent.
As a developer, I want to be able to specify a delimiter different from "," and "\t".
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 data.
As a developer, I want to be able to export homogeneous array data.

End user:

As an end user, I want to be able to export the grid I am working on directly to plain text.
As an end user, I want the exported grid data to closely represent the grid shown on the screen.

Acceptance criteria

Be able to export the IgxGrid and the resulting file to closely represent the grid.
Be able to prevent any column or row from exporting.
Be able to export homogeneous array data.

Functionality

The exporter will provide means of exporting the IgxGrid to .csv, .tsv and .tab files. The format of the current implementation is as follows:

Each record in the result file will be located on a separate line, delimited by a line break (CRLF).
The last record in the file also has an ending line break.
A header line will appear as the first line of the file with the same format as the data records' lines. The header line will contain the names of the corresponding fields or a default field name when exporting homogeneous data array.
Within all records there may be one or more fields, separated by the specified delimiter. The last field in the record will not be followed by the delimiter.
Fields, containing line breaks (CR, LF, CRLF) or the delimiter character, will be enclosed in double-quotes.

References

RFC 4180 (https://tools.ietf.org/html/rfc4180)

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.

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 igxGrid or array data. The exporter will also need an IgxCsvExporterOptions object to be provided. The IgxCsvExporterOptions will require a name for the resulting file and a CsvFileType format, but it will also have properties that can be used to modify the exported data, 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.

Globalization/Localization

The exporter will be able to export grids/data that contains non Latin characters.

User Interface

There is no user interface for this feature.

API

IgxCsvExporterService

Methods

Name	Description	Return type	Parameters
export	Exports the provided grid	void	The IgxGrid component to be exported and the IgxCsvExporterOptions object
exportData	Exports the provided data	void	The array containing the data to be exported and the IgxCsvExporterOptions object

Events

Name	Description	Cancelable	Event arguments
onRowExport	Emitted when a data record is being exported	True	RowExportingEventArgs
onColumnExport	Emitted when a data field is being exported	True	ColumnExportingEventArgs
onExportEnded	Emitted when the file has been exported	False	CsvExportEndedEventArgs

IgxCsvExporterOptions

Options

Name	Description	Type	Default value	Valid values
fileType	The type of the result file	CsvFileTypes	N/A	CSV, TSV and TAB
valueDelimiter	Specifies the character that should be used for separating data fields	string	Comma(,), when fileType is CSV, and Tab(\t), when fileType is TSV or TAB	String values different from undefined, null and empty string
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

RowExportingEventArgs

Options

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 result 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 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

ColumnExportingEventArgs

Options

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 result 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 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 column should be canceled	Boolean	false	true/false