xlsx-populate

xlsx-populate operates by manipulating the underlying XML structure of an XLSX workbook rather than deserializing the entire file into a rich object model.

An XLSX workbook is a zip archive of XML files. The library uses JSZip to unzip the workbook and sax-js to parse the XML documents into objects. As you call methods, xlsx-populate manipulates these objects directly. When generating output, it uses xmlbuilder-js to convert the objects back to XML and JSZip to re-zip them.

Key Benefit: Because it manipulates the XML data directly instead of attempting to map the entire Office Open XML specification to a high-level model, it can preserve styles and other content that the library does not explicitly support, preventing data loss during the read/write cycle.

You can work with multiple cells at once using range(address).

• Set values: Use .value() with a single value, a 2D array, or a callback function (cell, ri, ci, range) => value.
• Bulk extraction: Use Sheet.usedRange().value() to get a 2D array of all values in a worksheet.
• Top-left shortcut: Setting a value on a single cell with a 2D array will populate the range starting from that cell.

// Get 2D array of all values in the worksheet.
const values = workbook.sheet("Sheet1").usedRange().value();

// Set values using a 2D array in a range:
r.value([
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
]);

To contribute to or develop xlsx-populate, ensure you have the following installed:

• Node.js: version 4 or higher (required for ES6 syntax).
• git: for version control.
• gulp: installed globally via npm.

Initial Setup Steps:

1. Install gulp globally:

   npm install -g gulp

2. Clone the repository and install dependencies:

   npm install

3. Run the default gulp task to watch files and run tests:

   gulp

4. To build the project for the browser:

   gulp build

There are several ways to include xlsx-populate in a browser project:

1. Bower: Install the package using bower. Once included, the module is available globally as XlsxPopulate.
2. Browserify: Require the module using browserify. Because the library uses ES6 features, you must use babelify with babel-preset-env to transpile the code for browser compatibility.
3. Manual Download: You can download the combined, minified code directly from the browser directory in the repository.

bower install xlsx-populate

Before submitting a pull request, ensure your code meets these requirements:

• Pattern: Follow the getter/setter pattern using a single function for both (distinguish via arguments.length or ArgHandler).
• Documentation: Use valid JSDoc on all methods and classes. Use @private for private methods and @ignore for internal public methods.
• Linting: Adhere to ESLint rules (run gulp lint).
• Syntax: Use ES6 syntax.
• Testing: Provide full Jasmine unit test coverage and ensure all tests pass.
• Stability: Do not modify or break existing API behavior (the project follows semantic versioning).
• Docs: If the feature requires more than JSDoc, update docs/template.md.

To use xlsx-populate in a Node.js environment, install it using npm. Note that xlsx-populate uses ES6 features, so you must use Node.js v4 or higher.

npm install xlsx-populate

To contribute to or develop for xlsx-populate, ensure you have the following installed:

1. Node.js: Version 4 or higher (required for ES6 syntax).
2. Git: For version control.
3. Gulp: Installed globally via npm.

Installation Steps

From the project root, install the necessary npm dependencies:

npm install

Running the Development Workflow

• Watch for changes: Run gulp to start the default task, which watches source files for updates and runs tests automatically. If you add new files, you must restart gulp to include them in the watch list.
• Build for the browser: To create the client-side JavaScript bundle, run:

gulp build

To use xlsx-populate in a Node.js environment, install it using npm. Note that xlsx-populate uses ES6 features, so you must use Node.js v4 or higher.

npm install xlsx-populate

To create a new Excel file, use XlsxPopulate.fromBlankAsync(). You can then access sheets and cells to set values and finally write the workbook to a file using workbook.toFileAsync().

const XlsxPopulate = require('xlsx-populate');

// Load a new blank workbook
XlsxPopulate.fromBlankAsync()
    .then(workbook => {
        // Modify the workbook.
        workbook.sheet("Sheet1").cell("A1").value("This is neat!");

        // Write to file.
        return workbook.toFileAsync("./out.xlsx");
    });