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.
saveR1C1Formula	Indicates whether to save the r1c1 formula in the file. By default, the value is false.

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
    saveR1C1Formula: true
});

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
});