[]
        
(Showing Draft Content)

SpreadJS File Format

SpreadJS allows users to open and save large files in minimum time and export or import in different file formats like Excel, CSV, SSJSON (older SpreadJS format), and SJS (new faster SpreadJS format). The new SJS format significantly improves the load time and memory usage when working with very large Excel files, while greatly reducing the file size when resaved as compared to previous SpreadJS versions.

To perform file operations such as open, save, import and export in different formats, SpreadJS provides the gc.spread.sheets.io.xxx.js plugin.

The GC.Spread.Sheets.Workbook class provides the following methods for different file operations.

Methods

Description

open

Loads an SpreadJS file.

save

Saves the SpreadJS file.

export

Exports the file to Excel, SSJSON, SJS or CSV format.

import

Imports files with Excel, SSJSON, SJS, CSV or JavaScript formats.

In the following sections we will see in detail the different file operations.

Open Files

You can load the SpreadJS files in Spread using the open method. This method provides the following parameters:

  • file blob: It represents the zipped spreadsheet data file.

  • successCallBack: This function gives a success callback when loading the file is complete and accepts JSON as argument.

  • errorCallBack: This function gives an error callback when the file loading returns an error.

  • openOptions: This parameter is inherited from the GC.Spread.Sheets.OpenOptions Typedef.

    The different open options are given below:

Options

Description

includeStyles

Indicates whether the style can be included when loading. By default, it is true.

includeFormulas

Indicates whether the formula can be included when loading. By default, it is true.

fullRecalc

Indicates whether calculation can be included after loading the JSON data. By default, it is true.

dynamicReferences

Indicates whether functions can be calculated with dynamic reference. By default, it is true.

calcOnDemand

Indicates whether formulas can be calculated only when they are demanded. By default, it is true.

includeUnusedStyles

Indicates whether the name style can be included when converting Excel XML file to JSON. By default, it is true.

openMode

Inherited from GC.Spread.Sheets.OpenMode enumeration, it specifies whether the open mode is normal, lazy or incremental. By default, it is normal.

progress

Inherited from GC.Spread.Sheets.ProgressFunctionType Typedef, it is the progress callback function for each open mode.

The following code implementation shows how to perform the open file operation:

//This example uses the open method.
//Get file blob.
var file = document.getElementById("fileInput").files[0];
// import
spread.open(file, function () {
    // success callback to do something
}, function (e) {
    console.log(e); // error callback
}, {
    lazyLoad: true,
    includeFormulas: false,
    includeStyles: false
});

Save Files

You can save the SpreadJS files using the save method, which provides the following parameters:

  • successCallBack: This function gives a success callback when the SpreadJS file is completely saved and accepts Blob as argument.

  • errorCallBack: This function gives an error callback when saving the spreadJS file returns an error.

  • saveOptions: Inherited from the GC.Spread.Sheets.SaveOptions Typedef, it provides the save options.

    The different save options are given below:

Save Options

Description

includeBindingSource

Indicates whether the binding source can be included while saving the file. By default, the value is false.

includeStyles

Indicates whether the style can be included when saving files. By default, the value is true.

includeFormulas

Indicates whether the formula can be included when saving the file. By default, the value is true.

saveAsView

Indicates whether the saved file will ignore all the format strings of the current spread. By default, the value is false.

includeAutoMergedCells

Indicates whether automatically merged cells can be included when saving the file. By default, the value is false.

includeCalcModelCache

Indicates whether the extra data of calculation can be included when saving files. By default, the value is true.

includeUnusedNames

Indicates whether the unused custom name can be included when saving the file. By default, the value is true.

includeEmptyRegionCells

Indicates whether any empty cells can be included outside the used data range. By default, the value is true.

The following code implementation shows how to perform the save file operation:

var fileName = "fileNamehere.sjs";
spread.save(function (blob) {
    // save blob to a file
    saveAs(blob, fileName);
}, function (e) {
    console.log(e);
}, {
    includeUnusedNames: false,
    includeEmptyRegionCells: false
});

Export Files

You can export files to Excel, SSJSON, SJS or CSV formats in Spread.

The export method provides the following parameters:

  • successCallBack: This function gives a success callback when file export is complete and accepts Blob as argument.

  • errorCallBack: This function gives an error callback when exporting the file returns an error.

  • saveOptions: Inherited from the GC.Spread.Sheets.ExportOptions Typedef, it provides the export options.

The different export options are given below:

Options

Description

FileOptions

Inherited from GC.Spread.Sheets.FileType Typedef, FileOptions provides different file formats.

ExportCsvOptions

Inherited from GC.Spread.Sheets.ExportCsvOptions, the ExportCsvOptions provides options for exporting file to CSV format.

ExportSSJsonOptions

Inherited from GC.Spread.Sheets.ExportSSJsonOptions, the ExportSSJsonOptions provides options for exporting file to SSJSON format.

ExportXlsxOptions

Inherited from GC.Spread.Sheets.ExportXlsxOptions, the ExportXlsxOptions provides options for exporting file to Excel format.

The code implementation shows how to perform the export file operation:

var fileName = "fileNamehere.sjs";           
spread.export(function (blob) {
    // save blob to a file
    saveAs(blob, fileName);
}, function (e) {
    console.log(e);
}, {
    fileType: GC.Spread.Sheets.FileType.sjs,
    includeBindingSource: true
});

Import Files

You can also import files with Excel, SSJSON, SJS or CSV format in Spread.

The import method provides the following parameters:

  • file: The SSJSON, SJS or CSV or Excel file for import.

  • successCallBack: This function gives a success callback when file import is complete.

  • errorCallBack: This function gives an error callback when importing a file returns error.

  • importOptions: Inherited from the GC.Spread.Sheets.ImportOptions Typedef, it provides the import options.

The different import options are given below:

Options

Description

FileOptions

Inherited from GC.Spread.Sheets.FileType Typedef, FileOptions provides different file formats.

ImportCsvOptions

Inherited from GC.Spread.Sheets.ImportCsvOptions, the ImportCsvOptions provides options for Importing file from CSV format.

ImportSSJsonOptions

Inherited from GC.Spread.Sheets.ImportSSJsonOptions, the ImporSSJsonOptions provides options for Importing file from SSJSON format.

ImportXlsxOptions

Inherited from GC.Spread.Sheets.ImportXlsxOptions, the ImportXlsxOptions provides options for Importing file from Excel format.

The code implementation shows how to perform the import file operation:

//Get file blob.
var file = document.getElementById("fileInput").files[0];
// import
spread.import(file, function () {
    // success callback to do something
}, function (e) {
    console.log(e); // error callback
}, {
    fileType: GC.Spread.Sheets.FileType.excel
});