new ExportOptions()
The ExportOptions type defines options to export the control's data into CSV format. The Export() method exports data to CSV format. A comma-separated values (CSV) file is a delimited text file that uses a comma to separate values. Each line of the file is a data record. Each record consists of one or more fields, separated by commas. The ExportOptions type defines how the control's data is exported, including which items and columns to export, the format of the exported data, and other related options. For instance, the "items" field allows specifying whether to export all items, only visible items, selected items, checked items, leaf items, or to use a custom filter with the "only" option. The "columns" field defines which columns to include in the export and how to format their data. The "format" field determines whether the exported data is returned as a CSV string or as an array. Additional options such as "rtrim", "eor", "eof", "hdr", and "str" provide further control over the structure and formatting of the exported data.
Members
(static) columns :object
The columns field specifies a list of columns to export.
Specifies the list of columns to export. The columns can be one of the following:
- columns {null}, exports all visible columns of the control exactly as they are displayed (@since 4.3)
- columns {number}, indicates a numeric value that defines the index of the column to export
- columns {"all"} , exports all columns of the control (@since 4.3)
- columns {string}, specifies both the columns to export and the type of the cell's data to be used (@since 4.3). The available data types include value ("v", default), plain caption ("pc", text excluding ex-HTML format), formatted caption ("c", displayed value after applying the column's format), state ("s", 0 or 1), or any other name that indicates the cell's method to call. The column list follows the format "index,index[(data)],...", where each index represents the column's index, and (data) defines how the column is exported (e.g., v for value, c for caption, pc for plain caption, or s for state). For example, "0(cap),1(cap),2,3" exports captions for the first two columns and values for the remaining columns, while "0(chk)" exports the checkbox state for the first column. If no explict data is specifed by the "columns" field the column exports data as specified by the "data" field. For instance, if the "columns" field is "0(cap),1,2,3", and "data" field is "s", the control exports the caption for the first column, and the check-box states for the columns 1, 2 and 3
- columns {Column}, specifies the object reference to the column to export
Type:
- object
Example
null {null}, exports all visible columns of the control exactly as they are displayed (@since 4.3)
0 {number}, exports the first column only
"C1,C2" {string}, exports the columns C1 and C2(static) data :object
The data field specifies the method used to export the cell's data as:
- "v", to export the cell's value (default)
- "pc", to export the cell's plain caption (text excluding ex-HTML format)
- "c", to export the cell's formatted caption (displayed value after applying the column's format)
- "s", to export the cell's checkbox-state (0 or 1)
Type:
- object
Example
null {null} or "v" {string}, exports the cell's value (by default)
"pc" {string}, exports the cell's caption excluding ex-HTML format
"s" {string}, exports the cell's (checkbox) state instead of its value(static) eof :object
The eof (EndOfField) field specifies the character to separate fields within the row/item/line (has effect only if format field is "CSV"). The eof field specifies the character to separate fields within the row/item/line (has effect only if format field is "CSV"). For example, setting eof to "\t" would specify that fields are separated by a tab character, while setting it to "," would indicate that fields are separated by a comma character. By default, eof is set to ",", which means that fields are separated by commas in the exported CSV data.
Type:
- object
Example
"," {string}, specifies comma charactar as field separator (default)
"\t" {string}, specifies TAB charactar as field separator(static) eor :object
The eor (EndOfRow) field specifies the characters the row/item/line ends (has effect only if format field is "CSV"). The eor field specifies the delimiter, which can be a character, string, or regular expression (@since 4.4), used to identify the end of a row, item, or line during parsing (has effect only if format field is "CSV"). For example, setting eor to ";" would indicate that each row/item/line ends with a semicolon character. Alternatively, using a regular expression such as /^[ \t]*\r\n/m would specify that empty lines (lines that contain only spaces or tabs followed by a Windows-style newline) delimit each item. By default, eor is set to "\r\n", which means that each row/item/line ends with a carriage return and newline sequence.
Type:
- object
Example
"\r\n" {string}, specifies that the \r\n sequence ends each row/item/line (default)
";" {string}, specifies that the ; character ends each row/item/line(static) format :object
The format field determines the type of data the Export() method returns. The supported format is "CSV", meaning the method returns a CSV-formatted string containing the control's data. For any other value, the format defaults to "Array", where the data is exported as a two-dimensional array. When format is set to "CSV", the Export() method generates a string in CSV format, which includes delimiters for fields and rows as specified by the eof and eor options, and may include quoted values if necessary. When format is set to any other value (or left as null), the Export() method returns the data as an array of arrays, where each inner array represents a row/item/line of data, and each element within the inner array corresponds to a field's value.
Type:
- object
Example
null {null}, specifies that the Export() method returns an array of [[value]] type
"CSV" {string}, specifies that the Export() method returns a string in CSV format(static) hdr :object
The hdr field specifies whether the method exports the header of the columns (first line). The hdr field specifies whether the Export() method includes the header of the columns as the first line in the exported data (has effect only if format field is "CSV"). If hdr is set to true, the first line of the exported CSV data will contain the column headers, which are typically derived from the column captions. If hdr is set to false, the exported CSV data will not include a header line, and will consist only of the data rows/items/lines. By default, hdr is set to false, meaning that no header line is included in the export unless explicitly specified.
Type:
- object
- Since:
- 5.0
Example
false {boolean}, specifies the no header line is exported
true {boolean}, exports the control's header as first line(static) items :object
The items field specifies the items to export.
The items field can be one of the following value:
- "all", exports all items, including the locked (@since 4.3), hidden or collapsed items
- "vis", exports the visible items, excluding locked items, child items of collapsed elements or items that are not visible (e.g., items not matching the filter, or with a height of 0)
- "sel", exports the items that are currently selected
- "chk", exports all checked and visible items; when using this option, the first column in the columns list must indicate the index of the column used to query the checkbox state
- "leaf", exports the leaf items of the control, excluding parent or grouped items, ensuring that only the lowest-level data entries are included in the export (@since 4.3)
- "only", allows filtering specific item types for export (@since 4.3). The item types are listed in parentheses, separated by commas. Supported types include: locked, selected, visible, checked, sortable, selectable, divider, leaf, and expanded, as explained below.
Syntax:
only[byindex](type1,type2,!type3,...)
Supported scopes:
locked, includes items that are locked to the top or bottom of the control, meaning they remain fixed in place and are not scrollable
selected, includes items that are currently selected
visible, includes items that are included in the current filter (i.e., items that are not hidden due to filtering)
checked, includes items that are checked. a column index can be specified using brackets, e.g., "checked[1]" exports items checked in column 1
sortable, includes items that can be reordered (sortable items)
selectable, includes items that can be selected
divider, includes divider items, which are typically non-interactive items used for separation
leaf, includes items that do not have child elements (leaf nodes in a tree structure)
expanded, includes items that are currently expanded, showing their child elements
The "byindex" flag can be specified inside square brackets ([]) to indicate that the items should be listed by their original index order rather than their current display order.
Negating a scope (!scope)
Prefixing a scope with ! excludes items of that type.
Examples:
"only(selected)", exports only selected items
"only(!leaf,selected)", exports only selected parent items (excluding leaf items)
"only(sortable,selectable,!divider)", exports sortable and selectable items, but not dividers
"only(checked[1])", exports only items that are checked in column index 1
"only(locked)", exports only items that are locked to the top or bottom (not scrollable)
"only(visible)", exports only items that match the current filter criteria
""only[byindex]()", exports all items in their original dataset order rather than their current display order
Type:
- object
Example
"", exports nothing
"sel", exports only selected items(static) rtrim :object
The rtrim field includes or excludes undefined values from right of each row/item/line. The rtrim field specifies whether undefined values on the right of each row/item/line are excluded from the export data, which determines whether the number of fields within the lines is constant or variable. If rtrim is set to false, all values are included in the result, generating the same number of fields on each line. If rtrim is set to true, undefined values on the right of each row/item/line are excluded, which can generate different numbers of fields on different lines depending on the presence of undefined values.
Type:
- object
Example
false {boolean}, all values are included in the result (generates the same number of fields on each line)
true {boolean}, undefined values on the right of each row/item/line are excluded (generates different number of fields on different lines)(static) str :object
The str field specifies the character to quote values (has effect only if format field is "CSV"). The str field specifies the character used to quote values in the exported CSV data (has effect only if format field is "CSV"). This character is used to enclose field values that contain special characters such as the field separator (eof), row separator (eor), or the quote character itself. For example, if str is set to "\"", then any field value that contains a comma, newline, or double quote will be enclosed in double quotes in the exported CSV. If str is set to "'", then single quotes will be used for quoting such values. By default, str is set to "\"", which means that double quotes are used for quoting values in the exported CSV data.
Type:
- object
Example
"\"" {string}, specifies " character to quote any value that contains other " or eof character (default)
"'" {string}, specifies ' character to quote any value that contains other ' or eof character