Overview

The DataExporter object can be used to export tabular data (an array of objects) to a large variety of file formats – CSV, HTML, JSON, PDF, TSV, XLSX, and XML.

To instantiate a DataExporter object, the user has to include the following files to the head of the page:

  • smart.element.js – the base class;
  • smart.export.js – the JS file containing the class DataExporter.

The following files can optionally be included if the user would like to export formatted dates or numbers:

  • smart.date.js – used for date formatting;
  • smart.numeric.js – used for number formatting.

Initialization

A DataExporter object can be instantiated by calling the DataExporter class constructor with four available arguments, all of which optional. The available options are listed below:

exportDetails (first argument)

An object containing the main settings to apply when exporting. The fields in the exportDetails object are the following:

style

An object that defines the way the columns and rows will be styled and formatted in the output file.

Note: style is only applicable when exporting to HTML, PDF, and XLSX.

The structure of the style object is shown below (all properties are optional):

  • «any valid CSS property» – applied to whole table
  • header (Object)
    • «any valid CSS property» – applied to header cells
    • «any column name» (Object)
      • «any valid CSS property» – applied to particular column header cell
  • columns (Object)
    • «any valid CSS property» – applied to column cells
    • «any column name» (Object)
      • «any valid CSS property» – applied to the cells of particular column
      • format – applicable to numeric and date columns
      • «n» (Object), where «n» is a row index (related to use of ConditionalFormatting object)
        • background
        • border
        • color
  • rows (Object)
    • «any valid CSS property» – applied to rows
    • alternationCount – determines the number of color alternations in rows
    • alternationStart – determines the starting index of color alternations in rows
    • alternationEnd – determines the ending index of color alternations in rows
    • alternationIndex«n»Color – determines the color of the «n»th color alternation
    • alternationIndex«n»BorderColor – determines the border color of the «n»th color alternation
    • alternationIndex«n»BackgroundColor – determines the background color of the «n»th color alternation
    • «n» (Object), where «n» is a row index
      • «any valid CSS property» – applied to particular row

Example:

const theme1 = {
    border: '1px solid black',
    borderCollapse: 'collapse',
    header: {
        height: '50px',
        border: '1px solid black',
        fontSize: '16px',
        fontWeight: 'bold',
        firstName: {
            width: '300px'
        },
        lastName: {
            width: '300px'
        },
        birthday: {
            width: '400px'
        },
        price: {
            textAlign: 'right',
            width: '150px'
        },
        quantity: {
            textAlign: 'right'
        },
        timeOfPurchase: {
            width: '300px'
        },
        expired: {
            textAlign: 'center'
        }
    },
    columns: {
        border: '1px solid black',
        birthday: {
            format: 'D'
        },
        price: {
            textAlign: 'right',
            format: 'c2'
        },
        quantity: {
            textAlign: 'right'
        },
        timeOfPurchase: {
            format: 'T'
        },
        expired: {
            textAlign: 'center'
        }
    },
    rows: {
        alternationCount: 3,
        alternationStart: 0,
        alternationIndex0Color: '#FFFFFF',
        alternationIndex0BackgroundColor: '#000000',
        alternationIndex1Color: '#CCCCCC',
        alternationIndex1BackgroundColor: '#555555',
        alternationIndex2Color: '#000000',
        alternationIndex2BackgroundColor: '#FFFFFF',
        3: {
            backgroundColor: '#FF0034'
        }
    }
}
const dataExporter = new Smart.Utilities.DataExporter({ style: theme1 });

exportHeader

Determines whether header information will be exported. By default, if exportHeader is not set, the header is exported. See also header sub-property.


Example:

const dataExporter = new Smart.Utilities.DataExporter({ exportHeader: false });

header

Represents an object defining the header information. If the exportHeader sub-property is set to false, header is not applied.

Important: If the header object is not set, but exportHeader is true, the first record of data will be considered a header.

The following fields are available in the header object:

  • columns – an array of objects representing a header cell. Each object has the fields:
    • label – the text to be displayed in the generated header cell
    • dataField – the data field associated with the generated header cell
    • columnGroup (optional) – the name of the parent column group; allows for hierarchical header cells
  • columngroups (optional) – an array of objects representing a header hierarchy. Each object has the fields:
    • label – the text to be displayed in the generated parent header cell
    • name – the value referenced in the columns columnGroup field
    • parentGroup – the name of a parent column group

Simple header example:

const header = {
    columns: [
        { label: 'First name', dataField: 'firstName' },
        { label: 'Last name', dataField: 'lastName' },
        { label: 'Birthday', dataField: 'birthday' }
    ]
};
const dataExporter = new Smart.Utilities.DataExporter({ header: header, exportHeader: true });

Hierarchical header example:

const header = {
    columns: [
        { label: 'First name', dataField: 'firstName', columnGroup: 'PersonalInfo' },
        { label: 'Last name', dataField: 'lastName', columnGroup: 'PersonalInfo' },
        { label: 'Birthday', dataField: 'birthday', columnGroup: 'PersonalInfo' },
        { label: 'Pet name', dataField: 'petName' },
        { label: 'Product names', dataField: 'productName', columnGroup: 'Details' },
        { label: 'Country', dataField: 'country', columnGroup: 'Details' },
        { label: 'Expired', dataField: 'expired', columnGroup: 'Details' },
        { label: 'Price', dataField: 'price', columnGroup: 'Purchase' },
        { label: 'Quantity', dataField: 'quantity', columnGroup: 'Purchase' },
        { label: 'Time of purchase', dataField: 'timeOfPurchase', columnGroup: 'Purchase' }
    ],
    columngroups: [
        { label: 'Personal info', name: 'PersonalInfo' },
        { label: 'Details', name: 'Details', parentGroup: 'ProductInfo' },
        { label: 'Purchase', name: 'Purchase', parentGroup: 'ProductInfo' },
        { label: 'Product info', name: 'ProductInfo' }
    ]
};
const dataExporter = new Smart.Utilities.DataExporter({ header: header, exportHeader: true });

hierarchical

Determines whether the data to be exported is hierarchical.


Example:

const dataExporter = new Smart.Utilities.DataExporter({ hierarchical: true });

expandChar

Determines the “expand” character that is displayed when hierarchical data is exported. By default, the “expand” character is +.

Note: expandChar is only applicable when exporting to HTML.


Example:

const dataExporter = new Smart.Utilities.DataExporter({ expandChar: '▼' });

collapseChar

Determines the “collapse” character that is displayed when hierarchical data is exported. By default, the “collapse” character is .

Note: collapseChar is only applicable when exporting to HTML and PDF.


Example:

const dataExporter = new Smart.Utilities.DataExporter({ expandChar: '▲' });

mergedCells

An array of objects that defines cells to be merged.

Note: mergedCells is only applicable when exporting to HTML, PDF, and XLSX.

The following fields are available in the mergedCells member objects:

  • cell – an array with two members – column index and row index.
  • colspan
  • rowspan

Example:

const mergedCells = [
    { cell: [2, 0], colspan: 1, rowspan: 2 },
    { cell: [3, 10], colspan: 3, rowspan: 3 }
];
const dataExporter = new Smart.Utilities.DataExporter({ mergedCells: mergedCells });

pageOrientation

Determines whether to export pages to PDF in portrait or landscape orientation. The default page orientation is ‘portrait’.


Example:

const dataExporter = new Smart.Utilities.DataExporter({ pageOrientation: 'landscape' });

groupBy (second argument)

An array which determines which data fields to group by. If set, the exported data will be grouped and group headers will be shown.

Note: groupBy is only applicable when exporting to HTML, PDF, and XLSX.


Example:

const dataExporter = new Smart.Utilities.DataExporter({ style: theme1, exportHeader: true }, ['lastName', 'firstName', 'quantity']);

filterBy (third argument)

An object which determines filtering conditions to be applied to exported data. filterBy is only applicable when exporting to XLSX and, if set, applies an AutoFilter in the spreadsheet program (such as Microsoft Excel or LibreOffice Calc) used to open the generated file.

The following fields are available in the filterBy object:

  • «any valid data field name» – an object with the following fields:
    • operator1 (“or”) or 0 (“and”)
    • filters – an array of objects with the following fields:
      • value – the value to filter by
      • condition – filtering condition
        • possible conditions for string filter: ‘EMPTY’, ‘NOT_EMPTY’, ‘CONTAINS’, ‘CONTAINS_CASE_SENSITIVE’, ‘DOES_NOT_CONTAIN’, ‘DOES_NOT_CONTAIN_CASE_SENSITIVE’, ‘STARTS_WITH’, ‘STARTS_WITH_CASE_SENSITIVE’, ‘ENDS_WITH’, ‘ENDS_WITH_CASE_SENSITIVE’, ‘EQUAL’, ‘EQUAL_CASE_SENSITIVE’, ‘NULL’, ‘NOT_NULL’
        • possible conditions for numeric filter: ‘EQUAL’, ‘NOT_EQUAL’, ‘LESS_THAN’, ‘LESS_THAN_OR_EQUAL’, ‘GREATER_THAN’, ‘GREATER_THAN_OR_EQUAL’, ‘NULL’, ‘NOT_NULL’
        • possible conditions for date filter: ‘EQUAL’, ‘NOT_EQUAL’, ‘LESS_THAN’, ‘LESS_THAN_OR_EQUAL’, ‘GREATER_THAN’, ‘GREATER_THAN_OR_EQUAL’, ‘NULL’, ‘NOT_NULL’

Example:

const filterBy = {
    firstName: {
        operator: 1,
        filters: [{
            value: 'Ma',
            condition: 'STARTS_WITH'
        },
        {
            value: 'y',
            condition: 'CONTAINS'
        }]
    },
    birthday: {
        operator: 0,
        filters: [{
            value: new Date(1930, 0, 1),
            condition: 'GREATER_THAN'
        },
        {
            value: new Date(2010, 0, 1),
            condition: 'LESS_THAN'
        }]
    }
};
const dataExporter = new Smart.Utilities.DataExporter({ style: theme1, exportHeader: true }, undefined, filterBy);

conditionalFormatting (fourth argument)

An array of objects with information about column conditional formatting. Conditional formatting is applicable only when exporting to HTML, PDF, and XLSX. For HTML and PDF, the conditional styling is passed directly to the style argument. The fourth argument – conditionalFormatting – is applicable to XLSX export only.

The following fields are available in the conditionalFormatting member objects:

  • column – the data field to apply conditional formatting to
  • condition – applicable conditions are ‘equal’, ‘lessThan’, ‘greaterThan’, ‘notEqual’, ‘between’, ‘duplicate’, ‘topNItems’, ‘bottomNItems’, ‘topNPercent’, ‘bottomNPercent’, ‘aboveAverage’, ‘belowAverage’, ‘contains’, ‘doesNotContain’, ‘dateOccur’
  • comparator – the value to apply the condition by. Applicable to conditions ‘equal’, ‘lessThan’, ‘greaterThan’, ‘notEqual’, ‘between’, ‘topNItems’, ‘bottomNItems’, ‘topNPercent’, ‘bottomNPercent’, ‘contains’, ‘doesNotContain’, ‘dateOccur’.
  • background – the background color (in RGBA notation) to apply to cells that match the condition
  • color – the text color to apply to cells that match the condition. Available options are ‘White’ and ‘Black’.

Example:

const conditionalFormatting = [
    {
        column: 'firstName',
        condition: 'contains',
        comparator: 'P',
        background: 'rgba(197, 16, 204, 1)',
        color: 'White'
    },
    {
        column: 'price',
        condition: 'greaterThan',
        comparator: 60,
        background: 'rgba(0, 119, 204, 1)',
        color: 'White'
    },
    {
        column: 'timeOfPurchase',
        condition: 'dateOccur',
        comparator: 'lastMonth',
        background: 'rgba(130, 204, 108, 1)',
        color: 'Black'
    }
];
const dataExporter = new Smart.Utilities.DataExporter({ style: theme1, exportHeader: true }, undefined, undefined, conditionalFormatting);

exportData method

The method exportData exports tabular data (an array of objects) to one of a number of available file formats and applies the settings passed as arguments when constructing the DataExporter object. It has three arguments, listed below:

  • data – the data to export
  • format – the file format to export to. Available options are: ‘csv’, ‘html’, ‘json’, ‘pdf’, ‘tsv’, ‘xlsx’, and ‘xml’.
  • fileName – the name of the output file. If file extension is not provided in the name, it is automatically added.

Simple example:

const dataExporter = new Smart.Utilities.DataExporter();
const sampleData = [{
    firstName: "Shelley",
    lastName: "Bjorn",
    petName: "Tommy",
    country: "Singapore"
}, {
    firstName: "Antoni",
    lastName: "Fuller",
    petName: "Lucky",
    country: "USA"
}, {
    firstName: "Nancy",
    lastName: "Nodier",
    petName: "Charlie",
    country: "France"
}];
dataExporter.exportData(sampleData, 'xlsx', 'myFile');

Example with header info included in the data:

const dataExporter = new Smart.Utilities.DataExporter({ exportHeader: true });
const sampleData = [{
    firstName: "First name",
    lastName: "Last name",
    petName: "Pet name",
    country: "Country"
}, {
    firstName: "Shelley",
    lastName: "Bjorn",
    petName: "Tommy",
    country: "Singapore"
}, {
    firstName: "Antoni",
    lastName: "Fuller",
    petName: "Lucky",
    country: "USA"
}, {
    firstName: "Nancy",
    lastName: "Nodier",
    petName: "Charlie",
    country: "France"
}];
dataExporter.exportData(sampleData, 'html', 'myFile.html');

Example with header info included in separate object:

const header = {
    columns: [
        { label: 'First name', dataField: 'firstName' },
        { label: 'Last name', dataField: 'lastName' },
        { label: 'Pet name', dataField: 'petName' },
        { label: 'Country', dataField: 'country' }
    ]
}
const dataExporter = new Smart.Utilities.DataExporter({ header: header, exportHeader: true });
const sampleData = [{
    firstName: "Shelley",
    lastName: "Bjorn",
    petName: "Tommy",
    country: "Singapore"
}, {
    firstName: "Antoni",
    lastName: "Fuller",
    petName: "Lucky",
    country: "USA"
}, {
    firstName: "Nancy",
    lastName: "Nodier",
    petName: "Charlie",
    country: "France"
}];
dataExporter.exportData(sampleData, 'pdf', 'myFile.pdf');

Hierarchical data can also be exported. There are two ways to present the data structure:

  • by passing flat array of objects with _keyDataField and _parentDataField fields denoting the relations between items.
  • by passing nested array of objects with the nesting denoting the relations between items.

Additionally, the _expanded field denotes if a parent item should appear expanded by default or not when exporting to HTML. In that case, items can dynamically be expanded and collapsed in the output file via the mouse.

Example with hierarchical data export (with flat data):

const dataExporter = new Smart.Utilities.DataExporter({ exportHeader: true, hierarchical: true });
const flatSampleData = [
{
    "FirstName": "First Name",
    "LastName": "Last Name",
    "Country": "Country",
    "Title": "Title",
    "HireDate": "Hire Date",
    "BirthDate": "Birth Date",
    "City": "City",
    "Address": "Address"
},
{
    "_keyDataField": 1,
    "FirstName": "Nancy",
    "LastName": "Davolio",
    "_parentDataField": 2,
    "Country": "USA",
    "Title": "Sales Representative",
    "HireDate": new Date(1992, 4, 1),
    "BirthDate": new Date(1948, 11, 8),
    "City": "Seattle",
    "Address": "507 - 20th Ave. E.Apt. 2A"
},
{
    "_keyDataField": 2,
    "FirstName": "Andrew",
    "LastName": "Fuller",
    "_parentDataField": null,
    "Country": "USA",
    "Title": "Vice President, Sales",
    "HireDate": new Date(1992, 7, 14),
    "BirthDate": new Date(1952, 1, 19),
    "City": "Tacoma",
    "Address": "908 W. Capital Way",
    "_expanded": true,
},
{
    "_keyDataField": 3,
    "FirstName": "Janet",
    "LastName": "Leverling",
    "_parentDataField": 2,
    "Country": "USA",
    "Title": "Sales Representative",
    "HireDate": new Date(1992, 3, 1),
    "BirthDate": new Date(1963, 7, 30),
    "City": "Kirkland",
    "Address": "722 Moss Bay Blvd."
},
{
    "_keyDataField": 4,
    "FirstName": "Margaret",
    "LastName": "Peacock",
    "_parentDataField": 2,
    "Country": "USA",
    "Title": "Sales Representative",
    "HireDate": new Date(1993, 4, 3),
    "BirthDate": new Date(1937, 8, 19),
    "City": "Redmond",
    "Address": "4110 Old Redmond Rd."
},
{
    "_keyDataField": 5,
    "FirstName": "Steven",
    "LastName": "Buchanan",
    "_parentDataField": 2,
    "Country": "UK",
    "Title": "Sales Manager",
    "HireDate": new Date(1993, 9, 17),
    "BirthDate": new Date(1955, 2, 4),
    "City": "London",
    "Address": "14 Garrett Hill",
    "_expanded": false,
},
{
    "_keyDataField": 6,
    "FirstName": "Michael",
    "LastName": "Suyama",
    "_parentDataField": 5,
    "Country": "UK",
    "Title": "Sales Representative",
    "HireDate": new Date(1993, 9, 17),
    "BirthDate": new Date(1963, 6, 2),
    "City": "London",
    "Address": "Coventry House Miner Rd."
},
{
    "_keyDataField": 7,
    "FirstName": "Robert",
    "LastName": "King",
    "_parentDataField": 5,
    "Country": "UK",
    "Title": "Sales Representative",
    "HireDate": new Date(1994, 0, 2),
    "BirthDate": new Date(1960, 4, 29),
    "City": "London",
    "Address": "Edgeham Hollow Winchester Way"
},
{
    "_keyDataField": 8,
    "FirstName": "Laura",
    "LastName": "Callahan",
    "_parentDataField": 2,
    "Country": "USA",
    "Title": "Inside Sales Coordinator",
    "HireDate": new Date(1994, 3, 5),
    "BirthDate": new Date(1958, 0, 9),
    "City": "Seattle",
    "Address": "4726 - 11th Ave. N.E."
},
{
    "_keyDataField": 9,
    "FirstName": "Anne",
    "LastName": "Dodsworth",
    "_parentDataField": 5,
    "Country": "UK",
    "Title": "Sales Representative",
    "HireDate": new Date(1994, 10, 15),
    "BirthDate": new Date(1966, 0, 27),
    "City": "London",
    "Address": "7 Houndstooth Rd."
}];
dataExporter.exportData(flatSampleData, 'html', 'myFile.html');

Example with hierarchical data export (with nested data):

const dataExporter = new Smart.Utilities.DataExporter({ exportHeader: true, hierarchical: true });
const nestedSampleData = [
{
    "FirstName": "First Name",
    "LastName": "Last Name",
    "Country": "Country",
    "Title": "Title",
    "HireDate": "Hire Date",
    "BirthDate": "Birth Date",
    "City": "City",
    "Address": "Address"
},
{
    "FirstName": "Andrew",
    "LastName": "Fuller",
    "Country": "USA",
    "Title": "Vice President, Sales",
    "HireDate": new Date(1992, 7, 14),
    "BirthDate": new Date(1952, 1, 19),
    "City": "Tacoma",
    "Address": "908 W. Capital Way",
    "_expanded": true,
    children: [
    {
        "FirstName": "Laura",
        "LastName": "Callahan",
        "Country": "USA",
        "Title": "Inside Sales Coordinator",
        "HireDate": new Date(1994, 3, 5),
        "BirthDate": new Date(1958, 0, 9),
        "City": "Seattle",
        "Address": "4726 - 11th Ave. N.E."
    },
    {
        "FirstName": "Nancy",
        "LastName": "Davolio",
        "Country": "USA",
        "Title": "Sales Representative",
        "HireDate": new Date(1992, 4, 1),
        "BirthDate": new Date(1948, 11, 8),
        "City": "Seattle",
        "Address": "507 - 20th Ave. E.Apt. 2A"
    },
    {
        "FirstName": "Steven",
        "LastName": "Buchanan",
        "Country": "UK",
        "Title": "Sales Manager",
        "HireDate": new Date(1993, 9, 17),
        "BirthDate": new Date(1955, 2, 4),
        "City": "London",
        "Address": "14 Garrett Hill",
        "_expanded": false,
        children: [
        {
            "FirstName": "Michael",
            "LastName": "Suyama",
            "Country": "UK",
            "Title": "Sales Representative",
            "HireDate": new Date(1993, 9, 17),
            "BirthDate": new Date(1963, 6, 2),
            "City": "London",
            "Address": "Coventry House Miner Rd."
        },
        {
            "FirstName": "Robert",
            "LastName": "King",
            "Country": "UK",
            "Title": "Sales Representative",
            "HireDate": new Date(1994, 0, 2),
            "BirthDate": new Date(1960, 4, 29),
            "City": "London",
            "Address": "Edgeham Hollow Winchester Way"
        },
        {
            "FirstName": "Anne",
            "LastName": "Dodsworth",
            "Country": "UK",
            "Title": "Sales Representative",
            "HireDate": new Date(1994, 10, 15),
            "BirthDate": new Date(1966, 0, 27),
            "City": "London",
            "Address": "7 Houndstooth Rd."
        }]
    },
    {
        "FirstName": "Janet",
        "LastName": "Leverling",
        "Country": "USA",
        "Title": "Sales Representative",
        "HireDate": new Date(1992, 3, 1),
        "BirthDate": new Date(1963, 7, 30),
        "City": "Kirkland",
        "Address": "722 Moss Bay Blvd."
    },
    {
        "FirstName": "Margaret",
        "LastName": "Peacock",
        "Country": "USA",
        "Title": "Sales Representative",
        "HireDate": new Date(1993, 4, 3),
        "BirthDate": new Date(1937, 8, 19),
        "City": "Redmond",
        "Address": "4110 Old Redmond Rd."
    }]
}];
dataExporter.exportData(nestedSampleData, 'xml', 'myFile');