From 703dc4571ae1d7a6d6fcd132d829854d8fbe993f Mon Sep 17 00:00:00 2001 From: Kuznetsov Aleksey Date: Thu, 5 Jul 2018 15:54:20 +0300 Subject: [PATCH 01/13] Added ability to set tooltip for hyperlink --- lib/Cell.js | 13 +++++++++++-- lib/Sheet.js | 13 ++++++++++++- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/lib/Cell.js b/lib/Cell.js index 26f92e2c..5f93e7fb 100644 --- a/lib/Cell.js +++ b/lib/Cell.js @@ -164,7 +164,8 @@ class Cell { * @returns {string|undefined} The hyperlink or undefined if not set. *//** * Set or clear the hyperlink on the cell. - * @param {string|undefined} hyperlink - The hyperlink to set or undefined to clear. + * @param {string|object|undefined} hyperlink - The hyperlink to set or undefined to clear. + * @param {string} [tooltip] - The tooltip to set for hyperlink. * @returns {Cell} The cell. */ hyperlink() { @@ -172,10 +173,18 @@ class Cell { .case(() => { return this.sheet().hyperlink(this.address()); }) - .case('*', hyperlink => { + .case(['string', 'string'], (hyperlink, tooltip) => { + this.sheet().hyperlink(this.address(), hyperlink, tooltip); + return this; + }) + .case('string', hyperlink => { this.sheet().hyperlink(this.address(), hyperlink); return this; }) + .case('object', obj => { + this.sheet().hyperlink(this.address(), obj.hyperlink, obj.tooltip); + return this; + }) .handle(arguments); } diff --git a/lib/Sheet.js b/lib/Sheet.js index c20733e8..648a7880 100644 --- a/lib/Sheet.js +++ b/lib/Sheet.js @@ -558,7 +558,8 @@ class Sheet { *//** * Set the hyperlink attached to the cell with the given address. * @param {string} address - The address to of the hyperlinked cell. - * @param {boolean} hyperlink - The hyperlink to set or undefined to clear. + * @param {string} hyperlink - The hyperlink to set or undefined to clear. + * @param {string} [tooltip] - The tooltip to set for hyperlink. * @returns {Sheet} The sheet. * @ignore */ @@ -584,6 +585,16 @@ class Sheet { return this; }) + .case(['string', 'string', 'string'], (address, hyperlink, tooltip) => { + const relationship = this._relationships.add("hyperlink", hyperlink, "External"); + this._hyperlinks[address] = { + name: 'hyperlink', + attributes: { ref: address, 'r:id': relationship.attributes.Id, tooltip }, + children: [] + }; + + return this; + }) .handle(arguments); } From a4a0dfabc8bc4dcb7016bd42cb39f5019d9f35a5 Mon Sep 17 00:00:00 2001 From: Kuznetsov Aleksey Date: Thu, 5 Jul 2018 16:05:22 +0300 Subject: [PATCH 02/13] Updated the example for hyperlink in README.md --- README.md | 2150 +++++++++++++++++++++++++++-------------------------- 1 file changed, 1082 insertions(+), 1068 deletions(-) diff --git a/README.md b/README.md index b3456322..16db7c25 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ -[![view on npm](http://img.shields.io/npm/v/xlsx-populate.svg)](https://www.npmjs.org/package/xlsx-populate) -[![npm module downloads per month](http://img.shields.io/npm/dm/xlsx-populate.svg)](https://www.npmjs.org/package/xlsx-populate) -[![Build Status](https://travis-ci.org/dtjohnson/xlsx-populate.svg?branch=master)](https://travis-ci.org/dtjohnson/xlsx-populate) -[![Dependency Status](https://david-dm.org/dtjohnson/xlsx-populate.svg)](https://david-dm.org/dtjohnson/xlsx-populate) - -# xlsx-populate -Excel XLSX parser/generator written in JavaScript with Node.js and browser support, jQuery/d3-style method chaining, encryption, and a focus on keeping existing workbook features and styles in tact. - -## Table of Contents +[![view on npm](http://img.shields.io/npm/v/xlsx-populate.svg)](https://www.npmjs.org/package/xlsx-populate) +[![npm module downloads per month](http://img.shields.io/npm/dm/xlsx-populate.svg)](https://www.npmjs.org/package/xlsx-populate) +[![Build Status](https://travis-ci.org/dtjohnson/xlsx-populate.svg?branch=master)](https://travis-ci.org/dtjohnson/xlsx-populate) +[![Dependency Status](https://david-dm.org/dtjohnson/xlsx-populate.svg)](https://david-dm.org/dtjohnson/xlsx-populate) + +# xlsx-populate +Excel XLSX parser/generator written in JavaScript with Node.js and browser support, jQuery/d3-style method chaining, encryption, and a focus on keeping existing workbook features and styles in tact. + +## Table of Contents - [Installation](#installation) * [Node.js](#nodejs) * [Browser](#browser) @@ -35,741 +35,751 @@ Excel XLSX parser/generator written in JavaScript with Node.js and browser suppo * [Pull Request Checklist](#pull-request-checklist) * [Gulp Tasks](#gulp-tasks) - [Style Reference](#style-reference) -- [API Reference](#api-reference) - -## Installation - -### Node.js -```bash -npm install xlsx-populate -``` -Note that xlsx-populate uses ES6 features so only Node.js v4+ is supported. - -### Browser - -A functional browser example can be found in [examples/browser/index.html](https://gitcdn.xyz/repo/dtjohnson/xlsx-populate/master/examples/browser/index.html). - -xlsx-populate is written first for Node.js. We use [browserify](http://browserify.org/) and [babelify](https://github.com/babel/babelify) to transpile and pack up the module for use in the browser. - -You have a number of options to include the code in the browser. You can download the combined, minified code from the browser directory in this repository or you can install with bower: -```bash -bower install xlsx-populate -``` -After including the module in the browser, it is available globally as `XlsxPopulate`. - -Alternatively, you can require this module using [browserify](http://browserify.org/). Since xlsx-populate uses ES6 features, you will also need to use [babelify](https://github.com/babel/babelify) with [babel-preset-env](https://www.npmjs.com/package/babel-preset-env). - -## Usage - -xlsx-populate has an [extensive API](#api-reference) for working with Excel workbooks. This section reviews the most common functions and use cases. Examples can also be found in the examples directory of the source code. - -### Populating Data - -To populate data in a workbook, you first load one (either blank, from data, or from file). Then you can access sheets and - cells within the workbook to manipulate them. -```js -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"); - }); -``` - -### Parsing Data - -You can pull data out of existing workbooks using [Cell.value](#Cell+value) as a getter without any arguments: -```js -const XlsxPopulate = require('xlsx-populate'); - -// Load an existing workbook -XlsxPopulate.fromFileAsync("./Book1.xlsx") - .then(workbook => { - // Modify the workbook. - const value = workbook.sheet("Sheet1").cell("A1").value(); - - // Log the value. - console.log(value); - }); -``` -__Note__: in cells that contain values calculated by formulas, Excel will store the calculated value in the workbook. The [value](#Cell+value) method will return the value of the cells at the time the workbook was saved. xlsx-populate will _not_ recalculate the values as you manipulate the workbook and will _not_ write the values to the output. - -### Ranges -xlsx-populate also supports ranges of cells to allow parsing/manipulation of multiple cells at once. -```js -const r = workbook.sheet(0).range("A1:C3"); - -// Set all cell values to the same value: -r.value(5); - -// Set the values using a 2D array: -r.value([ - [1, 2, 3], - [4, 5, 6], - [7, 8, 9] -]); - -// Set the values using a callback function: -r.value((cell, ri, ci, range) => Math.random()); -``` - -A common use case is to simply pull all of the values out all at once. You can easily do that with the [Sheet.usedRange](#Sheet+usedRange) method. -```js -// Get 2D array of all values in the worksheet. -const values = workbook.sheet("Sheet1").usedRange().value(); -``` - -Alternatively, you can set the values in a range with only the top-left cell in the range: -```js -workbook.sheet(0).cell("A1").value([ - [1, 2, 3], - [4, 5, 6], - [7, 8, 9] -]); -``` -The set range is returned. - -### Rows and Columns - -You can access rows and columns in order to change size, hide/show, or access cells within: -```js -// Get the B column, set its width and unhide it (assuming it was hidden). -sheet.column("B").width(25).hidden(false); - -const cell = sheet.row(5).cell(3); // Returns the cell at C5. -``` - -### Managing Sheets -xlsx-populate supports a number of options for managing sheets. - -You can get a sheet by name or index or get all of the sheets as an array: -```js -// Get sheet by index -const sheet1 = workbook.sheet(0); - -// Get sheet by name -const sheet2 = workbook.sheet("Sheet2"); - -// Get all sheets as an array -const sheets = workbook.sheets(); -``` - -You can add new sheets: -```js -// Add a new sheet named 'New 1' at the end of the workbook -const newSheet1 = workbook.addSheet('New 1'); - -// Add a new sheet named 'New 2' at index 1 (0-based) -const newSheet2 = workbook.addSheet('New 2', 1); - -// Add a new sheet named 'New 3' before the sheet named 'Sheet1' -const newSheet3 = workbook.addSheet('New 3', 'Sheet1'); - -// Add a new sheet named 'New 4' before the sheet named 'Sheet1' using a Sheet reference. -const sheet = workbook.sheet('Sheet1'); -const newSheet4 = workbook.addSheet('New 4', sheet); -``` -*Note: the sheet rename method does not rename references to the sheet so formulas, etc. can be broken. Use with caution!* - -You can rename sheets: -```js -// Rename the first sheet. -const sheet = workbook.sheet(0).name("new sheet name"); -``` - -You can move sheets: -```js -// Move 'Sheet1' to the end -workbook.moveSheet("Sheet1"); - -// Move 'Sheet1' to index 2 -workbook.moveSheet("Sheet1", 2); - -// Move 'Sheet1' before 'Sheet2' -workbook.moveSheet("Sheet1", "Sheet2"); -``` -The above methods can all use sheet references instead of names as well. And you can also move a sheet using a method on the sheet: -```js -// Move the sheet before 'Sheet2' -sheet.move("Sheet2"); -``` - -You can delete sheets: -```js -// Delete 'Sheet1' -workbook.deleteSheet("Sheet1"); - -// Delete sheet with index 2 -workbook.deleteSheet(2); - -// Delete from sheet reference -workbook.sheet(0).delete(); -``` - -You can get/set the active sheet: -```js -// Get the active sheet -const sheet = workbook.activeSheet(); - -// Check if the current sheet is active -sheet.active() // returns true or false - -// Activate the sheet -sheet.active(true); - -// Or from the workbook -workbook.activeSheet("Sheet2"); -``` - -### Defined Names -Excel supports creating defined names that refer to addresses, formulas, or constants. These defined names can be scoped -to the entire workbook or just individual sheets. xlsx-populate supports looking up defined names that refer to cells or -ranges. (Dereferencing other names will result in an error.) Defined names are particularly useful if you are populating -data into a known template. Then you do need to know the exact location. - -```js -// Look up workbook-scoped name and set the value to 5. -workbook.definedName("some name").value(5); - -// Look of a name scoped to the first sheet and set the value to "foo". -workbook.sheet(0).definedName("some other name").value("foo"); -``` - -You can also create, modify, or delete defined names: -```js -// Create/modify a workbook-scope defined name -workbook.definedName("some name", "TRUE"); - -// Delete a sheet-scoped defined name: -workbook.sheet(0).definedName("some name", null); -``` - -### Find and Replace -You can search for occurrences of text in cells within the workbook or sheets and optionally replace them. -```js -// Find all occurrences of the text "foo" in the workbook and replace with "bar". -workbook.find("foo", "bar"); // Returns array of matched cells - -// Find the matches but don't replace. -workbook.find("foo"); - -// Just look in the first sheet. -workbook.sheet(0).find("foo"); - -// Check if a particular cell matches the value. -workbook.sheet("Sheet1").cell("A1").find("foo"); // Returns true or false -``` - -Like [String.replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace), the find method can also take a RegExp search pattern and replace can take a function callback: -```js -// Use a RegExp to replace all lowercase letters with uppercase -workbook.find(/[a-z]+/g, match => match.toUpperCase()); -``` - -### Styles -xlsx-populate supports a wide range of cell formatting. See the [Style Reference](#style-reference) for the various options. - -To set/set a cell style: -```js -// Set a single style -cell.style("bold", true); - -// Set multiple styles -cell.style({ bold: true, italic: true }); - -// Get a single style -const bold = cell.style("bold"); // true - -// Get multiple styles -const styles = cell.style(["bold", "italic"]); // { bold: true, italic: true } -``` - -Similarly for ranges: -```js -// Set all cells in range with a single style -range.style("bold", true); - -// Set with a 2D array -range.style("bold", [[true, false], [false, true]]); - -// Set with a callback function -range.style("bold", (cell, ri, ci, range) => Math.random() > 0.5); - -// Set multiple styles using any combination -range.style({ - bold: true, - italic: [[true, false], [false, true]], - underline: (cell, ri, ci, range) => Math.random() > 0.5 -}); -``` - -If you are setting styles for many cells, performance is far better if you set for an entire row or column: -```js -// Set a single style -sheet.row(1).style("bold", true); - -// Set multiple styles -sheet.column("A").style({ bold: true, italic: true }); - -// Get a single style -const bold = sheet.column(3).style("bold"); - -// Get multiple styles -const styles = sheet.row(5).style(["bold", "italic"]); -``` -Note that the row/column style behavior mirrors Excel. Setting a style on a column will apply that style to all existing cells and any new cells that are populated. Getting the row/column style will return only the styles that have been applied to the entire row/column, not the styles of every cell in the row or column. - -Some styles take values that are more complex objects: -```js -cell.style("fill", { - type: "pattern", - pattern: "darkDown", - foreground: { - rgb: "ff0000" - }, - background: { - theme: 3, - tint: 0.4 - } -}); -``` - -There are often shortcuts for the setters, but the getters will always return the full objects: -```js -cell.style("fill", "0000ff"); - -const fill = cell.style("fill"); -/* -fill is now set to: -{ - type: "solid", - color: { - rgb: "0000ff" - } -} -*/ -``` - -Number formats are one of the most common styles. They can be set using the `numberFormat` style. -```js -cell.style("numberFormat", "0.00"); -``` - -Information on how number format codes work can be found [here](https://support.office.com/en-us/article/Number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68?ui=en-US&rs=en-US&ad=US). -You can also look up the desired format code in Excel: -* Right-click on a cell in Excel with the number format you want. -* Click on "Format Cells..." -* Switch the category to "Custom" if it is not already. -* The code in the "Type" box is the format you should copy. - -### Dates - -Excel stores date/times as the number of days since 1/1/1900 ([sort of](https://en.wikipedia.org/wiki/Leap_year_bug)). It just applies a number formatting to make the number appear as a date. So to set a date value, you will need to also set a number format for a date if one doesn't already exist in the cell: -```js -cell.value(new Date(2017, 1, 22)).style("numberFormat", "dddd, mmmm dd, yyyy"); -``` -When fetching the value of the cell, it will be returned as a number. To convert it to a date use [XlsxPopulate.numberToDate](#XlsxPopulate.numberToDate): -```js -const num = cell.value(); // 42788 -const date = XlsxPopulate.numberToDate(num); // Wed Feb 22 2017 00:00:00 GMT-0500 (Eastern Standard Time) -``` - -### Data Validation -Data validation is also supported. To set/get/remove a cell data validation: -```js -// Set the data validation -cell.dataValidation({ - type: 'list', - allowBlank: false, - showInputMessage: false, - prompt: false, - promptTitle: 'String', - showErrorMessage: false, - error: 'String', - errorTitle: 'String', - operator: 'String', - formula1: '$A:$A',//Required - formula2: 'String' -}); - -//Here is a short version of the one above. -cell.dataValidation('$A:$A'); - -// Get the data validation -const obj = cell.dataValidation(); // Returns an object - -// Remove the data validation -cell.dataValidation(null); //Returns the cell -``` - -Similarly for ranges: -```js - -// Set all cells in range with a single shared data validation -range.dataValidation({ - type: 'list', - allowBlank: false, - showInputMessage: false, - prompt: false, - promptTitle: 'String', - showErrorMessage: false, - error: 'String', - errorTitle: 'String', - operator: 'String', - formula1: 'Item1,Item2,Item3,Item4',//Required - formula2: 'String' -}); - -//Here is a short version of the one above. -range.dataValidation('Item1,Item2,Item3,Item4'); - -// Get the data validation -const obj = range.dataValidation(); // Returns an object - -// Remove the data validation -range.dataValidation(null); //Returns the Range -``` -Please note, the data validation gets applied to the entire range, *not* each Cell in the range. - -### Method Chaining - -xlsx-populate uses method-chaining similar to that found in [jQuery](https://jquery.com/) and [d3](https://d3js.org/). This lets you construct large chains of setters as desired: -```js -workbook - .sheet(0) - .cell("A1") - .value("foo") - .style("bold", true) - .relativeCell(1, 0) - .formula("A1") - .style("italic", true) -.workbook() - .sheet(1) - .range("A1:B3") - .value(5) - .cell(0, 0) - .style("underline", "double"); - -``` - -### Hyperlinks -Hyperlinks are also supported on cells using the [Cell.hyperlink](#Cell+hyperlink) method. The method will _not_ style the content to look like a hyperlink. You must do that yourself: -```js -// Set a hyperlink -cell.value("Link Text") - .style({ fontColor: "0563c1", underline: true }) - .hyperlink("http://example.com"); - -// Get the hyperlink -const value = cell.hyperlink(); // Returns 'http://example.com' -``` - -### Serving from Express -You can serve the workbook from [express](http://expressjs.com/) or other web servers with something like this: -```js -router.get("/download", function (req, res, next) { - // Open the workbook. - XlsxPopulate.fromFileAsync("input.xlsx") - .then(workbook => { - // Make edits. - workbook.sheet(0).cell("A1").value("foo"); - - // Get the output - return workbook.outputAsync(); - }) - .then(data => { - // Set the output file name. - res.attachment("output.xlsx"); - - // Send the workbook. - res.send(data); - }) - .catch(next); -}); -``` - -### Browser Usage -Usage in the browser is almost the same. A functional example can be found in [examples/browser/index.html](https://gitcdn.xyz/repo/dtjohnson/xlsx-populate/master/examples/browser/index.html). The library is exposed globally as `XlsxPopulate`. Existing workbooks can be loaded from a file: -```js -// Assuming there is a file input in the page with the id 'file-input' -var file = document.getElementById("file-input").files[0]; - -// A File object is a special kind of blob. -XlsxPopulate.fromDataAsync(file) - .then(function (workbook) { - // ... - }); -``` - -You can also load from AJAX if you set the responseType to 'arraybuffer': -```js -var req = new XMLHttpRequest(); -req.open("GET", "http://...", true); -req.responseType = "arraybuffer"; -req.onreadystatechange = function () { - if (req.readyState === 4 && req.status === 200){ - XlsxPopulate.fromDataAsync(req.response) - .then(function (workbook) { - // ... - }); - } -}; - -req.send(); -``` - -To download the workbook, you can either export as a blob (default behavior) or as a base64 string. You can then insert a link into the DOM and click it: -```js -workbook.outputAsync() - .then(function (blob) { - if (window.navigator && window.navigator.msSaveOrOpenBlob) { - // If IE, you must uses a different method. - window.navigator.msSaveOrOpenBlob(blob, "out.xlsx"); - } else { - var url = window.URL.createObjectURL(blob); - var a = document.createElement("a"); - document.body.appendChild(a); - a.href = url; - a.download = "out.xlsx"; - a.click(); - window.URL.revokeObjectURL(url); - document.body.removeChild(a); - } - }); -``` - -Alternatively, you can download via a data URI, but this is not supported by IE: -```js -workbook.outputAsync("base64") - .then(function (base64) { - location.href = "data:" + XlsxPopulate.MIME_TYPE + ";base64," + base64; - }); -``` - -### Promises -xlsx-populate uses [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to manage async input/output. By default it uses the `Promise` defined in the browser or Node.js. In browsers that don't support promises (IE) a [polyfill is used via JSZip](https://stuk.github.io/jszip/documentation/api_jszip/external.html). -```js -// Get the current promise library in use. -// Helpful for getting a usable Promise library in IE. -var Promise = XlsxPopulate.Promise; -``` - -If you prefer, you can override the default `Promise` library used with another ES6 compliant library like [bluebird](http://bluebirdjs.com/). -```js -const Promise = require("bluebird"); -const XlsxPopulate = require("xlsx-populate"); -XlsxPopulate.Promise = Promise; -``` - -### Encryption -XLSX Agile encryption and descryption are supported so you can read and write password-protected workbooks. To read a protected workbook, pass the password in as an option: -```js -XlsxPopulate.fromFileAsync("./Book1.xlsx", { password: "S3cret!" }) - .then(workbook => { - // ... - }); -``` - -Similarly, to write a password encrypted workbook: -```js -workbook.toFileAsync("./out.xlsx", { password: "S3cret!" }); -``` -The password option is supported in all output methods. N.B. Workbooks will only be encrypted if you supply a password when outputting even if they had a password when reading. - -Encryption support is also available in the browser, but take care! Any password you put in browser code can be read by anyone with access to your code. You should only use passwords that are supplied by the end-user. Also, the performance of encryption/decryption in the browser is far worse than with Node.js. IE, in particular, is extremely slow. xlsx-populate is bundled for browsers with and without encryption support as the encryption libraries increase the size of the bundle a lot. - -## Missing Features -There are many, many features of the XLSX format that are not yet supported. If your use case needs something that isn't supported -please open an issue to show your support. Better still, feel free to [contribute](#contributing) a pull request! - -## Submitting an Issue -If you happen to run into a bug or an issue, please feel free to [submit an issue](https://github.com/dtjohnson/xlsx-populate/issues). I only ask that you please include sample JavaScript code that demonstrates the issue. -If the problem lies with modifying some template, it is incredibly difficult to debug the issue without the template. So please attach the template if possible. If you have confidentiality concerns, please attach a different workbook that exhibits the issue or you can send your workbook directly to [dtjohnson](https://github.com/dtjohnson) after creating the issue. - -## Contributing - -Pull requests are very much welcome! If you'd like to contribute, please make sure to read this section carefully first. - -### How xlsx-populate Works -An XLSX workbook is essentially a zip of a bunch of XML files. xlsx-populate uses [JSZip](https://stuk.github.io/jszip/) -to unzip the workbook and [sax-js](https://github.com/isaacs/sax-js) to parse the XML documents into corresponding objects. -As you call methods, xlsx-populate manipulates the content of those objects. When you generate the output, xlsx-populate -uses [xmlbuilder-js](https://github.com/oozcitak/xmlbuilder-js) to convert the objects back to XML and then uses JSZip to -rezip them back into a workbook. - -The way in which xlsx-populate manipulates objects that are essentially the XML data is very different from the usual way -parser/generator libraries work. Most other libraries will deserialize the XML into a rich object model. That model is then -manipulated and serialized back into XML upon generation. The challenge with this approach is that the Office Open XML spec is [HUGE](http://www.ecma-international.org/publications/standards/Ecma-376.htm). -It is extremely difficult for libraries to be able to support the entire specification. So these other libraries will deserialize -only the portion of the spec they support and any other content/styles in the workbook they don't support are lost. Since -xlsx-populate just manipulates the XML data, it is able to preserve styles and other content while still only supporting -a fraction of the spec. - -### Setting up your Environment -You'll need to make sure [Node.js](https://nodejs.org/en/) v4+ is installed (as xlsx-populate uses ES6 syntax). You'll also -need to install [gulp](https://github.com/gulpjs/gulp): -```bash -npm install -g gulp -``` - -Make sure you have [git](https://git-scm.com/) installed. Then follow [this guide](https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) to see how to check out code, branch, and -then submit your code as a pull request. When you check out the code, you'll first need to install the npm dependencies. -From the project root, run: -```bash -npm install -``` - -The default gulp task is set up to watch the source files for updates and retest while you edit. From the project root just run: -```bash -gulp -``` - -You should see the test output in your console window. As you edit files the tests will run again and show you if you've -broken anything. (Note that if you've added new files you'll need to restart gulp for the new files to be watched.) - -Now write your code and make sure to add [Jasmine](https://jasmine.github.io/) unit tests. When you are finished, you need -to build the code for the browser. Do that by running the gulp build command: -```bash -gulp build -``` - -Verify all is working, check in your code, and submit a pull request. - -### Pull Request Checklist -To make sure your code is consistent and high quality, please make sure to follow this checklist before submitting a pull request: - * Your code must follow the getter/setter pattern using a single function for both. Check `arguments.length` or use `ArgHandler` to distinguish. - * You must use valid [JSDoc](http://usejsdoc.org/) comments on *all* methods and classes. Use `@private` for private methods and `@ignore` for any public methods that are internal to xlsx-populate and should not be included in the public API docs. - * You must adhere to the configured [ESLint](http://eslint.org/) linting rules. You can configure your IDE to display rule violations live or you can run `gulp lint` to see them. - * Use [ES6](http://es6-features.org/#Constants) syntax. (This should be enforced by ESLint.) - * Make sure to have full [Jasmine](https://jasmine.github.io/) unit test coverage for your code. - * Make sure all tests pass successfully. - * Whenever possible, do not modify/break existing API behavior. This module adheres to the [semantic versioning standard](https://docs.npmjs.com/getting-started/semantic-versioning). So any breaking changes will require a major release. - * If your feature needs more documentation than just the JSDoc output, please add to the docs/template.md README file. - - -### Gulp Tasks - -xlsx-populate uses [gulp](https://github.com/gulpjs/gulp) as a build tool. There are a number of tasks: - -* __browser__ - Transpile and build client-side JavaScript project bundle using [browserify](http://browserify.org/) and [babelify](https://github.com/babel/babelify). -* __lint__ - Check project source code style using [ESLint](http://eslint.org/). -* __unit__ - Run [Jasmine](https://jasmine.github.io/) unit tests. -* __unit-browser__ - Run the unit tests in real browsers using [Karma](https://karma-runner.github.io/1.0/index.html). -* __e2e-parse__ - End-to-end tests of parsing data out of sample workbooks that were created in Microsoft Excel. -* __e2e-generate__ - End-to-end tests of generating workbooks using xlsx-populate. To verify the workbooks were truly generated correctly they need to be opened in Microsoft Excel and verified. This task automates this verification using the .NET Excel Interop library with [Edge.js](https://github.com/tjanczuk/edge) acting as a bridge between Node.js and C#. Note that these tests will _only_ run on Windows with Microsoft Excel and the [Primary Interop Assemblies installed](https://msdn.microsoft.com/en-us/library/kh3965hw.aspx). -* __e2e-browser__ - End-to-end tests of usage of the browserify bundle in real browsers using Karma. -* __blank__ - Convert a blank XLSX template into a JS buffer module to support [fromBlankAsync](#XlsxPopulate.fromBlankAsync). -* __docs__ - Build this README doc by combining docs/template.md, API docs generated with [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown), and a table of contents generated with [markdown-toc](https://github.com/jonschlinkert/markdown-toc). -* __watch__ - Watch files for changes and then run associated gulp task. (Used by the default task.) -* __build__ - Run all gulp tasks, including linting and tests, and build the docs and browser bundle. -* __default__ - Run blank, unit, and docs tasks and watch the source files for those tasks for changes. - -## Style Reference - -### Styles -|Style Name|Type|Description| -| ------------- | ------------- | ----- | -|bold|`boolean`|`true` for bold, `false` for not bold| -|italic|`boolean`|`true` for italic, `false` for not italic| -|underline|`boolean|string`|`true` for single underline, `false` for no underline, `'double'` for double-underline| -|strikethrough|`boolean`|`true` for strikethrough `false` for not strikethrough| -|subscript|`boolean`|`true` for subscript, `false` for not subscript (cannot be combined with superscript)| -|superscript|`boolean`|`true` for superscript, `false` for not superscript (cannot be combined with subscript)| -|fontSize|`number`|Font size in points. Must be greater than 0.| -|fontFamily|`string`|Name of font family.| -|fontColor|`Color|string|number`|Color of the font. If string, will set an RGB color. If number, will set a theme color.| -|horizontalAlignment|`string`|Horizontal alignment. Allowed values: `'left'`, `'center'`, `'right'`, `'fill'`, `'justify'`, `'centerContinuous'`, `'distributed'`| -|justifyLastLine|`boolean`|a.k.a Justified Distributed. Only applies when horizontalAlignment === `'distributed'`. A boolean value indicating if the cells justified or distributed alignment should be used on the last line of text. (This is typical for East Asian alignments but not typical in other contexts.)| -|indent|`number`|Number of indents. Must be greater than or equal to 0.| -|verticalAlignment|`string`|Vertical alignment. Allowed values: `'top'`, `'center'`, `'bottom'`, `'justify'`, `'distributed'`| -|wrapText|`boolean`|`true` to wrap the text in the cell, `false` to not wrap.| -|shrinkToFit|`boolean`|`true` to shrink the text in the cell to fit, `false` to not shrink.| -|textDirection|`string`|Direction of the text. Allowed values: `'left-to-right'`, `'right-to-left'`| -|textRotation|`number`|Counter-clockwise angle of rotation in degrees. Must be [-90, 90] where negative numbers indicate clockwise rotation.| -|angleTextCounterclockwise|`boolean`|Shortcut for textRotation of 45 degrees.| -|angleTextClockwise|`boolean`|Shortcut for textRotation of -45 degrees.| -|rotateTextUp|`boolean`|Shortcut for textRotation of 90 degrees.| -|rotateTextDown|`boolean`|Shortcut for textRotation of -90 degrees.| -|verticalText|`boolean`|Special rotation that shows text vertical but individual letters are oriented normally. `true` to rotate, `false` to not rotate.| -|fill|`SolidFill|PatternFill|GradientFill|Color|string|number`|The cell fill. If Color, will set a solid fill with the color. If string, will set a solid RGB fill. If number, will set a solid theme color fill.| -|border|`Borders|Border|string|boolean}`|The border settings. If string, will set outside borders to given border style. If true, will set outside border style to `'thin'`.| -|borderColor|`Color|string|number`|Color of the borders. If string, will set an RGB color. If number, will set a theme color.| -|borderStyle|`string`|Style of the outside borders. Allowed values: `'hair'`, `'dotted'`, `'dashDotDot'`, `'dashed'`, `'mediumDashDotDot'`, `'thin'`, `'slantDashDot'`, `'mediumDashDot'`, `'mediumDashed'`, `'medium'`, `'thick'`, `'double'`| -|leftBorder, rightBorder, topBorder, bottomBorder, diagonalBorder|`Border|string|boolean`|The border settings for the given side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| -|leftBorderColor, rightBorderColor, topBorderColor, bottomBorderColor, diagonalBorderColor|`Color|string|number`|Color of the given border. If string, will set an RGB color. If number, will set a theme color.| -|leftBorderStyle, rightBorderStyle, topBorderStyle, bottomBorderStyle, diagonalBorderStyle|`string`|Style of the given side.| -|diagonalBorderDirection|`string`|Direction of the diagonal border(s) from left to right. Allowed values: `'up'`, `'down'`, `'both'`| -|numberFormat|`string`|Number format code. See docs [here](https://support.office.com/en-us/article/Number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68?ui=en-US&rs=en-US&ad=US).| - -### Color -An object representing a color. - -|Property|Type|Description| -| ------------- | ------------- | ----- | -|[rgb]|`string`|RGB color code (e.g. `'ff0000'`). Either rgb or theme is required.| -|[theme]|`number`|Index of a theme color. Either rgb or theme is required.| -|[tint]|`number`|Optional tint value of the color from -1 to 1. Particularly useful for theme colors. 0.0 means no tint, -1.0 means 100% darken, and 1.0 means 100% lighten.| - -### Borders -An object representing all of the borders. - -|Property|Type|Description| -| ------------- | ------------- | ----- | -|[left]|`Border|string|boolean`|The border settings for the left side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| -|[right]|`Border|string|boolean`|The border settings for the right side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| -|[top]|`Border|string|boolean`|The border settings for the top side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| -|[bottom]|`Border|string|boolean`|The border settings for the bottom side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| -|[diagonal]|`Border|string|boolean`|The border settings for the diagonal side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| - -### Border -An object representing an individual border. - -|Property|Type|Description| -| ------------- | ------------- | ----- | -|style|`string`|Style of the given border.| -|color|`Color|string|number`|Color of the given border. If string, will set an RGB color. If number, will set a theme color.| -|[direction]|`string`|For diagonal border, the direction of the border(s) from left to right. Allowed values: `'up'`, `'down'`, `'both'`| - -### SolidFill -An object representing a solid fill. - -|Property|Type|Description| -| ------------- | ------------- | ----- | -|type|`'solid'`|| -|color|`Color|string|number`|Color of the fill. If string, will set an RGB color. If number, will set a theme color.| - -### PatternFill -An object representing a pattern fill. - -|Property|Type|Description| -| ------------- | ------------- | ----- | -|type|`'pattern'`|| -|pattern|`string`|Name of the pattern. Allowed values: `'gray125'`, `'darkGray'`, `'mediumGray'`, `'lightGray'`, `'gray0625'`, `'darkHorizontal'`, `'darkVertical'`, `'darkDown'`, `'darkUp'`, `'darkGrid'`, `'darkTrellis'`, `'lightHorizontal'`, `'lightVertical'`, `'lightDown'`, `'lightUp'`, `'lightGrid'`, `'lightTrellis'`.| -|foreground|`Color|string|number`|Color of the foreground. If string, will set an RGB color. If number, will set a theme color.| -|background|`Color|string|number`|Color of the background. If string, will set an RGB color. If number, will set a theme color.| - -### GradientFill -An object representing a gradient fill. - -|Property|Type|Description| -| ------------- | ------------- | ----- | -|type|`'gradient'`|| -|[gradientType]|`string`|Type of gradient. Allowed values: `'linear'` (default), `'path'`. With a path gradient, a path is drawn between the top, left, right, and bottom values and a graident is draw from that path to the outside of the cell.| -|stops|`Array.<{}>`|| -|stops[].position|`number`|The position of the stop from 0 to 1.| -|stops[].color|`Color|string|number`|Color of the stop. If string, will set an RGB color. If number, will set a theme color.| -|[angle]|`number`|If linear gradient, the angle of clockwise rotation of the gradient.| -|[left]|`number`|If path gradient, the left position of the path as a percentage from 0 to 1.| -|[right]|`number`|If path gradient, the right position of the path as a percentage from 0 to 1.| -|[top]|`number`|If path gradient, the top position of the path as a percentage from 0 to 1.| -|[bottom]|`number`|If path gradient, the bottom position of the path as a percentage from 0 to 1.| - -## API Reference +- [API Reference](#api-reference) + +## Installation + +### Node.js +```bash +npm install xlsx-populate +``` +Note that xlsx-populate uses ES6 features so only Node.js v4+ is supported. + +### Browser + +A functional browser example can be found in [examples/browser/index.html](https://gitcdn.xyz/repo/dtjohnson/xlsx-populate/master/examples/browser/index.html). + +xlsx-populate is written first for Node.js. We use [browserify](http://browserify.org/) and [babelify](https://github.com/babel/babelify) to transpile and pack up the module for use in the browser. + +You have a number of options to include the code in the browser. You can download the combined, minified code from the browser directory in this repository or you can install with bower: +```bash +bower install xlsx-populate +``` +After including the module in the browser, it is available globally as `XlsxPopulate`. + +Alternatively, you can require this module using [browserify](http://browserify.org/). Since xlsx-populate uses ES6 features, you will also need to use [babelify](https://github.com/babel/babelify) with [babel-preset-env](https://www.npmjs.com/package/babel-preset-env). + +## Usage + +xlsx-populate has an [extensive API](#api-reference) for working with Excel workbooks. This section reviews the most common functions and use cases. Examples can also be found in the examples directory of the source code. + +### Populating Data + +To populate data in a workbook, you first load one (either blank, from data, or from file). Then you can access sheets and + cells within the workbook to manipulate them. +```js +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"); + }); +``` + +### Parsing Data + +You can pull data out of existing workbooks using [Cell.value](#Cell+value) as a getter without any arguments: +```js +const XlsxPopulate = require('xlsx-populate'); + +// Load an existing workbook +XlsxPopulate.fromFileAsync("./Book1.xlsx") + .then(workbook => { + // Modify the workbook. + const value = workbook.sheet("Sheet1").cell("A1").value(); + + // Log the value. + console.log(value); + }); +``` +__Note__: in cells that contain values calculated by formulas, Excel will store the calculated value in the workbook. The [value](#Cell+value) method will return the value of the cells at the time the workbook was saved. xlsx-populate will _not_ recalculate the values as you manipulate the workbook and will _not_ write the values to the output. + +### Ranges +xlsx-populate also supports ranges of cells to allow parsing/manipulation of multiple cells at once. +```js +const r = workbook.sheet(0).range("A1:C3"); + +// Set all cell values to the same value: +r.value(5); + +// Set the values using a 2D array: +r.value([ + [1, 2, 3], + [4, 5, 6], + [7, 8, 9] +]); + +// Set the values using a callback function: +r.value((cell, ri, ci, range) => Math.random()); +``` + +A common use case is to simply pull all of the values out all at once. You can easily do that with the [Sheet.usedRange](#Sheet+usedRange) method. +```js +// Get 2D array of all values in the worksheet. +const values = workbook.sheet("Sheet1").usedRange().value(); +``` + +Alternatively, you can set the values in a range with only the top-left cell in the range: +```js +workbook.sheet(0).cell("A1").value([ + [1, 2, 3], + [4, 5, 6], + [7, 8, 9] +]); +``` +The set range is returned. + +### Rows and Columns + +You can access rows and columns in order to change size, hide/show, or access cells within: +```js +// Get the B column, set its width and unhide it (assuming it was hidden). +sheet.column("B").width(25).hidden(false); + +const cell = sheet.row(5).cell(3); // Returns the cell at C5. +``` + +### Managing Sheets +xlsx-populate supports a number of options for managing sheets. + +You can get a sheet by name or index or get all of the sheets as an array: +```js +// Get sheet by index +const sheet1 = workbook.sheet(0); + +// Get sheet by name +const sheet2 = workbook.sheet("Sheet2"); + +// Get all sheets as an array +const sheets = workbook.sheets(); +``` + +You can add new sheets: +```js +// Add a new sheet named 'New 1' at the end of the workbook +const newSheet1 = workbook.addSheet('New 1'); + +// Add a new sheet named 'New 2' at index 1 (0-based) +const newSheet2 = workbook.addSheet('New 2', 1); + +// Add a new sheet named 'New 3' before the sheet named 'Sheet1' +const newSheet3 = workbook.addSheet('New 3', 'Sheet1'); + +// Add a new sheet named 'New 4' before the sheet named 'Sheet1' using a Sheet reference. +const sheet = workbook.sheet('Sheet1'); +const newSheet4 = workbook.addSheet('New 4', sheet); +``` +*Note: the sheet rename method does not rename references to the sheet so formulas, etc. can be broken. Use with caution!* + +You can rename sheets: +```js +// Rename the first sheet. +const sheet = workbook.sheet(0).name("new sheet name"); +``` + +You can move sheets: +```js +// Move 'Sheet1' to the end +workbook.moveSheet("Sheet1"); + +// Move 'Sheet1' to index 2 +workbook.moveSheet("Sheet1", 2); + +// Move 'Sheet1' before 'Sheet2' +workbook.moveSheet("Sheet1", "Sheet2"); +``` +The above methods can all use sheet references instead of names as well. And you can also move a sheet using a method on the sheet: +```js +// Move the sheet before 'Sheet2' +sheet.move("Sheet2"); +``` + +You can delete sheets: +```js +// Delete 'Sheet1' +workbook.deleteSheet("Sheet1"); + +// Delete sheet with index 2 +workbook.deleteSheet(2); + +// Delete from sheet reference +workbook.sheet(0).delete(); +``` + +You can get/set the active sheet: +```js +// Get the active sheet +const sheet = workbook.activeSheet(); + +// Check if the current sheet is active +sheet.active() // returns true or false + +// Activate the sheet +sheet.active(true); + +// Or from the workbook +workbook.activeSheet("Sheet2"); +``` + +### Defined Names +Excel supports creating defined names that refer to addresses, formulas, or constants. These defined names can be scoped +to the entire workbook or just individual sheets. xlsx-populate supports looking up defined names that refer to cells or +ranges. (Dereferencing other names will result in an error.) Defined names are particularly useful if you are populating +data into a known template. Then you do need to know the exact location. + +```js +// Look up workbook-scoped name and set the value to 5. +workbook.definedName("some name").value(5); + +// Look of a name scoped to the first sheet and set the value to "foo". +workbook.sheet(0).definedName("some other name").value("foo"); +``` + +You can also create, modify, or delete defined names: +```js +// Create/modify a workbook-scope defined name +workbook.definedName("some name", "TRUE"); + +// Delete a sheet-scoped defined name: +workbook.sheet(0).definedName("some name", null); +``` + +### Find and Replace +You can search for occurrences of text in cells within the workbook or sheets and optionally replace them. +```js +// Find all occurrences of the text "foo" in the workbook and replace with "bar". +workbook.find("foo", "bar"); // Returns array of matched cells + +// Find the matches but don't replace. +workbook.find("foo"); + +// Just look in the first sheet. +workbook.sheet(0).find("foo"); + +// Check if a particular cell matches the value. +workbook.sheet("Sheet1").cell("A1").find("foo"); // Returns true or false +``` + +Like [String.replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace), the find method can also take a RegExp search pattern and replace can take a function callback: +```js +// Use a RegExp to replace all lowercase letters with uppercase +workbook.find(/[a-z]+/g, match => match.toUpperCase()); +``` + +### Styles +xlsx-populate supports a wide range of cell formatting. See the [Style Reference](#style-reference) for the various options. + +To set/set a cell style: +```js +// Set a single style +cell.style("bold", true); + +// Set multiple styles +cell.style({ bold: true, italic: true }); + +// Get a single style +const bold = cell.style("bold"); // true + +// Get multiple styles +const styles = cell.style(["bold", "italic"]); // { bold: true, italic: true } +``` + +Similarly for ranges: +```js +// Set all cells in range with a single style +range.style("bold", true); + +// Set with a 2D array +range.style("bold", [[true, false], [false, true]]); + +// Set with a callback function +range.style("bold", (cell, ri, ci, range) => Math.random() > 0.5); + +// Set multiple styles using any combination +range.style({ + bold: true, + italic: [[true, false], [false, true]], + underline: (cell, ri, ci, range) => Math.random() > 0.5 +}); +``` + +If you are setting styles for many cells, performance is far better if you set for an entire row or column: +```js +// Set a single style +sheet.row(1).style("bold", true); + +// Set multiple styles +sheet.column("A").style({ bold: true, italic: true }); + +// Get a single style +const bold = sheet.column(3).style("bold"); + +// Get multiple styles +const styles = sheet.row(5).style(["bold", "italic"]); +``` +Note that the row/column style behavior mirrors Excel. Setting a style on a column will apply that style to all existing cells and any new cells that are populated. Getting the row/column style will return only the styles that have been applied to the entire row/column, not the styles of every cell in the row or column. + +Some styles take values that are more complex objects: +```js +cell.style("fill", { + type: "pattern", + pattern: "darkDown", + foreground: { + rgb: "ff0000" + }, + background: { + theme: 3, + tint: 0.4 + } +}); +``` + +There are often shortcuts for the setters, but the getters will always return the full objects: +```js +cell.style("fill", "0000ff"); + +const fill = cell.style("fill"); +/* +fill is now set to: +{ + type: "solid", + color: { + rgb: "0000ff" + } +} +*/ +``` + +Number formats are one of the most common styles. They can be set using the `numberFormat` style. +```js +cell.style("numberFormat", "0.00"); +``` + +Information on how number format codes work can be found [here](https://support.office.com/en-us/article/Number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68?ui=en-US&rs=en-US&ad=US). +You can also look up the desired format code in Excel: +* Right-click on a cell in Excel with the number format you want. +* Click on "Format Cells..." +* Switch the category to "Custom" if it is not already. +* The code in the "Type" box is the format you should copy. + +### Dates + +Excel stores date/times as the number of days since 1/1/1900 ([sort of](https://en.wikipedia.org/wiki/Leap_year_bug)). It just applies a number formatting to make the number appear as a date. So to set a date value, you will need to also set a number format for a date if one doesn't already exist in the cell: +```js +cell.value(new Date(2017, 1, 22)).style("numberFormat", "dddd, mmmm dd, yyyy"); +``` +When fetching the value of the cell, it will be returned as a number. To convert it to a date use [XlsxPopulate.numberToDate](#XlsxPopulate.numberToDate): +```js +const num = cell.value(); // 42788 +const date = XlsxPopulate.numberToDate(num); // Wed Feb 22 2017 00:00:00 GMT-0500 (Eastern Standard Time) +``` + +### Data Validation +Data validation is also supported. To set/get/remove a cell data validation: +```js +// Set the data validation +cell.dataValidation({ + type: 'list', + allowBlank: false, + showInputMessage: false, + prompt: false, + promptTitle: 'String', + showErrorMessage: false, + error: 'String', + errorTitle: 'String', + operator: 'String', + formula1: '$A:$A',//Required + formula2: 'String' +}); + +//Here is a short version of the one above. +cell.dataValidation('$A:$A'); + +// Get the data validation +const obj = cell.dataValidation(); // Returns an object + +// Remove the data validation +cell.dataValidation(null); //Returns the cell +``` + +Similarly for ranges: +```js + +// Set all cells in range with a single shared data validation +range.dataValidation({ + type: 'list', + allowBlank: false, + showInputMessage: false, + prompt: false, + promptTitle: 'String', + showErrorMessage: false, + error: 'String', + errorTitle: 'String', + operator: 'String', + formula1: 'Item1,Item2,Item3,Item4',//Required + formula2: 'String' +}); + +//Here is a short version of the one above. +range.dataValidation('Item1,Item2,Item3,Item4'); + +// Get the data validation +const obj = range.dataValidation(); // Returns an object + +// Remove the data validation +range.dataValidation(null); //Returns the Range +``` +Please note, the data validation gets applied to the entire range, *not* each Cell in the range. + +### Method Chaining + +xlsx-populate uses method-chaining similar to that found in [jQuery](https://jquery.com/) and [d3](https://d3js.org/). This lets you construct large chains of setters as desired: +```js +workbook + .sheet(0) + .cell("A1") + .value("foo") + .style("bold", true) + .relativeCell(1, 0) + .formula("A1") + .style("italic", true) +.workbook() + .sheet(1) + .range("A1:B3") + .value(5) + .cell(0, 0) + .style("underline", "double"); + +``` + +### Hyperlinks +Hyperlinks are also supported on cells using the [Cell.hyperlink](#Cell+hyperlink) method. The method will _not_ style the content to look like a hyperlink. You must do that yourself: +```js +// Set a hyperlink +cell.value("Link Text") + .style({ fontColor: "0563c1", underline: true }) + .hyperlink("http://example.com"); + +// Set a hyperlink with tooltip +cell.value("Link Text") + .style({ fontColor: "0563c1", underline: true }) + .hyperlink("http://example.com", "example.com"); + +// Set a hyperlink with tooltip by object +cell.value("Link Text") + .style({ fontColor: "0563c1", underline: true }) + .hyperlink({ hyperlink: "http://example.com", tooltip: "example.com" }); + +// Get the hyperlink +const value = cell.hyperlink(); // Returns 'http://example.com' +``` + +### Serving from Express +You can serve the workbook from [express](http://expressjs.com/) or other web servers with something like this: +```js +router.get("/download", function (req, res, next) { + // Open the workbook. + XlsxPopulate.fromFileAsync("input.xlsx") + .then(workbook => { + // Make edits. + workbook.sheet(0).cell("A1").value("foo"); + + // Get the output + return workbook.outputAsync(); + }) + .then(data => { + // Set the output file name. + res.attachment("output.xlsx"); + + // Send the workbook. + res.send(data); + }) + .catch(next); +}); +``` + +### Browser Usage +Usage in the browser is almost the same. A functional example can be found in [examples/browser/index.html](https://gitcdn.xyz/repo/dtjohnson/xlsx-populate/master/examples/browser/index.html). The library is exposed globally as `XlsxPopulate`. Existing workbooks can be loaded from a file: +```js +// Assuming there is a file input in the page with the id 'file-input' +var file = document.getElementById("file-input").files[0]; + +// A File object is a special kind of blob. +XlsxPopulate.fromDataAsync(file) + .then(function (workbook) { + // ... + }); +``` + +You can also load from AJAX if you set the responseType to 'arraybuffer': +```js +var req = new XMLHttpRequest(); +req.open("GET", "http://...", true); +req.responseType = "arraybuffer"; +req.onreadystatechange = function () { + if (req.readyState === 4 && req.status === 200){ + XlsxPopulate.fromDataAsync(req.response) + .then(function (workbook) { + // ... + }); + } +}; + +req.send(); +``` + +To download the workbook, you can either export as a blob (default behavior) or as a base64 string. You can then insert a link into the DOM and click it: +```js +workbook.outputAsync() + .then(function (blob) { + if (window.navigator && window.navigator.msSaveOrOpenBlob) { + // If IE, you must uses a different method. + window.navigator.msSaveOrOpenBlob(blob, "out.xlsx"); + } else { + var url = window.URL.createObjectURL(blob); + var a = document.createElement("a"); + document.body.appendChild(a); + a.href = url; + a.download = "out.xlsx"; + a.click(); + window.URL.revokeObjectURL(url); + document.body.removeChild(a); + } + }); +``` + +Alternatively, you can download via a data URI, but this is not supported by IE: +```js +workbook.outputAsync("base64") + .then(function (base64) { + location.href = "data:" + XlsxPopulate.MIME_TYPE + ";base64," + base64; + }); +``` + +### Promises +xlsx-populate uses [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to manage async input/output. By default it uses the `Promise` defined in the browser or Node.js. In browsers that don't support promises (IE) a [polyfill is used via JSZip](https://stuk.github.io/jszip/documentation/api_jszip/external.html). +```js +// Get the current promise library in use. +// Helpful for getting a usable Promise library in IE. +var Promise = XlsxPopulate.Promise; +``` + +If you prefer, you can override the default `Promise` library used with another ES6 compliant library like [bluebird](http://bluebirdjs.com/). +```js +const Promise = require("bluebird"); +const XlsxPopulate = require("xlsx-populate"); +XlsxPopulate.Promise = Promise; +``` + +### Encryption +XLSX Agile encryption and descryption are supported so you can read and write password-protected workbooks. To read a protected workbook, pass the password in as an option: +```js +XlsxPopulate.fromFileAsync("./Book1.xlsx", { password: "S3cret!" }) + .then(workbook => { + // ... + }); +``` + +Similarly, to write a password encrypted workbook: +```js +workbook.toFileAsync("./out.xlsx", { password: "S3cret!" }); +``` +The password option is supported in all output methods. N.B. Workbooks will only be encrypted if you supply a password when outputting even if they had a password when reading. + +Encryption support is also available in the browser, but take care! Any password you put in browser code can be read by anyone with access to your code. You should only use passwords that are supplied by the end-user. Also, the performance of encryption/decryption in the browser is far worse than with Node.js. IE, in particular, is extremely slow. xlsx-populate is bundled for browsers with and without encryption support as the encryption libraries increase the size of the bundle a lot. + +## Missing Features +There are many, many features of the XLSX format that are not yet supported. If your use case needs something that isn't supported +please open an issue to show your support. Better still, feel free to [contribute](#contributing) a pull request! + +## Submitting an Issue +If you happen to run into a bug or an issue, please feel free to [submit an issue](https://github.com/dtjohnson/xlsx-populate/issues). I only ask that you please include sample JavaScript code that demonstrates the issue. +If the problem lies with modifying some template, it is incredibly difficult to debug the issue without the template. So please attach the template if possible. If you have confidentiality concerns, please attach a different workbook that exhibits the issue or you can send your workbook directly to [dtjohnson](https://github.com/dtjohnson) after creating the issue. + +## Contributing + +Pull requests are very much welcome! If you'd like to contribute, please make sure to read this section carefully first. + +### How xlsx-populate Works +An XLSX workbook is essentially a zip of a bunch of XML files. xlsx-populate uses [JSZip](https://stuk.github.io/jszip/) +to unzip the workbook and [sax-js](https://github.com/isaacs/sax-js) to parse the XML documents into corresponding objects. +As you call methods, xlsx-populate manipulates the content of those objects. When you generate the output, xlsx-populate +uses [xmlbuilder-js](https://github.com/oozcitak/xmlbuilder-js) to convert the objects back to XML and then uses JSZip to +rezip them back into a workbook. + +The way in which xlsx-populate manipulates objects that are essentially the XML data is very different from the usual way +parser/generator libraries work. Most other libraries will deserialize the XML into a rich object model. That model is then +manipulated and serialized back into XML upon generation. The challenge with this approach is that the Office Open XML spec is [HUGE](http://www.ecma-international.org/publications/standards/Ecma-376.htm). +It is extremely difficult for libraries to be able to support the entire specification. So these other libraries will deserialize +only the portion of the spec they support and any other content/styles in the workbook they don't support are lost. Since +xlsx-populate just manipulates the XML data, it is able to preserve styles and other content while still only supporting +a fraction of the spec. + +### Setting up your Environment +You'll need to make sure [Node.js](https://nodejs.org/en/) v4+ is installed (as xlsx-populate uses ES6 syntax). You'll also +need to install [gulp](https://github.com/gulpjs/gulp): +```bash +npm install -g gulp +``` + +Make sure you have [git](https://git-scm.com/) installed. Then follow [this guide](https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) to see how to check out code, branch, and +then submit your code as a pull request. When you check out the code, you'll first need to install the npm dependencies. +From the project root, run: +```bash +npm install +``` + +The default gulp task is set up to watch the source files for updates and retest while you edit. From the project root just run: +```bash +gulp +``` + +You should see the test output in your console window. As you edit files the tests will run again and show you if you've +broken anything. (Note that if you've added new files you'll need to restart gulp for the new files to be watched.) + +Now write your code and make sure to add [Jasmine](https://jasmine.github.io/) unit tests. When you are finished, you need +to build the code for the browser. Do that by running the gulp build command: +```bash +gulp build +``` + +Verify all is working, check in your code, and submit a pull request. + +### Pull Request Checklist +To make sure your code is consistent and high quality, please make sure to follow this checklist before submitting a pull request: + * Your code must follow the getter/setter pattern using a single function for both. Check `arguments.length` or use `ArgHandler` to distinguish. + * You must use valid [JSDoc](http://usejsdoc.org/) comments on *all* methods and classes. Use `@private` for private methods and `@ignore` for any public methods that are internal to xlsx-populate and should not be included in the public API docs. + * You must adhere to the configured [ESLint](http://eslint.org/) linting rules. You can configure your IDE to display rule violations live or you can run `gulp lint` to see them. + * Use [ES6](http://es6-features.org/#Constants) syntax. (This should be enforced by ESLint.) + * Make sure to have full [Jasmine](https://jasmine.github.io/) unit test coverage for your code. + * Make sure all tests pass successfully. + * Whenever possible, do not modify/break existing API behavior. This module adheres to the [semantic versioning standard](https://docs.npmjs.com/getting-started/semantic-versioning). So any breaking changes will require a major release. + * If your feature needs more documentation than just the JSDoc output, please add to the docs/template.md README file. + + +### Gulp Tasks + +xlsx-populate uses [gulp](https://github.com/gulpjs/gulp) as a build tool. There are a number of tasks: + +* __browser__ - Transpile and build client-side JavaScript project bundle using [browserify](http://browserify.org/) and [babelify](https://github.com/babel/babelify). +* __lint__ - Check project source code style using [ESLint](http://eslint.org/). +* __unit__ - Run [Jasmine](https://jasmine.github.io/) unit tests. +* __unit-browser__ - Run the unit tests in real browsers using [Karma](https://karma-runner.github.io/1.0/index.html). +* __e2e-parse__ - End-to-end tests of parsing data out of sample workbooks that were created in Microsoft Excel. +* __e2e-generate__ - End-to-end tests of generating workbooks using xlsx-populate. To verify the workbooks were truly generated correctly they need to be opened in Microsoft Excel and verified. This task automates this verification using the .NET Excel Interop library with [Edge.js](https://github.com/tjanczuk/edge) acting as a bridge between Node.js and C#. Note that these tests will _only_ run on Windows with Microsoft Excel and the [Primary Interop Assemblies installed](https://msdn.microsoft.com/en-us/library/kh3965hw.aspx). +* __e2e-browser__ - End-to-end tests of usage of the browserify bundle in real browsers using Karma. +* __blank__ - Convert a blank XLSX template into a JS buffer module to support [fromBlankAsync](#XlsxPopulate.fromBlankAsync). +* __docs__ - Build this README doc by combining docs/template.md, API docs generated with [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown), and a table of contents generated with [markdown-toc](https://github.com/jonschlinkert/markdown-toc). +* __watch__ - Watch files for changes and then run associated gulp task. (Used by the default task.) +* __build__ - Run all gulp tasks, including linting and tests, and build the docs and browser bundle. +* __default__ - Run blank, unit, and docs tasks and watch the source files for those tasks for changes. + +## Style Reference + +### Styles +|Style Name|Type|Description| +| ------------- | ------------- | ----- | +|bold|`boolean`|`true` for bold, `false` for not bold| +|italic|`boolean`|`true` for italic, `false` for not italic| +|underline|`boolean|string`|`true` for single underline, `false` for no underline, `'double'` for double-underline| +|strikethrough|`boolean`|`true` for strikethrough `false` for not strikethrough| +|subscript|`boolean`|`true` for subscript, `false` for not subscript (cannot be combined with superscript)| +|superscript|`boolean`|`true` for superscript, `false` for not superscript (cannot be combined with subscript)| +|fontSize|`number`|Font size in points. Must be greater than 0.| +|fontFamily|`string`|Name of font family.| +|fontColor|`Color|string|number`|Color of the font. If string, will set an RGB color. If number, will set a theme color.| +|horizontalAlignment|`string`|Horizontal alignment. Allowed values: `'left'`, `'center'`, `'right'`, `'fill'`, `'justify'`, `'centerContinuous'`, `'distributed'`| +|justifyLastLine|`boolean`|a.k.a Justified Distributed. Only applies when horizontalAlignment === `'distributed'`. A boolean value indicating if the cells justified or distributed alignment should be used on the last line of text. (This is typical for East Asian alignments but not typical in other contexts.)| +|indent|`number`|Number of indents. Must be greater than or equal to 0.| +|verticalAlignment|`string`|Vertical alignment. Allowed values: `'top'`, `'center'`, `'bottom'`, `'justify'`, `'distributed'`| +|wrapText|`boolean`|`true` to wrap the text in the cell, `false` to not wrap.| +|shrinkToFit|`boolean`|`true` to shrink the text in the cell to fit, `false` to not shrink.| +|textDirection|`string`|Direction of the text. Allowed values: `'left-to-right'`, `'right-to-left'`| +|textRotation|`number`|Counter-clockwise angle of rotation in degrees. Must be [-90, 90] where negative numbers indicate clockwise rotation.| +|angleTextCounterclockwise|`boolean`|Shortcut for textRotation of 45 degrees.| +|angleTextClockwise|`boolean`|Shortcut for textRotation of -45 degrees.| +|rotateTextUp|`boolean`|Shortcut for textRotation of 90 degrees.| +|rotateTextDown|`boolean`|Shortcut for textRotation of -90 degrees.| +|verticalText|`boolean`|Special rotation that shows text vertical but individual letters are oriented normally. `true` to rotate, `false` to not rotate.| +|fill|`SolidFill|PatternFill|GradientFill|Color|string|number`|The cell fill. If Color, will set a solid fill with the color. If string, will set a solid RGB fill. If number, will set a solid theme color fill.| +|border|`Borders|Border|string|boolean}`|The border settings. If string, will set outside borders to given border style. If true, will set outside border style to `'thin'`.| +|borderColor|`Color|string|number`|Color of the borders. If string, will set an RGB color. If number, will set a theme color.| +|borderStyle|`string`|Style of the outside borders. Allowed values: `'hair'`, `'dotted'`, `'dashDotDot'`, `'dashed'`, `'mediumDashDotDot'`, `'thin'`, `'slantDashDot'`, `'mediumDashDot'`, `'mediumDashed'`, `'medium'`, `'thick'`, `'double'`| +|leftBorder, rightBorder, topBorder, bottomBorder, diagonalBorder|`Border|string|boolean`|The border settings for the given side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| +|leftBorderColor, rightBorderColor, topBorderColor, bottomBorderColor, diagonalBorderColor|`Color|string|number`|Color of the given border. If string, will set an RGB color. If number, will set a theme color.| +|leftBorderStyle, rightBorderStyle, topBorderStyle, bottomBorderStyle, diagonalBorderStyle|`string`|Style of the given side.| +|diagonalBorderDirection|`string`|Direction of the diagonal border(s) from left to right. Allowed values: `'up'`, `'down'`, `'both'`| +|numberFormat|`string`|Number format code. See docs [here](https://support.office.com/en-us/article/Number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68?ui=en-US&rs=en-US&ad=US).| + +### Color +An object representing a color. + +|Property|Type|Description| +| ------------- | ------------- | ----- | +|[rgb]|`string`|RGB color code (e.g. `'ff0000'`). Either rgb or theme is required.| +|[theme]|`number`|Index of a theme color. Either rgb or theme is required.| +|[tint]|`number`|Optional tint value of the color from -1 to 1. Particularly useful for theme colors. 0.0 means no tint, -1.0 means 100% darken, and 1.0 means 100% lighten.| + +### Borders +An object representing all of the borders. + +|Property|Type|Description| +| ------------- | ------------- | ----- | +|[left]|`Border|string|boolean`|The border settings for the left side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| +|[right]|`Border|string|boolean`|The border settings for the right side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| +|[top]|`Border|string|boolean`|The border settings for the top side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| +|[bottom]|`Border|string|boolean`|The border settings for the bottom side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| +|[diagonal]|`Border|string|boolean`|The border settings for the diagonal side. If string, will set border to the given border style. If true, will set border style to `'thin'`.| + +### Border +An object representing an individual border. + +|Property|Type|Description| +| ------------- | ------------- | ----- | +|style|`string`|Style of the given border.| +|color|`Color|string|number`|Color of the given border. If string, will set an RGB color. If number, will set a theme color.| +|[direction]|`string`|For diagonal border, the direction of the border(s) from left to right. Allowed values: `'up'`, `'down'`, `'both'`| + +### SolidFill +An object representing a solid fill. + +|Property|Type|Description| +| ------------- | ------------- | ----- | +|type|`'solid'`|| +|color|`Color|string|number`|Color of the fill. If string, will set an RGB color. If number, will set a theme color.| + +### PatternFill +An object representing a pattern fill. + +|Property|Type|Description| +| ------------- | ------------- | ----- | +|type|`'pattern'`|| +|pattern|`string`|Name of the pattern. Allowed values: `'gray125'`, `'darkGray'`, `'mediumGray'`, `'lightGray'`, `'gray0625'`, `'darkHorizontal'`, `'darkVertical'`, `'darkDown'`, `'darkUp'`, `'darkGrid'`, `'darkTrellis'`, `'lightHorizontal'`, `'lightVertical'`, `'lightDown'`, `'lightUp'`, `'lightGrid'`, `'lightTrellis'`.| +|foreground|`Color|string|number`|Color of the foreground. If string, will set an RGB color. If number, will set a theme color.| +|background|`Color|string|number`|Color of the background. If string, will set an RGB color. If number, will set a theme color.| + +### GradientFill +An object representing a gradient fill. + +|Property|Type|Description| +| ------------- | ------------- | ----- | +|type|`'gradient'`|| +|[gradientType]|`string`|Type of gradient. Allowed values: `'linear'` (default), `'path'`. With a path gradient, a path is drawn between the top, left, right, and bottom values and a graident is draw from that path to the outside of the cell.| +|stops|`Array.<{}>`|| +|stops[].position|`number`|The position of the stop from 0 to 1.| +|stops[].color|`Color|string|number`|Color of the stop. If string, will set an RGB color. If number, will set a theme color.| +|[angle]|`number`|If linear gradient, the angle of clockwise rotation of the gradient.| +|[left]|`number`|If path gradient, the left position of the path as a percentage from 0 to 1.| +|[right]|`number`|If path gradient, the right position of the path as a percentage from 0 to 1.| +|[top]|`number`|If path gradient, the top position of the path as a percentage from 0 to 1.| +|[bottom]|`number`|If path gradient, the bottom position of the path as a percentage from 0 to 1.| + +## API Reference ### Classes
@@ -819,7 +829,7 @@ An object representing a gradient fill. ### Cell A cell -**Kind**: global class +**Kind**: global class * [Cell](#Cell) * _instance_ @@ -863,15 +873,15 @@ A cell #### cell.active() ⇒ boolean Gets a value indicating whether the cell is the active cell in the sheet. -**Kind**: instance method of [Cell](#Cell) -**Returns**: boolean - True if active, false otherwise. +**Kind**: instance method of [Cell](#Cell) +**Returns**: boolean - True if active, false otherwise. #### cell.active(active) ⇒ [Cell](#Cell) Make the cell the active cell in the sheet. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -882,8 +892,8 @@ Make the cell the active cell in the sheet. #### cell.address([opts]) ⇒ string Get the address of the column. -**Kind**: instance method of [Cell](#Cell) -**Returns**: string - The address +**Kind**: instance method of [Cell](#Cell) +**Returns**: string - The address | Param | Type | Description | | --- | --- | --- | @@ -898,36 +908,36 @@ Get the address of the column. #### cell.column() ⇒ [Column](#Column) Gets the parent column of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Column](#Column) - The parent column. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Column](#Column) - The parent column. #### cell.clear() ⇒ [Cell](#Cell) Clears the contents from the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. #### cell.columnName() ⇒ number Gets the column name of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: number - The column name. +**Kind**: instance method of [Cell](#Cell) +**Returns**: number - The column name. #### cell.columnNumber() ⇒ number Gets the column number of the cell (1-based). -**Kind**: instance method of [Cell](#Cell) -**Returns**: number - The column number. +**Kind**: instance method of [Cell](#Cell) +**Returns**: number - The column number. #### cell.find(pattern, [replacement]) ⇒ boolean Find the given pattern in the cell and optionally replace it. -**Kind**: instance method of [Cell](#Cell) -**Returns**: boolean - A flag indicating if the pattern was found. +**Kind**: instance method of [Cell](#Cell) +**Returns**: boolean - A flag indicating if the pattern was found. | Param | Type | Description | | --- | --- | --- | @@ -939,15 +949,15 @@ Find the given pattern in the cell and optionally replace it. #### cell.formula() ⇒ string Gets the formula in the cell. Note that if a formula was set as part of a range, the getter will return 'SHARED'. This is a limitation that may be addressed in a future release. -**Kind**: instance method of [Cell](#Cell) -**Returns**: string - The formula in the cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: string - The formula in the cell. #### cell.formula(formula) ⇒ [Cell](#Cell) Sets the formula in the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -958,15 +968,15 @@ Sets the formula in the cell. #### cell.hyperlink() ⇒ string \| undefined Gets the hyperlink attached to the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: string \| undefined - The hyperlink or undefined if not set. +**Kind**: instance method of [Cell](#Cell) +**Returns**: string \| undefined - The hyperlink or undefined if not set. #### cell.hyperlink(hyperlink) ⇒ [Cell](#Cell) Set or clear the hyperlink on the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -977,15 +987,15 @@ Set or clear the hyperlink on the cell. #### cell.dataValidation() ⇒ object \| undefined Gets the data validation object attached to the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: object \| undefined - The data validation or undefined if not set. +**Kind**: instance method of [Cell](#Cell) +**Returns**: object \| undefined - The data validation or undefined if not set. #### cell.dataValidation(dataValidation) ⇒ [Cell](#Cell) Set or clear the data validation object of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -996,8 +1006,8 @@ Set or clear the data validation object of the cell. #### cell.tap(callback) ⇒ [Cell](#Cell) Invoke a callback on the cell and return the cell. Useful for method chaining. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1008,8 +1018,8 @@ Invoke a callback on the cell and return the cell. Useful for method chaining. #### cell.thru(callback) ⇒ \* Invoke a callback on the cell and return the value provided by the callback. Useful for method chaining. -**Kind**: instance method of [Cell](#Cell) -**Returns**: \* - The return value of the callback. +**Kind**: instance method of [Cell](#Cell) +**Returns**: \* - The return value of the callback. | Param | Type | Description | | --- | --- | --- | @@ -1020,8 +1030,8 @@ Invoke a callback on the cell and return the value provided by the callback. Use #### cell.rangeTo(cell) ⇒ [Range](#Range) Create a range from this cell and another. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1032,8 +1042,8 @@ Create a range from this cell and another. #### cell.relativeCell(rowOffset, columnOffset) ⇒ [Cell](#Cell) Returns a cell with a relative position given the offsets provided. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The relative cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The relative cell. | Param | Type | Description | | --- | --- | --- | @@ -1045,29 +1055,29 @@ Returns a cell with a relative position given the offsets provided. #### cell.row() ⇒ [Row](#Row) Gets the parent row of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Row](#Row) - The parent row. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Row](#Row) - The parent row. #### cell.rowNumber() ⇒ number Gets the row number of the cell (1-based). -**Kind**: instance method of [Cell](#Cell) -**Returns**: number - The row number. +**Kind**: instance method of [Cell](#Cell) +**Returns**: number - The row number. #### cell.sheet() ⇒ [Sheet](#Sheet) Gets the parent sheet. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Sheet](#Sheet) - The parent sheet. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Sheet](#Sheet) - The parent sheet. #### cell.style(name) ⇒ \* Gets an individual style. -**Kind**: instance method of [Cell](#Cell) -**Returns**: \* - The style. +**Kind**: instance method of [Cell](#Cell) +**Returns**: \* - The style. | Param | Type | Description | | --- | --- | --- | @@ -1078,8 +1088,8 @@ Gets an individual style. #### cell.style(names) ⇒ object.<string, \*> Gets multiple styles. -**Kind**: instance method of [Cell](#Cell) -**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. +**Kind**: instance method of [Cell](#Cell) +**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. | Param | Type | Description | | --- | --- | --- | @@ -1090,8 +1100,8 @@ Gets multiple styles. #### cell.style(name, value) ⇒ [Cell](#Cell) Sets an individual style. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1103,8 +1113,8 @@ Sets an individual style. #### cell.style(name) ⇒ [Range](#Range) Sets the styles in the range starting with the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Range](#Range) - The range that was set. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Range](#Range) - The range that was set. | Param | Type | Description | | --- | --- | --- | @@ -1116,8 +1126,8 @@ Sets the styles in the range starting with the cell. #### cell.style(styles) ⇒ [Cell](#Cell) Sets multiple styles. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1128,8 +1138,8 @@ Sets multiple styles. #### cell.style(style) ⇒ [Cell](#Cell) Sets to a specific style -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1140,15 +1150,15 @@ Sets to a specific style #### cell.value() ⇒ string \| boolean \| number \| Date \| undefined Gets the value of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: string \| boolean \| number \| Date \| undefined - The value of the cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: string \| boolean \| number \| Date \| undefined - The value of the cell. #### cell.value(value) ⇒ [Cell](#Cell) Sets the value of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1159,8 +1169,8 @@ Sets the value of the cell. #### cell.value() ⇒ [Range](#Range) Sets the values in the range starting with the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Range](#Range) - The range that was set. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Range](#Range) - The range that was set. | Param | Type | Description | | --- | --- | --- | @@ -1171,14 +1181,14 @@ Sets the values in the range starting with the cell. #### cell.workbook() ⇒ [Workbook](#Workbook) Gets the parent workbook. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Workbook](#Workbook) - The parent workbook. #### Cell~tapCallback ⇒ undefined Callback used by tap. -**Kind**: inner typedef of [Cell](#Cell) +**Kind**: inner typedef of [Cell](#Cell) | Param | Type | Description | | --- | --- | --- | @@ -1189,8 +1199,8 @@ Callback used by tap. #### Cell~thruCallback ⇒ \* Callback used by thru. -**Kind**: inner typedef of [Cell](#Cell) -**Returns**: \* - The value to return from thru. +**Kind**: inner typedef of [Cell](#Cell) +**Returns**: \* - The value to return from thru. | Param | Type | Description | | --- | --- | --- | @@ -1201,7 +1211,7 @@ Callback used by thru. ### Column A column. -**Kind**: global class +**Kind**: global class * [Column](#Column) * [.address([opts])](#Column+address) ⇒ string @@ -1225,8 +1235,8 @@ A column. #### column.address([opts]) ⇒ string Get the address of the column. -**Kind**: instance method of [Column](#Column) -**Returns**: string - The address +**Kind**: instance method of [Column](#Column) +**Returns**: string - The address | Param | Type | Description | | --- | --- | --- | @@ -1239,8 +1249,8 @@ Get the address of the column. #### column.cell(rowNumber) ⇒ [Cell](#Cell) Get a cell within the column. -**Kind**: instance method of [Column](#Column) -**Returns**: [Cell](#Cell) - The cell in the column with the given row number. +**Kind**: instance method of [Column](#Column) +**Returns**: [Cell](#Cell) - The cell in the column with the given row number. | Param | Type | Description | | --- | --- | --- | @@ -1251,29 +1261,29 @@ Get a cell within the column. #### column.columnName() ⇒ string Get the name of the column. -**Kind**: instance method of [Column](#Column) -**Returns**: string - The column name. +**Kind**: instance method of [Column](#Column) +**Returns**: string - The column name. #### column.columnNumber() ⇒ number Get the number of the column. -**Kind**: instance method of [Column](#Column) -**Returns**: number - The column number. +**Kind**: instance method of [Column](#Column) +**Returns**: number - The column number. #### column.hidden() ⇒ boolean Gets a value indicating whether the column is hidden. -**Kind**: instance method of [Column](#Column) -**Returns**: boolean - A flag indicating whether the column is hidden. +**Kind**: instance method of [Column](#Column) +**Returns**: boolean - A flag indicating whether the column is hidden. #### column.hidden(hidden) ⇒ [Column](#Column) Sets whether the column is hidden. -**Kind**: instance method of [Column](#Column) -**Returns**: [Column](#Column) - The column. +**Kind**: instance method of [Column](#Column) +**Returns**: [Column](#Column) - The column. | Param | Type | Description | | --- | --- | --- | @@ -1284,15 +1294,15 @@ Sets whether the column is hidden. #### column.sheet() ⇒ [Sheet](#Sheet) Get the parent sheet. -**Kind**: instance method of [Column](#Column) -**Returns**: [Sheet](#Sheet) - The parent sheet. +**Kind**: instance method of [Column](#Column) +**Returns**: [Sheet](#Sheet) - The parent sheet. #### column.style(name) ⇒ \* Gets an individual style. -**Kind**: instance method of [Column](#Column) -**Returns**: \* - The style. +**Kind**: instance method of [Column](#Column) +**Returns**: \* - The style. | Param | Type | Description | | --- | --- | --- | @@ -1303,8 +1313,8 @@ Gets an individual style. #### column.style(names) ⇒ object.<string, \*> Gets multiple styles. -**Kind**: instance method of [Column](#Column) -**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. +**Kind**: instance method of [Column](#Column) +**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. | Param | Type | Description | | --- | --- | --- | @@ -1315,8 +1325,8 @@ Gets multiple styles. #### column.style(name, value) ⇒ [Cell](#Cell) Sets an individual style. -**Kind**: instance method of [Column](#Column) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Column](#Column) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1328,8 +1338,8 @@ Sets an individual style. #### column.style(styles) ⇒ [Cell](#Cell) Sets multiple styles. -**Kind**: instance method of [Column](#Column) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Column](#Column) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1340,8 +1350,8 @@ Sets multiple styles. #### column.style(style) ⇒ [Cell](#Cell) Sets to a specific style -**Kind**: instance method of [Column](#Column) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Column](#Column) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1352,15 +1362,15 @@ Sets to a specific style #### column.width() ⇒ undefined \| number Gets the width. -**Kind**: instance method of [Column](#Column) -**Returns**: undefined \| number - The width (or undefined). +**Kind**: instance method of [Column](#Column) +**Returns**: undefined \| number - The width (or undefined). #### column.width(width) ⇒ [Column](#Column) Sets the width. -**Kind**: instance method of [Column](#Column) -**Returns**: [Column](#Column) - The column. +**Kind**: instance method of [Column](#Column) +**Returns**: [Column](#Column) - The column. | Param | Type | Description | | --- | --- | --- | @@ -1371,14 +1381,14 @@ Sets the width. #### column.workbook() ⇒ [Workbook](#Workbook) Get the parent workbook. -**Kind**: instance method of [Column](#Column) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Column](#Column) +**Returns**: [Workbook](#Workbook) - The parent workbook. ### FormulaError A formula error (e.g. #DIV/0!). -**Kind**: global class +**Kind**: global class * [FormulaError](#FormulaError) * _instance_ @@ -1397,56 +1407,56 @@ A formula error (e.g. #DIV/0!). #### formulaError.error() ⇒ string Get the error code. -**Kind**: instance method of [FormulaError](#FormulaError) -**Returns**: string - The error code. +**Kind**: instance method of [FormulaError](#FormulaError) +**Returns**: string - The error code. #### FormulaError.DIV0 : [FormulaError](#FormulaError) \#DIV/0! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.NA : [FormulaError](#FormulaError) \#N/A error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.NAME : [FormulaError](#FormulaError) \#NAME? error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.NULL : [FormulaError](#FormulaError) \#NULL! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.NUM : [FormulaError](#FormulaError) \#NUM! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.REF : [FormulaError](#FormulaError) \#REF! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.VALUE : [FormulaError](#FormulaError) \#VALUE! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) ### Range A range of cells. -**Kind**: global class +**Kind**: global class * [Range](#Range) * _instance_ @@ -1493,8 +1503,8 @@ A range of cells. #### range.address([opts]) ⇒ string Get the address of the range. -**Kind**: instance method of [Range](#Range) -**Returns**: string - The address. +**Kind**: instance method of [Range](#Range) +**Returns**: string - The address. | Param | Type | Description | | --- | --- | --- | @@ -1511,8 +1521,8 @@ Get the address of the range. #### range.cell(ri, ci) ⇒ [Cell](#Cell) Gets a cell within the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Range](#Range) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1524,36 +1534,36 @@ Gets a cell within the range. #### range.autoFilter() ⇒ [Range](#Range) Sets sheet autoFilter to this range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - This range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - This range. #### range.cells() ⇒ Array.<Array.<Cell>> Get the cells in the range as a 2D array. -**Kind**: instance method of [Range](#Range) -**Returns**: Array.<Array.<Cell>> - The cells. +**Kind**: instance method of [Range](#Range) +**Returns**: Array.<Array.<Cell>> - The cells. #### range.clear() ⇒ [Range](#Range) Clear the contents of all the cells in the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. #### range.endCell() ⇒ [Cell](#Cell) Get the end cell of the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Cell](#Cell) - The end cell. +**Kind**: instance method of [Range](#Range) +**Returns**: [Cell](#Cell) - The end cell. #### range.forEach(callback) ⇒ [Range](#Range) Call a function for each cell in the range. Goes by row then column. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1564,15 +1574,15 @@ Call a function for each cell in the range. Goes by row then column. #### range.formula() ⇒ string \| undefined Gets the shared formula in the start cell (assuming it's the source of the shared formula). -**Kind**: instance method of [Range](#Range) -**Returns**: string \| undefined - The shared formula. +**Kind**: instance method of [Range](#Range) +**Returns**: string \| undefined - The shared formula. #### range.formula(formula) ⇒ [Range](#Range) Sets the shared formula in the range. The formula will be translated for each cell. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1583,8 +1593,8 @@ Sets the shared formula in the range. The formula will be translated for each ce #### range.map(callback) ⇒ Array.<Array.<\*>> Creates a 2D array of values by running each cell through a callback. -**Kind**: instance method of [Range](#Range) -**Returns**: Array.<Array.<\*>> - The 2D array of return values. +**Kind**: instance method of [Range](#Range) +**Returns**: Array.<Array.<\*>> - The 2D array of return values. | Param | Type | Description | | --- | --- | --- | @@ -1595,15 +1605,15 @@ Creates a 2D array of values by running each cell through a callback. #### range.merged() ⇒ boolean Gets a value indicating whether the cells in the range are merged. -**Kind**: instance method of [Range](#Range) -**Returns**: boolean - The value. +**Kind**: instance method of [Range](#Range) +**Returns**: boolean - The value. #### range.merged(merged) ⇒ [Range](#Range) Sets a value indicating whether the cells in the range should be merged. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1614,15 +1624,15 @@ Sets a value indicating whether the cells in the range should be merged. #### range.dataValidation() ⇒ object \| undefined Gets the data validation object attached to the Range. -**Kind**: instance method of [Range](#Range) -**Returns**: object \| undefined - The data validation object or undefined if not set. +**Kind**: instance method of [Range](#Range) +**Returns**: object \| undefined - The data validation object or undefined if not set. #### range.dataValidation(dataValidation) ⇒ [Range](#Range) Set or clear the data validation object of the entire range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1633,8 +1643,8 @@ Set or clear the data validation object of the entire range. #### range.reduce(callback, [initialValue]) ⇒ \* Reduces the range to a single value accumulated from the result of a function called for each cell. -**Kind**: instance method of [Range](#Range) -**Returns**: \* - The accumulated value. +**Kind**: instance method of [Range](#Range) +**Returns**: \* - The accumulated value. | Param | Type | Description | | --- | --- | --- | @@ -1646,22 +1656,22 @@ Reduces the range to a single value accumulated from the result of a function ca #### range.sheet() ⇒ [Sheet](#Sheet) Gets the parent sheet of the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Sheet](#Sheet) - The parent sheet. +**Kind**: instance method of [Range](#Range) +**Returns**: [Sheet](#Sheet) - The parent sheet. #### range.startCell() ⇒ [Cell](#Cell) Gets the start cell of the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Cell](#Cell) - The start cell. +**Kind**: instance method of [Range](#Range) +**Returns**: [Cell](#Cell) - The start cell. #### range.style(name) ⇒ Array.<Array.<\*>> Gets a single style for each cell. -**Kind**: instance method of [Range](#Range) -**Returns**: Array.<Array.<\*>> - 2D array of style values. +**Kind**: instance method of [Range](#Range) +**Returns**: Array.<Array.<\*>> - 2D array of style values. | Param | Type | Description | | --- | --- | --- | @@ -1672,8 +1682,8 @@ Gets a single style for each cell. #### range.style(names) ⇒ Object.<string, Array.<Array.<\*>>> Gets multiple styles for each cell. -**Kind**: instance method of [Range](#Range) -**Returns**: Object.<string, Array.<Array.<\*>>> - Object whose keys are style names and values are 2D arrays of style values. +**Kind**: instance method of [Range](#Range) +**Returns**: Object.<string, Array.<Array.<\*>>> - Object whose keys are style names and values are 2D arrays of style values. | Param | Type | Description | | --- | --- | --- | @@ -1684,8 +1694,8 @@ Gets multiple styles for each cell. #### range.style(name) ⇒ [Range](#Range) Set the style in each cell to the result of a function called for each. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1697,8 +1707,8 @@ Set the style in each cell to the result of a function called for each. #### range.style(name) ⇒ [Range](#Range) Sets the style in each cell to the corresponding value in the given 2D array of values. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1710,8 +1720,8 @@ Sets the style in each cell to the corresponding value in the given 2D array of #### range.style(name, value) ⇒ [Range](#Range) Set the style of all cells in the range to a single style value. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1723,8 +1733,8 @@ Set the style of all cells in the range to a single style value. #### range.style(styles) ⇒ [Range](#Range) Set multiple styles for the cells in the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1735,8 +1745,8 @@ Set multiple styles for the cells in the range. #### range.style(style) ⇒ [Range](#Range) Sets to a specific style -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1747,8 +1757,8 @@ Sets to a specific style #### range.tap(callback) ⇒ [Range](#Range) Invoke a callback on the range and return the range. Useful for method chaining. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1759,8 +1769,8 @@ Invoke a callback on the range and return the range. Useful for method chaining. #### range.thru(callback) ⇒ \* Invoke a callback on the range and return the value provided by the callback. Useful for method chaining. -**Kind**: instance method of [Range](#Range) -**Returns**: \* - The return value of the callback. +**Kind**: instance method of [Range](#Range) +**Returns**: \* - The return value of the callback. | Param | Type | Description | | --- | --- | --- | @@ -1771,15 +1781,15 @@ Invoke a callback on the range and return the value provided by the callback. Us #### range.value() ⇒ Array.<Array.<\*>> Get the values of each cell in the range as a 2D array. -**Kind**: instance method of [Range](#Range) -**Returns**: Array.<Array.<\*>> - The values. +**Kind**: instance method of [Range](#Range) +**Returns**: Array.<Array.<\*>> - The values. #### range.value(callback) ⇒ [Range](#Range) Set the values in each cell to the result of a function called for each. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1790,8 +1800,8 @@ Set the values in each cell to the result of a function called for each. #### range.value(values) ⇒ [Range](#Range) Sets the value in each cell to the corresponding value in the given 2D array of values. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1802,8 +1812,8 @@ Sets the value in each cell to the corresponding value in the given 2D array of #### range.value(value) ⇒ [Range](#Range) Set the value of all cells in the range to a single value. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1814,14 +1824,14 @@ Set the value of all cells in the range to a single value. #### range.workbook() ⇒ [Workbook](#Workbook) Gets the parent workbook. -**Kind**: instance method of [Range](#Range) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Range](#Range) +**Returns**: [Workbook](#Workbook) - The parent workbook. #### Range~forEachCallback ⇒ undefined Callback used by forEach. -**Kind**: inner typedef of [Range](#Range) +**Kind**: inner typedef of [Range](#Range) | Param | Type | Description | | --- | --- | --- | @@ -1835,8 +1845,8 @@ Callback used by forEach. #### Range~mapCallback ⇒ \* Callback used by map. -**Kind**: inner typedef of [Range](#Range) -**Returns**: \* - The value to map to. +**Kind**: inner typedef of [Range](#Range) +**Returns**: \* - The value to map to. | Param | Type | Description | | --- | --- | --- | @@ -1850,8 +1860,8 @@ Callback used by map. #### Range~reduceCallback ⇒ \* Callback used by reduce. -**Kind**: inner typedef of [Range](#Range) -**Returns**: \* - The value to map to. +**Kind**: inner typedef of [Range](#Range) +**Returns**: \* - The value to map to. | Param | Type | Description | | --- | --- | --- | @@ -1866,7 +1876,7 @@ Callback used by reduce. #### Range~tapCallback ⇒ undefined Callback used by tap. -**Kind**: inner typedef of [Range](#Range) +**Kind**: inner typedef of [Range](#Range) | Param | Type | Description | | --- | --- | --- | @@ -1877,8 +1887,8 @@ Callback used by tap. #### Range~thruCallback ⇒ \* Callback used by thru. -**Kind**: inner typedef of [Range](#Range) -**Returns**: \* - The value to return from thru. +**Kind**: inner typedef of [Range](#Range) +**Returns**: \* - The value to return from thru. | Param | Type | Description | | --- | --- | --- | @@ -1889,7 +1899,7 @@ Callback used by thru. ### Row A row. -**Kind**: global class +**Kind**: global class * [Row](#Row) * [.address([opts])](#Row+address) ⇒ string @@ -1912,8 +1922,8 @@ A row. #### row.address([opts]) ⇒ string Get the address of the row. -**Kind**: instance method of [Row](#Row) -**Returns**: string - The address +**Kind**: instance method of [Row](#Row) +**Returns**: string - The address | Param | Type | Description | | --- | --- | --- | @@ -1926,8 +1936,8 @@ Get the address of the row. #### row.cell(columnNameOrNumber) ⇒ [Cell](#Cell) Get a cell in the row. -**Kind**: instance method of [Row](#Row) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Row](#Row) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1938,15 +1948,15 @@ Get a cell in the row. #### row.height() ⇒ undefined \| number Gets the row height. -**Kind**: instance method of [Row](#Row) -**Returns**: undefined \| number - The height (or undefined). +**Kind**: instance method of [Row](#Row) +**Returns**: undefined \| number - The height (or undefined). #### row.height(height) ⇒ [Row](#Row) Sets the row height. -**Kind**: instance method of [Row](#Row) -**Returns**: [Row](#Row) - The row. +**Kind**: instance method of [Row](#Row) +**Returns**: [Row](#Row) - The row. | Param | Type | Description | | --- | --- | --- | @@ -1957,15 +1967,15 @@ Sets the row height. #### row.hidden() ⇒ boolean Gets a value indicating whether the row is hidden. -**Kind**: instance method of [Row](#Row) -**Returns**: boolean - A flag indicating whether the row is hidden. +**Kind**: instance method of [Row](#Row) +**Returns**: boolean - A flag indicating whether the row is hidden. #### row.hidden(hidden) ⇒ [Row](#Row) Sets whether the row is hidden. -**Kind**: instance method of [Row](#Row) -**Returns**: [Row](#Row) - The row. +**Kind**: instance method of [Row](#Row) +**Returns**: [Row](#Row) - The row. | Param | Type | Description | | --- | --- | --- | @@ -1976,22 +1986,22 @@ Sets whether the row is hidden. #### row.rowNumber() ⇒ number Gets the row number. -**Kind**: instance method of [Row](#Row) -**Returns**: number - The row number. +**Kind**: instance method of [Row](#Row) +**Returns**: number - The row number. #### row.sheet() ⇒ [Sheet](#Sheet) Gets the parent sheet of the row. -**Kind**: instance method of [Row](#Row) -**Returns**: [Sheet](#Sheet) - The parent sheet. +**Kind**: instance method of [Row](#Row) +**Returns**: [Sheet](#Sheet) - The parent sheet. #### row.style(name) ⇒ \* Gets an individual style. -**Kind**: instance method of [Row](#Row) -**Returns**: \* - The style. +**Kind**: instance method of [Row](#Row) +**Returns**: \* - The style. | Param | Type | Description | | --- | --- | --- | @@ -2002,8 +2012,8 @@ Gets an individual style. #### row.style(names) ⇒ object.<string, \*> Gets multiple styles. -**Kind**: instance method of [Row](#Row) -**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. +**Kind**: instance method of [Row](#Row) +**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. | Param | Type | Description | | --- | --- | --- | @@ -2014,8 +2024,8 @@ Gets multiple styles. #### row.style(name, value) ⇒ [Cell](#Cell) Sets an individual style. -**Kind**: instance method of [Row](#Row) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Row](#Row) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2027,8 +2037,8 @@ Sets an individual style. #### row.style(styles) ⇒ [Cell](#Cell) Sets multiple styles. -**Kind**: instance method of [Row](#Row) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Row](#Row) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2039,8 +2049,8 @@ Sets multiple styles. #### row.style(style) ⇒ [Cell](#Cell) Sets to a specific style -**Kind**: instance method of [Row](#Row) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Row](#Row) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2051,14 +2061,14 @@ Sets to a specific style #### row.workbook() ⇒ [Workbook](#Workbook) Get the parent workbook. -**Kind**: instance method of [Row](#Row) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Row](#Row) +**Returns**: [Workbook](#Workbook) - The parent workbook. ### Sheet A worksheet. -**Kind**: global class +**Kind**: global class * [Sheet](#Sheet) * [.active()](#Sheet+active) ⇒ boolean @@ -2098,15 +2108,15 @@ A worksheet. #### sheet.active() ⇒ boolean Gets a value indicating whether the sheet is the active sheet in the workbook. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: boolean - True if active, false otherwise. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: boolean - True if active, false otherwise. #### sheet.active(active) ⇒ [Sheet](#Sheet) Make the sheet the active sheet in the workkbok. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2117,15 +2127,15 @@ Make the sheet the active sheet in the workkbok. #### sheet.activeCell() ⇒ [Cell](#Cell) Get the active cell in the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Cell](#Cell) - The active cell. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Cell](#Cell) - The active cell. #### sheet.activeCell(cell) ⇒ [Sheet](#Sheet) Set the active cell in the workbook. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2136,8 +2146,8 @@ Set the active cell in the workbook. #### sheet.activeCell(rowNumber, columnNameOrNumber) ⇒ [Sheet](#Sheet) Set the active cell in the workbook by row and column. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2149,8 +2159,8 @@ Set the active cell in the workbook by row and column. #### sheet.cell(address) ⇒ [Cell](#Cell) Gets the cell with the given address. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2161,8 +2171,8 @@ Gets the cell with the given address. #### sheet.cell(rowNumber, columnNameOrNumber) ⇒ [Cell](#Cell) Gets the cell with the given row and column numbers. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2174,8 +2184,8 @@ Gets the cell with the given row and column numbers. #### sheet.column(columnNameOrNumber) ⇒ [Column](#Column) Gets a column in the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Column](#Column) - The column. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Column](#Column) - The column. | Param | Type | Description | | --- | --- | --- | @@ -2186,8 +2196,8 @@ Gets a column in the sheet. #### sheet.definedName(name) ⇒ undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) Gets a defined name scoped to the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) - What the defined name refers to or undefined if not found. Will return the string formula if not a Row, Column, Cell, or Range. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) - What the defined name refers to or undefined if not found. Will return the string formula if not a Row, Column, Cell, or Range. | Param | Type | Description | | --- | --- | --- | @@ -2198,8 +2208,8 @@ Gets a defined name scoped to the sheet. #### sheet.definedName(name, refersTo) ⇒ [Workbook](#Workbook) Set a defined name scoped to the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2211,15 +2221,15 @@ Set a defined name scoped to the sheet. #### sheet.delete() ⇒ [Workbook](#Workbook) Deletes the sheet and returns the parent workbook. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Workbook](#Workbook) - The workbook. #### sheet.find(pattern, [replacement]) ⇒ [Array.<Cell>](#Cell) Find the given pattern in the sheet and optionally replace it. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Array.<Cell>](#Cell) - The matching cells. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Array.<Cell>](#Cell) - The matching cells. | Param | Type | Description | | --- | --- | --- | @@ -2231,15 +2241,15 @@ Find the given pattern in the sheet and optionally replace it. #### sheet.gridLinesVisible() ⇒ boolean Gets a value indicating whether this sheet's grid lines are visible. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: boolean - True if selected, false if not. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: boolean - True if selected, false if not. #### sheet.gridLinesVisible(selected) ⇒ [Sheet](#Sheet) Sets whether this sheet's grid lines are visible. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2250,15 +2260,15 @@ Sets whether this sheet's grid lines are visible. #### sheet.hidden() ⇒ boolean \| string Gets a value indicating if the sheet is hidden or not. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: boolean \| string - True if hidden, false if visible, and 'very' if very hidden. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: boolean \| string - True if hidden, false if visible, and 'very' if very hidden. #### sheet.hidden(hidden) ⇒ [Sheet](#Sheet) Set whether the sheet is hidden or not. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2269,8 +2279,8 @@ Set whether the sheet is hidden or not. #### sheet.move([indexOrBeforeSheet]) ⇒ [Sheet](#Sheet) Move the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2281,15 +2291,15 @@ Move the sheet. #### sheet.name() ⇒ string Get the name of the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: string - The sheet name. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: string - The sheet name. #### sheet.name(name) ⇒ [Sheet](#Sheet) Set the name of the sheet. *Note: this method does not rename references to the sheet so formulas, etc. can be broken. Use with caution!* -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2300,8 +2310,8 @@ Set the name of the sheet. *Note: this method does not rename references to the #### sheet.range(address) ⇒ [Range](#Range) Gets a range from the given range address. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -2312,8 +2322,8 @@ Gets a range from the given range address. #### sheet.range(startCell, endCell) ⇒ [Range](#Range) Gets a range from the given cells or cell addresses. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -2325,8 +2335,8 @@ Gets a range from the given cells or cell addresses. #### sheet.range(startRowNumber, startColumnNameOrNumber, endRowNumber, endColumnNameOrNumber) ⇒ [Range](#Range) Gets a range from the given row numbers and column names or numbers. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -2340,15 +2350,15 @@ Gets a range from the given row numbers and column names or numbers. #### sheet.autoFilter() ⇒ [Sheet](#Sheet) Unsets sheet autoFilter. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - This sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - This sheet. #### sheet.autoFilter(range) ⇒ [Sheet](#Sheet) Sets sheet autoFilter to a Range. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - This sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - This sheet. | Param | Type | Description | | --- | --- | --- | @@ -2359,8 +2369,8 @@ Sets sheet autoFilter to a Range. #### sheet.row(rowNumber) ⇒ [Row](#Row) Gets the row with the given number. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Row](#Row) - The row with the given number. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Row](#Row) - The row with the given number. | Param | Type | Description | | --- | --- | --- | @@ -2371,29 +2381,29 @@ Gets the row with the given number. #### sheet.tabColor() ⇒ undefined \| Color Get the tab color. (See style [Color](#color).) -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: undefined \| Color - The color or undefined if not set. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: undefined \| Color - The color or undefined if not set. #### sheet.tabColor() ⇒ Color \| string \| number Sets the tab color. (See style [Color](#color).) -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: Color \| string \| number - color - Color of the tab. If string, will set an RGB color. If number, will set a theme color. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: Color \| string \| number - color - Color of the tab. If string, will set an RGB color. If number, will set a theme color. #### sheet.tabSelected() ⇒ boolean Gets a value indicating whether this sheet is selected. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: boolean - True if selected, false if not. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: boolean - True if selected, false if not. #### sheet.tabSelected(selected) ⇒ [Sheet](#Sheet) Sets whether this sheet is selected. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2404,21 +2414,21 @@ Sets whether this sheet is selected. #### sheet.usedRange() ⇒ [Range](#Range) \| undefined Get the range of cells in the sheet that have contained a value or style at any point. Useful for extracting the entire sheet contents. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Range](#Range) \| undefined - The used range or undefined if no cells in the sheet are used. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Range](#Range) \| undefined - The used range or undefined if no cells in the sheet are used. #### sheet.workbook() ⇒ [Workbook](#Workbook) Gets the parent workbook. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Workbook](#Workbook) - The parent workbook. ### Workbook A workbook. -**Kind**: global class +**Kind**: global class * [Workbook](#Workbook) * [.activeSheet()](#Workbook+activeSheet) ⇒ [Sheet](#Sheet) @@ -2445,15 +2455,15 @@ A workbook. #### workbook.activeSheet() ⇒ [Sheet](#Sheet) Get the active sheet in the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Sheet](#Sheet) - The active sheet. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Sheet](#Sheet) - The active sheet. #### workbook.activeSheet(sheet) ⇒ [Workbook](#Workbook) Set the active sheet in the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2464,8 +2474,8 @@ Set the active sheet in the workbook. #### workbook.addSheet(name, [indexOrBeforeSheet]) ⇒ [Sheet](#Sheet) Add a new sheet to the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Sheet](#Sheet) - The new sheet. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Sheet](#Sheet) - The new sheet. | Param | Type | Description | | --- | --- | --- | @@ -2477,8 +2487,8 @@ Add a new sheet to the workbook. #### workbook.definedName(name) ⇒ undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) Gets a defined name scoped to the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) - What the defined name refers to or undefined if not found. Will return the string formula if not a Row, Column, Cell, or Range. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) - What the defined name refers to or undefined if not found. Will return the string formula if not a Row, Column, Cell, or Range. | Param | Type | Description | | --- | --- | --- | @@ -2489,8 +2499,8 @@ Gets a defined name scoped to the workbook. #### workbook.definedName(name, refersTo) ⇒ [Workbook](#Workbook) Set a defined name scoped to the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2502,8 +2512,8 @@ Set a defined name scoped to the workbook. #### workbook.deleteSheet(sheet) ⇒ [Workbook](#Workbook) Delete a sheet from the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2514,8 +2524,8 @@ Delete a sheet from the workbook. #### workbook.find(pattern, [replacement]) ⇒ boolean Find the given pattern in the workbook and optionally replace it. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: boolean - A flag indicating if the pattern was found. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: boolean - A flag indicating if the pattern was found. | Param | Type | Description | | --- | --- | --- | @@ -2527,8 +2537,8 @@ Find the given pattern in the workbook and optionally replace it. #### workbook.moveSheet(sheet, [indexOrBeforeSheet]) ⇒ [Workbook](#Workbook) Move a sheet to a new position. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2540,8 +2550,8 @@ Move a sheet to a new position. #### workbook.outputAsync([type]) ⇒ string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer Generates the workbook output. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer - The data. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer - The data. | Param | Type | Description | | --- | --- | --- | @@ -2552,8 +2562,8 @@ Generates the workbook output. #### workbook.outputAsync([opts]) ⇒ string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer Generates the workbook output. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer - The data. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer - The data. | Param | Type | Description | | --- | --- | --- | @@ -2566,8 +2576,8 @@ Generates the workbook output. #### workbook.sheet(sheetNameOrIndex) ⇒ [Sheet](#Sheet) \| undefined Gets the sheet with the provided name or index (0-based). -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Sheet](#Sheet) \| undefined - The sheet or undefined if not found. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Sheet](#Sheet) \| undefined - The sheet or undefined if not found. | Param | Type | Description | | --- | --- | --- | @@ -2578,15 +2588,15 @@ Gets the sheet with the provided name or index (0-based). #### workbook.sheets() ⇒ [Array.<Sheet>](#Sheet) Get an array of all the sheets in the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Array.<Sheet>](#Sheet) - The sheets. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Array.<Sheet>](#Sheet) - The sheets. #### workbook.property(name) ⇒ \* Gets an individual property. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: \* - The property. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: \* - The property. | Param | Type | Description | | --- | --- | --- | @@ -2597,8 +2607,8 @@ Gets an individual property. #### workbook.property(names) ⇒ object.<string, \*> Gets multiple properties. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: object.<string, \*> - Object whose keys are the property names and values are the properties. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: object.<string, \*> - Object whose keys are the property names and values are the properties. | Param | Type | Description | | --- | --- | --- | @@ -2609,8 +2619,8 @@ Gets multiple properties. #### workbook.property(name, value) ⇒ [Workbook](#Workbook) Sets an individual property. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2622,8 +2632,8 @@ Sets an individual property. #### workbook.property(properties) ⇒ [Workbook](#Workbook) Sets multiple properties. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2634,15 +2644,15 @@ Sets multiple properties. #### workbook.properties() ⇒ CoreProperties Get access to core properties object -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: CoreProperties - The core properties. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: CoreProperties - The core properties. #### workbook.toFileAsync(path, [opts]) ⇒ Promise.<undefined> Write the workbook to file. (Not supported in browsers.) -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: Promise.<undefined> - A promise. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: Promise.<undefined> - A promise. | Param | Type | Description | | --- | --- | --- | @@ -2653,7 +2663,7 @@ Write the workbook to file. (Not supported in browsers.) ### XlsxPopulate : object -**Kind**: global namespace +**Kind**: global namespace * [XlsxPopulate](#XlsxPopulate) : object * [.Promise](#XlsxPopulate.Promise) : Promise @@ -2670,26 +2680,26 @@ Write the workbook to file. (Not supported in browsers.) #### XlsxPopulate.Promise : Promise The Promise library. -**Kind**: static property of [XlsxPopulate](#XlsxPopulate) +**Kind**: static property of [XlsxPopulate](#XlsxPopulate) #### XlsxPopulate.MIME_TYPE : string The XLSX mime type. -**Kind**: static property of [XlsxPopulate](#XlsxPopulate) +**Kind**: static property of [XlsxPopulate](#XlsxPopulate) #### XlsxPopulate.FormulaError : [FormulaError](#FormulaError) Formula error class. -**Kind**: static property of [XlsxPopulate](#XlsxPopulate) +**Kind**: static property of [XlsxPopulate](#XlsxPopulate) #### XlsxPopulate.dateToNumber(date) ⇒ number Convert a date to a number for Excel. -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: number - The number. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: number - The number. | Param | Type | Description | | --- | --- | --- | @@ -2700,15 +2710,15 @@ Convert a date to a number for Excel. #### XlsxPopulate.fromBlankAsync() ⇒ [Promise.<Workbook>](#Workbook) Create a new blank workbook. -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. #### XlsxPopulate.fromDataAsync(data, [opts]) ⇒ [Promise.<Workbook>](#Workbook) Loads a workbook from a data object. (Supports any supported [JSZip data types](https://stuk.github.io/jszip/documentation/api_jszip/load_async.html).) -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2721,8 +2731,8 @@ Loads a workbook from a data object. (Supports any supported [JSZip data types]( #### XlsxPopulate.fromFileAsync(path, [opts]) ⇒ [Promise.<Workbook>](#Workbook) Loads a workbook from file. -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2735,8 +2745,8 @@ Loads a workbook from file. #### XlsxPopulate.numberToDate(number) ⇒ Date Convert an Excel number to a date. -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: Date - The date. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: Date - The date. | Param | Type | Description | | --- | --- | --- | @@ -2745,7 +2755,11 @@ Convert an Excel number to a date. ### _ -OOXML uses the CFB file format with Agile Encryption. The details of the encryption are here: https://msdn.microsoft.com/en-us/library/dd950165(v=office.12).aspx Helpful guidance also take from this Github project: https://github.com/nolze/ms-offcrypto-tool +OOXML uses the CFB file format with Agile Encryption. The details of the encryption are here: +https://msdn.microsoft.com/en-us/library/dd950165(v=office.12).aspx + +Helpful guidance also take from this Github project: +https://github.com/nolze/ms-offcrypto-tool + +**Kind**: global constant -**Kind**: global constant - From 488954508bb78064a8d245bb3fa7e9e07a125133 Mon Sep 17 00:00:00 2001 From: Kuznetsov Aleksey Date: Sun, 29 Jul 2018 00:21:53 +0300 Subject: [PATCH 03/13] Add a hyperlink tooltip unit test --- test/unit/Cell.spec.js | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/test/unit/Cell.spec.js b/test/unit/Cell.spec.js index 42289d6a..aa330e73 100644 --- a/test/unit/Cell.spec.js +++ b/test/unit/Cell.spec.js @@ -201,6 +201,11 @@ describe("Cell", () => { expect(cell.hyperlink("HYPERLINK")).toBe(cell); expect(sheet.hyperlink).toHaveBeenCalledWith("C7", "HYPERLINK"); }); + + it("should set the hyperlink with tooltip on the sheet", () => { + expect(cell.hyperlink("HYPERLINK", "TOOLTIP")).toBe(cell); + expect(sheet.hyperlink).toHaveBeenCalledWith("C7", "HYPERLINK", "TOOLTIP"); + }); }); describe('dataValidation', () => { From fb121cb9833719e39c55bdda72be7bee0d6400a3 Mon Sep 17 00:00:00 2001 From: Eddie Corrigall Date: Sun, 30 Dec 2018 20:15:26 -0500 Subject: [PATCH 04/13] Implement email and internal hyperlinks --- lib/Sheet.js | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/lib/Sheet.js b/lib/Sheet.js index c20733e8..42b556a9 100644 --- a/lib/Sheet.js +++ b/lib/Sheet.js @@ -558,7 +558,14 @@ class Sheet { *//** * Set the hyperlink attached to the cell with the given address. * @param {string} address - The address to of the hyperlinked cell. - * @param {boolean} hyperlink - The hyperlink to set or undefined to clear. + * @param {string} hyperlink - The hyperlink to set or undefined to clear. + * @returns {Sheet} The sheet. + * @ignore + *//** + * Set the hyperlink attached to the cell with the given email and subject. + * @param {string} address - The address to of the hyperlinked cell. + * @param {string} email - The email address to set. + * @param {string} subject - The email subject to set. * @returns {Sheet} The sheet. * @ignore */ @@ -575,15 +582,32 @@ class Sheet { return this; }) .case(['string', 'string'], (address, hyperlink) => { - const relationship = this._relationships.add("hyperlink", hyperlink, "External"); + var hyperlinkAttributes; + const isHyperlinkInternalAddress = addressConverter.fromAddress(hyperlink); + if (isHyperlinkInternalAddress) { + hyperlinkAttributes = { + ref: address, + location: hyperlink, + display: hyperlink + }; + } else { + const relationship = this._relationships.add("hyperlink", hyperlink, "External"); + hyperlinkAttributes = { + ref: address, + 'r:id': relationship.attributes.Id + }; + } this._hyperlinks[address] = { name: 'hyperlink', - attributes: { ref: address, 'r:id': relationship.attributes.Id }, + attributes: hyperlinkAttributes, children: [] }; - return this; }) + .case(['string', 'string', 'string'], (address, email, subject) => { + const hyperlink = encodeURI('mailto:' + email + '?' + 'subject=' + subject); + return this.hyperlink(address, hyperlink); + }) .handle(arguments); } From 1ba5e62ef3142e9e885fb293298200c09d0cce73 Mon Sep 17 00:00:00 2001 From: Eddie Corrigall Date: Mon, 31 Dec 2018 12:04:08 -0500 Subject: [PATCH 05/13] Fixes suggested by gulp lint --- lib/Sheet.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/Sheet.js b/lib/Sheet.js index 42b556a9..2adb8f78 100644 --- a/lib/Sheet.js +++ b/lib/Sheet.js @@ -582,7 +582,7 @@ class Sheet { return this; }) .case(['string', 'string'], (address, hyperlink) => { - var hyperlinkAttributes; + let hyperlinkAttributes; const isHyperlinkInternalAddress = addressConverter.fromAddress(hyperlink); if (isHyperlinkInternalAddress) { hyperlinkAttributes = { @@ -605,7 +605,7 @@ class Sheet { return this; }) .case(['string', 'string', 'string'], (address, email, subject) => { - const hyperlink = encodeURI('mailto:' + email + '?' + 'subject=' + subject); + const hyperlink = encodeURI('mailto:${email}?subject=${subject}'); return this.hyperlink(address, hyperlink); }) .handle(arguments); From 0c173e3cc5820cff39988f7a0242832cdfc958d0 Mon Sep 17 00:00:00 2001 From: Kuznetsov Aleksey Date: Wed, 9 Jan 2019 21:58:18 +0300 Subject: [PATCH 06/13] Update hyperlinks example in template.md --- docs/template.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/template.md b/docs/template.md index 835eeaba..b6c848f7 100644 --- a/docs/template.md +++ b/docs/template.md @@ -436,7 +436,17 @@ Hyperlinks are also supported on cells using the [Cell.hyperlink](#Cell+hyperlin cell.value("Link Text") .style({ fontColor: "0563c1", underline: true }) .hyperlink("http://example.com"); - + +// Set a hyperlink with tooltip +cell.value("Link Text") + .style({ fontColor: "0563c1", underline: true }) + .hyperlink("http://example.com", "example.com"); + +// Set a hyperlink with tooltip by object +cell.value("Link Text") + .style({ fontColor: "0563c1", underline: true }) + .hyperlink({ hyperlink: "http://example.com", tooltip: "example.com" }); + // Get the hyperlink const value = cell.hyperlink(); // Returns 'http://example.com' ``` From 1ccd62249d7bd3cd353609be462dc324c33fe410 Mon Sep 17 00:00:00 2001 From: Kuznetsov Aleksey Date: Wed, 9 Jan 2019 21:58:42 +0300 Subject: [PATCH 07/13] Update README.md --- README.md | 685 +++++++++++++++++++++++++++--------------------------- 1 file changed, 343 insertions(+), 342 deletions(-) diff --git a/README.md b/README.md index 16db7c25..d96ca5b1 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ XlsxPopulate.fromBlankAsync() .then(workbook => { // Modify the workbook. workbook.sheet("Sheet1").cell("A1").value("This is neat!"); - + // Write to file. return workbook.toFileAsync("./out.xlsx"); }); @@ -92,12 +92,12 @@ XlsxPopulate.fromFileAsync("./Book1.xlsx") .then(workbook => { // Modify the workbook. const value = workbook.sheet("Sheet1").cell("A1").value(); - + // Log the value. console.log(value); }); ``` -__Note__: in cells that contain values calculated by formulas, Excel will store the calculated value in the workbook. The [value](#Cell+value) method will return the value of the cells at the time the workbook was saved. xlsx-populate will _not_ recalculate the values as you manipulate the workbook and will _not_ write the values to the output. +__Note__: in cells that contain values calculated by formulas, Excel will store the calculated value in the workbook. The [value](#Cell+value) method will return the value of the cells at the time the workbook was saved. xlsx-populate will _not_ recalculate the values as you manipulate the workbook and will _not_ write the values to the output. ### Ranges xlsx-populate also supports ranges of cells to allow parsing/manipulation of multiple cells at once. @@ -141,7 +141,7 @@ You can access rows and columns in order to change size, hide/show, or access ce // Get the B column, set its width and unhide it (assuming it was hidden). sheet.column("B").width(25).hidden(false); -const cell = sheet.row(5).cell(3); // Returns the cell at C5. +const cell = sheet.row(5).cell(3); // Returns the cell at C5. ``` ### Managing Sheets @@ -255,7 +255,7 @@ You can search for occurrences of text in cells within the workbook or sheets an // Find all occurrences of the text "foo" in the workbook and replace with "bar". workbook.find("foo", "bar"); // Returns array of matched cells -// Find the matches but don't replace. +// Find the matches but don't replace. workbook.find("foo"); // Just look in the first sheet. @@ -284,9 +284,9 @@ cell.style({ bold: true, italic: true }); // Get a single style const bold = cell.style("bold"); // true - + // Get multiple styles -const styles = cell.style(["bold", "italic"]); // { bold: true, italic: true } +const styles = cell.style(["bold", "italic"]); // { bold: true, italic: true } ``` Similarly for ranges: @@ -318,9 +318,9 @@ sheet.column("A").style({ bold: true, italic: true }); // Get a single style const bold = sheet.column(3).style("bold"); - + // Get multiple styles -const styles = sheet.row(5).style(["bold", "italic"]); +const styles = sheet.row(5).style(["bold", "italic"]); ``` Note that the row/column style behavior mirrors Excel. Setting a style on a column will apply that style to all existing cells and any new cells that are populated. Getting the row/column style will return only the styles that have been applied to the entire row/column, not the styles of every cell in the row or column. @@ -385,7 +385,7 @@ Data validation is also supported. To set/get/remove a cell data validation: // Set the data validation cell.dataValidation({ type: 'list', - allowBlank: false, + allowBlank: false, showInputMessage: false, prompt: false, promptTitle: 'String', @@ -413,7 +413,7 @@ Similarly for ranges: // Set all cells in range with a single shared data validation range.dataValidation({ type: 'list', - allowBlank: false, + allowBlank: false, showInputMessage: false, prompt: false, promptTitle: 'String', @@ -454,7 +454,7 @@ workbook .value(5) .cell(0, 0) .style("underline", "double"); - + ``` ### Hyperlinks @@ -488,14 +488,14 @@ router.get("/download", function (req, res, next) { .then(workbook => { // Make edits. workbook.sheet(0).cell("A1").value("foo"); - + // Get the output return workbook.outputAsync(); }) .then(data => { // Set the output file name. res.attachment("output.xlsx"); - + // Send the workbook. res.send(data); }) @@ -591,7 +591,7 @@ workbook.toFileAsync("./out.xlsx", { password: "S3cret!" }); ``` The password option is supported in all output methods. N.B. Workbooks will only be encrypted if you supply a password when outputting even if they had a password when reading. -Encryption support is also available in the browser, but take care! Any password you put in browser code can be read by anyone with access to your code. You should only use passwords that are supplied by the end-user. Also, the performance of encryption/decryption in the browser is far worse than with Node.js. IE, in particular, is extremely slow. xlsx-populate is bundled for browsers with and without encryption support as the encryption libraries increase the size of the bundle a lot. +Encryption support is also available in the browser, but take care! Any password you put in browser code can be read by anyone with access to your code. You should only use passwords that are supplied by the end-user. Also, the performance of encryption/decryption in the browser is far worse than with Node.js. IE, in particular, is extremely slow. xlsx-populate is bundled for browsers with and without encryption support as the encryption libraries increase the size of the bundle a lot. ## Missing Features There are many, many features of the XLSX format that are not yet supported. If your use case needs something that isn't supported @@ -599,7 +599,7 @@ please open an issue to show your support. Better still, feel free to [contribut ## Submitting an Issue If you happen to run into a bug or an issue, please feel free to [submit an issue](https://github.com/dtjohnson/xlsx-populate/issues). I only ask that you please include sample JavaScript code that demonstrates the issue. -If the problem lies with modifying some template, it is incredibly difficult to debug the issue without the template. So please attach the template if possible. If you have confidentiality concerns, please attach a different workbook that exhibits the issue or you can send your workbook directly to [dtjohnson](https://github.com/dtjohnson) after creating the issue. +If the problem lies with modifying some template, it is incredibly difficult to debug the issue without the template. So please attach the template if possible. If you have confidentiality concerns, please attach a different workbook that exhibits the issue or you can send your workbook directly to [dtjohnson](https://github.com/dtjohnson) after creating the issue. ## Contributing @@ -660,7 +660,7 @@ To make sure your code is consistent and high quality, please make sure to follo * Make sure all tests pass successfully. * Whenever possible, do not modify/break existing API behavior. This module adheres to the [semantic versioning standard](https://docs.npmjs.com/getting-started/semantic-versioning). So any breaking changes will require a major release. * If your feature needs more documentation than just the JSDoc output, please add to the docs/template.md README file. - + ### Gulp Tasks @@ -829,7 +829,7 @@ An object representing a gradient fill. ### Cell A cell -**Kind**: global class +**Kind**: global class * [Cell](#Cell) * _instance_ @@ -844,7 +844,7 @@ A cell * [.formula()](#Cell+formula) ⇒ string * [.formula(formula)](#Cell+formula) ⇒ [Cell](#Cell) * [.hyperlink()](#Cell+hyperlink) ⇒ string \| undefined - * [.hyperlink(hyperlink)](#Cell+hyperlink) ⇒ [Cell](#Cell) + * [.hyperlink(hyperlink, [tooltip])](#Cell+hyperlink) ⇒ [Cell](#Cell) * [.dataValidation()](#Cell+dataValidation) ⇒ object \| undefined * [.dataValidation(dataValidation)](#Cell+dataValidation) ⇒ [Cell](#Cell) * [.tap(callback)](#Cell+tap) ⇒ [Cell](#Cell) @@ -873,15 +873,15 @@ A cell #### cell.active() ⇒ boolean Gets a value indicating whether the cell is the active cell in the sheet. -**Kind**: instance method of [Cell](#Cell) -**Returns**: boolean - True if active, false otherwise. +**Kind**: instance method of [Cell](#Cell) +**Returns**: boolean - True if active, false otherwise. #### cell.active(active) ⇒ [Cell](#Cell) Make the cell the active cell in the sheet. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -892,8 +892,8 @@ Make the cell the active cell in the sheet. #### cell.address([opts]) ⇒ string Get the address of the column. -**Kind**: instance method of [Cell](#Cell) -**Returns**: string - The address +**Kind**: instance method of [Cell](#Cell) +**Returns**: string - The address | Param | Type | Description | | --- | --- | --- | @@ -908,36 +908,36 @@ Get the address of the column. #### cell.column() ⇒ [Column](#Column) Gets the parent column of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Column](#Column) - The parent column. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Column](#Column) - The parent column. #### cell.clear() ⇒ [Cell](#Cell) Clears the contents from the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. #### cell.columnName() ⇒ number Gets the column name of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: number - The column name. +**Kind**: instance method of [Cell](#Cell) +**Returns**: number - The column name. #### cell.columnNumber() ⇒ number Gets the column number of the cell (1-based). -**Kind**: instance method of [Cell](#Cell) -**Returns**: number - The column number. +**Kind**: instance method of [Cell](#Cell) +**Returns**: number - The column number. #### cell.find(pattern, [replacement]) ⇒ boolean Find the given pattern in the cell and optionally replace it. -**Kind**: instance method of [Cell](#Cell) -**Returns**: boolean - A flag indicating if the pattern was found. +**Kind**: instance method of [Cell](#Cell) +**Returns**: boolean - A flag indicating if the pattern was found. | Param | Type | Description | | --- | --- | --- | @@ -949,15 +949,15 @@ Find the given pattern in the cell and optionally replace it. #### cell.formula() ⇒ string Gets the formula in the cell. Note that if a formula was set as part of a range, the getter will return 'SHARED'. This is a limitation that may be addressed in a future release. -**Kind**: instance method of [Cell](#Cell) -**Returns**: string - The formula in the cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: string - The formula in the cell. #### cell.formula(formula) ⇒ [Cell](#Cell) Sets the formula in the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -968,34 +968,35 @@ Sets the formula in the cell. #### cell.hyperlink() ⇒ string \| undefined Gets the hyperlink attached to the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: string \| undefined - The hyperlink or undefined if not set. +**Kind**: instance method of [Cell](#Cell) +**Returns**: string \| undefined - The hyperlink or undefined if not set. -#### cell.hyperlink(hyperlink) ⇒ [Cell](#Cell) +#### cell.hyperlink(hyperlink, [tooltip]) ⇒ [Cell](#Cell) Set or clear the hyperlink on the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | -| hyperlink | string \| undefined | The hyperlink to set or undefined to clear. | +| hyperlink | string \| object \| undefined | The hyperlink to set or undefined to clear. | +| [tooltip] | string | The tooltip to set for hyperlink. | #### cell.dataValidation() ⇒ object \| undefined Gets the data validation object attached to the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: object \| undefined - The data validation or undefined if not set. +**Kind**: instance method of [Cell](#Cell) +**Returns**: object \| undefined - The data validation or undefined if not set. #### cell.dataValidation(dataValidation) ⇒ [Cell](#Cell) Set or clear the data validation object of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1006,8 +1007,8 @@ Set or clear the data validation object of the cell. #### cell.tap(callback) ⇒ [Cell](#Cell) Invoke a callback on the cell and return the cell. Useful for method chaining. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1018,8 +1019,8 @@ Invoke a callback on the cell and return the cell. Useful for method chaining. #### cell.thru(callback) ⇒ \* Invoke a callback on the cell and return the value provided by the callback. Useful for method chaining. -**Kind**: instance method of [Cell](#Cell) -**Returns**: \* - The return value of the callback. +**Kind**: instance method of [Cell](#Cell) +**Returns**: \* - The return value of the callback. | Param | Type | Description | | --- | --- | --- | @@ -1030,8 +1031,8 @@ Invoke a callback on the cell and return the value provided by the callback. Use #### cell.rangeTo(cell) ⇒ [Range](#Range) Create a range from this cell and another. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1042,8 +1043,8 @@ Create a range from this cell and another. #### cell.relativeCell(rowOffset, columnOffset) ⇒ [Cell](#Cell) Returns a cell with a relative position given the offsets provided. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The relative cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The relative cell. | Param | Type | Description | | --- | --- | --- | @@ -1055,29 +1056,29 @@ Returns a cell with a relative position given the offsets provided. #### cell.row() ⇒ [Row](#Row) Gets the parent row of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Row](#Row) - The parent row. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Row](#Row) - The parent row. #### cell.rowNumber() ⇒ number Gets the row number of the cell (1-based). -**Kind**: instance method of [Cell](#Cell) -**Returns**: number - The row number. +**Kind**: instance method of [Cell](#Cell) +**Returns**: number - The row number. #### cell.sheet() ⇒ [Sheet](#Sheet) Gets the parent sheet. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Sheet](#Sheet) - The parent sheet. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Sheet](#Sheet) - The parent sheet. #### cell.style(name) ⇒ \* Gets an individual style. -**Kind**: instance method of [Cell](#Cell) -**Returns**: \* - The style. +**Kind**: instance method of [Cell](#Cell) +**Returns**: \* - The style. | Param | Type | Description | | --- | --- | --- | @@ -1088,8 +1089,8 @@ Gets an individual style. #### cell.style(names) ⇒ object.<string, \*> Gets multiple styles. -**Kind**: instance method of [Cell](#Cell) -**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. +**Kind**: instance method of [Cell](#Cell) +**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. | Param | Type | Description | | --- | --- | --- | @@ -1100,8 +1101,8 @@ Gets multiple styles. #### cell.style(name, value) ⇒ [Cell](#Cell) Sets an individual style. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1113,8 +1114,8 @@ Sets an individual style. #### cell.style(name) ⇒ [Range](#Range) Sets the styles in the range starting with the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Range](#Range) - The range that was set. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Range](#Range) - The range that was set. | Param | Type | Description | | --- | --- | --- | @@ -1126,8 +1127,8 @@ Sets the styles in the range starting with the cell. #### cell.style(styles) ⇒ [Cell](#Cell) Sets multiple styles. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1138,8 +1139,8 @@ Sets multiple styles. #### cell.style(style) ⇒ [Cell](#Cell) Sets to a specific style -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1150,15 +1151,15 @@ Sets to a specific style #### cell.value() ⇒ string \| boolean \| number \| Date \| undefined Gets the value of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: string \| boolean \| number \| Date \| undefined - The value of the cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: string \| boolean \| number \| Date \| undefined - The value of the cell. #### cell.value(value) ⇒ [Cell](#Cell) Sets the value of the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1169,8 +1170,8 @@ Sets the value of the cell. #### cell.value() ⇒ [Range](#Range) Sets the values in the range starting with the cell. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Range](#Range) - The range that was set. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Range](#Range) - The range that was set. | Param | Type | Description | | --- | --- | --- | @@ -1181,14 +1182,14 @@ Sets the values in the range starting with the cell. #### cell.workbook() ⇒ [Workbook](#Workbook) Gets the parent workbook. -**Kind**: instance method of [Cell](#Cell) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Workbook](#Workbook) - The parent workbook. #### Cell~tapCallback ⇒ undefined Callback used by tap. -**Kind**: inner typedef of [Cell](#Cell) +**Kind**: inner typedef of [Cell](#Cell) | Param | Type | Description | | --- | --- | --- | @@ -1199,8 +1200,8 @@ Callback used by tap. #### Cell~thruCallback ⇒ \* Callback used by thru. -**Kind**: inner typedef of [Cell](#Cell) -**Returns**: \* - The value to return from thru. +**Kind**: inner typedef of [Cell](#Cell) +**Returns**: \* - The value to return from thru. | Param | Type | Description | | --- | --- | --- | @@ -1211,7 +1212,7 @@ Callback used by thru. ### Column A column. -**Kind**: global class +**Kind**: global class * [Column](#Column) * [.address([opts])](#Column+address) ⇒ string @@ -1235,8 +1236,8 @@ A column. #### column.address([opts]) ⇒ string Get the address of the column. -**Kind**: instance method of [Column](#Column) -**Returns**: string - The address +**Kind**: instance method of [Column](#Column) +**Returns**: string - The address | Param | Type | Description | | --- | --- | --- | @@ -1249,8 +1250,8 @@ Get the address of the column. #### column.cell(rowNumber) ⇒ [Cell](#Cell) Get a cell within the column. -**Kind**: instance method of [Column](#Column) -**Returns**: [Cell](#Cell) - The cell in the column with the given row number. +**Kind**: instance method of [Column](#Column) +**Returns**: [Cell](#Cell) - The cell in the column with the given row number. | Param | Type | Description | | --- | --- | --- | @@ -1261,29 +1262,29 @@ Get a cell within the column. #### column.columnName() ⇒ string Get the name of the column. -**Kind**: instance method of [Column](#Column) -**Returns**: string - The column name. +**Kind**: instance method of [Column](#Column) +**Returns**: string - The column name. #### column.columnNumber() ⇒ number Get the number of the column. -**Kind**: instance method of [Column](#Column) -**Returns**: number - The column number. +**Kind**: instance method of [Column](#Column) +**Returns**: number - The column number. #### column.hidden() ⇒ boolean Gets a value indicating whether the column is hidden. -**Kind**: instance method of [Column](#Column) -**Returns**: boolean - A flag indicating whether the column is hidden. +**Kind**: instance method of [Column](#Column) +**Returns**: boolean - A flag indicating whether the column is hidden. #### column.hidden(hidden) ⇒ [Column](#Column) Sets whether the column is hidden. -**Kind**: instance method of [Column](#Column) -**Returns**: [Column](#Column) - The column. +**Kind**: instance method of [Column](#Column) +**Returns**: [Column](#Column) - The column. | Param | Type | Description | | --- | --- | --- | @@ -1294,15 +1295,15 @@ Sets whether the column is hidden. #### column.sheet() ⇒ [Sheet](#Sheet) Get the parent sheet. -**Kind**: instance method of [Column](#Column) -**Returns**: [Sheet](#Sheet) - The parent sheet. +**Kind**: instance method of [Column](#Column) +**Returns**: [Sheet](#Sheet) - The parent sheet. #### column.style(name) ⇒ \* Gets an individual style. -**Kind**: instance method of [Column](#Column) -**Returns**: \* - The style. +**Kind**: instance method of [Column](#Column) +**Returns**: \* - The style. | Param | Type | Description | | --- | --- | --- | @@ -1313,8 +1314,8 @@ Gets an individual style. #### column.style(names) ⇒ object.<string, \*> Gets multiple styles. -**Kind**: instance method of [Column](#Column) -**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. +**Kind**: instance method of [Column](#Column) +**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. | Param | Type | Description | | --- | --- | --- | @@ -1325,8 +1326,8 @@ Gets multiple styles. #### column.style(name, value) ⇒ [Cell](#Cell) Sets an individual style. -**Kind**: instance method of [Column](#Column) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Column](#Column) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1338,8 +1339,8 @@ Sets an individual style. #### column.style(styles) ⇒ [Cell](#Cell) Sets multiple styles. -**Kind**: instance method of [Column](#Column) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Column](#Column) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1350,8 +1351,8 @@ Sets multiple styles. #### column.style(style) ⇒ [Cell](#Cell) Sets to a specific style -**Kind**: instance method of [Column](#Column) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Column](#Column) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1362,15 +1363,15 @@ Sets to a specific style #### column.width() ⇒ undefined \| number Gets the width. -**Kind**: instance method of [Column](#Column) -**Returns**: undefined \| number - The width (or undefined). +**Kind**: instance method of [Column](#Column) +**Returns**: undefined \| number - The width (or undefined). #### column.width(width) ⇒ [Column](#Column) Sets the width. -**Kind**: instance method of [Column](#Column) -**Returns**: [Column](#Column) - The column. +**Kind**: instance method of [Column](#Column) +**Returns**: [Column](#Column) - The column. | Param | Type | Description | | --- | --- | --- | @@ -1381,14 +1382,14 @@ Sets the width. #### column.workbook() ⇒ [Workbook](#Workbook) Get the parent workbook. -**Kind**: instance method of [Column](#Column) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Column](#Column) +**Returns**: [Workbook](#Workbook) - The parent workbook. ### FormulaError A formula error (e.g. #DIV/0!). -**Kind**: global class +**Kind**: global class * [FormulaError](#FormulaError) * _instance_ @@ -1407,56 +1408,56 @@ A formula error (e.g. #DIV/0!). #### formulaError.error() ⇒ string Get the error code. -**Kind**: instance method of [FormulaError](#FormulaError) -**Returns**: string - The error code. +**Kind**: instance method of [FormulaError](#FormulaError) +**Returns**: string - The error code. #### FormulaError.DIV0 : [FormulaError](#FormulaError) \#DIV/0! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.NA : [FormulaError](#FormulaError) \#N/A error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.NAME : [FormulaError](#FormulaError) \#NAME? error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.NULL : [FormulaError](#FormulaError) \#NULL! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.NUM : [FormulaError](#FormulaError) \#NUM! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.REF : [FormulaError](#FormulaError) \#REF! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) #### FormulaError.VALUE : [FormulaError](#FormulaError) \#VALUE! error. -**Kind**: static property of [FormulaError](#FormulaError) +**Kind**: static property of [FormulaError](#FormulaError) ### Range A range of cells. -**Kind**: global class +**Kind**: global class * [Range](#Range) * _instance_ @@ -1503,8 +1504,8 @@ A range of cells. #### range.address([opts]) ⇒ string Get the address of the range. -**Kind**: instance method of [Range](#Range) -**Returns**: string - The address. +**Kind**: instance method of [Range](#Range) +**Returns**: string - The address. | Param | Type | Description | | --- | --- | --- | @@ -1521,8 +1522,8 @@ Get the address of the range. #### range.cell(ri, ci) ⇒ [Cell](#Cell) Gets a cell within the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Range](#Range) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1534,36 +1535,36 @@ Gets a cell within the range. #### range.autoFilter() ⇒ [Range](#Range) Sets sheet autoFilter to this range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - This range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - This range. #### range.cells() ⇒ Array.<Array.<Cell>> Get the cells in the range as a 2D array. -**Kind**: instance method of [Range](#Range) -**Returns**: Array.<Array.<Cell>> - The cells. +**Kind**: instance method of [Range](#Range) +**Returns**: Array.<Array.<Cell>> - The cells. #### range.clear() ⇒ [Range](#Range) Clear the contents of all the cells in the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. #### range.endCell() ⇒ [Cell](#Cell) Get the end cell of the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Cell](#Cell) - The end cell. +**Kind**: instance method of [Range](#Range) +**Returns**: [Cell](#Cell) - The end cell. #### range.forEach(callback) ⇒ [Range](#Range) Call a function for each cell in the range. Goes by row then column. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1574,15 +1575,15 @@ Call a function for each cell in the range. Goes by row then column. #### range.formula() ⇒ string \| undefined Gets the shared formula in the start cell (assuming it's the source of the shared formula). -**Kind**: instance method of [Range](#Range) -**Returns**: string \| undefined - The shared formula. +**Kind**: instance method of [Range](#Range) +**Returns**: string \| undefined - The shared formula. #### range.formula(formula) ⇒ [Range](#Range) Sets the shared formula in the range. The formula will be translated for each cell. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1593,8 +1594,8 @@ Sets the shared formula in the range. The formula will be translated for each ce #### range.map(callback) ⇒ Array.<Array.<\*>> Creates a 2D array of values by running each cell through a callback. -**Kind**: instance method of [Range](#Range) -**Returns**: Array.<Array.<\*>> - The 2D array of return values. +**Kind**: instance method of [Range](#Range) +**Returns**: Array.<Array.<\*>> - The 2D array of return values. | Param | Type | Description | | --- | --- | --- | @@ -1605,15 +1606,15 @@ Creates a 2D array of values by running each cell through a callback. #### range.merged() ⇒ boolean Gets a value indicating whether the cells in the range are merged. -**Kind**: instance method of [Range](#Range) -**Returns**: boolean - The value. +**Kind**: instance method of [Range](#Range) +**Returns**: boolean - The value. #### range.merged(merged) ⇒ [Range](#Range) Sets a value indicating whether the cells in the range should be merged. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1624,15 +1625,15 @@ Sets a value indicating whether the cells in the range should be merged. #### range.dataValidation() ⇒ object \| undefined Gets the data validation object attached to the Range. -**Kind**: instance method of [Range](#Range) -**Returns**: object \| undefined - The data validation object or undefined if not set. +**Kind**: instance method of [Range](#Range) +**Returns**: object \| undefined - The data validation object or undefined if not set. #### range.dataValidation(dataValidation) ⇒ [Range](#Range) Set or clear the data validation object of the entire range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1643,8 +1644,8 @@ Set or clear the data validation object of the entire range. #### range.reduce(callback, [initialValue]) ⇒ \* Reduces the range to a single value accumulated from the result of a function called for each cell. -**Kind**: instance method of [Range](#Range) -**Returns**: \* - The accumulated value. +**Kind**: instance method of [Range](#Range) +**Returns**: \* - The accumulated value. | Param | Type | Description | | --- | --- | --- | @@ -1656,22 +1657,22 @@ Reduces the range to a single value accumulated from the result of a function ca #### range.sheet() ⇒ [Sheet](#Sheet) Gets the parent sheet of the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Sheet](#Sheet) - The parent sheet. +**Kind**: instance method of [Range](#Range) +**Returns**: [Sheet](#Sheet) - The parent sheet. #### range.startCell() ⇒ [Cell](#Cell) Gets the start cell of the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Cell](#Cell) - The start cell. +**Kind**: instance method of [Range](#Range) +**Returns**: [Cell](#Cell) - The start cell. #### range.style(name) ⇒ Array.<Array.<\*>> Gets a single style for each cell. -**Kind**: instance method of [Range](#Range) -**Returns**: Array.<Array.<\*>> - 2D array of style values. +**Kind**: instance method of [Range](#Range) +**Returns**: Array.<Array.<\*>> - 2D array of style values. | Param | Type | Description | | --- | --- | --- | @@ -1682,8 +1683,8 @@ Gets a single style for each cell. #### range.style(names) ⇒ Object.<string, Array.<Array.<\*>>> Gets multiple styles for each cell. -**Kind**: instance method of [Range](#Range) -**Returns**: Object.<string, Array.<Array.<\*>>> - Object whose keys are style names and values are 2D arrays of style values. +**Kind**: instance method of [Range](#Range) +**Returns**: Object.<string, Array.<Array.<\*>>> - Object whose keys are style names and values are 2D arrays of style values. | Param | Type | Description | | --- | --- | --- | @@ -1694,8 +1695,8 @@ Gets multiple styles for each cell. #### range.style(name) ⇒ [Range](#Range) Set the style in each cell to the result of a function called for each. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1707,8 +1708,8 @@ Set the style in each cell to the result of a function called for each. #### range.style(name) ⇒ [Range](#Range) Sets the style in each cell to the corresponding value in the given 2D array of values. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1720,8 +1721,8 @@ Sets the style in each cell to the corresponding value in the given 2D array of #### range.style(name, value) ⇒ [Range](#Range) Set the style of all cells in the range to a single style value. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1733,8 +1734,8 @@ Set the style of all cells in the range to a single style value. #### range.style(styles) ⇒ [Range](#Range) Set multiple styles for the cells in the range. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1745,8 +1746,8 @@ Set multiple styles for the cells in the range. #### range.style(style) ⇒ [Range](#Range) Sets to a specific style -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1757,8 +1758,8 @@ Sets to a specific style #### range.tap(callback) ⇒ [Range](#Range) Invoke a callback on the range and return the range. Useful for method chaining. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1769,8 +1770,8 @@ Invoke a callback on the range and return the range. Useful for method chaining. #### range.thru(callback) ⇒ \* Invoke a callback on the range and return the value provided by the callback. Useful for method chaining. -**Kind**: instance method of [Range](#Range) -**Returns**: \* - The return value of the callback. +**Kind**: instance method of [Range](#Range) +**Returns**: \* - The return value of the callback. | Param | Type | Description | | --- | --- | --- | @@ -1781,15 +1782,15 @@ Invoke a callback on the range and return the value provided by the callback. Us #### range.value() ⇒ Array.<Array.<\*>> Get the values of each cell in the range as a 2D array. -**Kind**: instance method of [Range](#Range) -**Returns**: Array.<Array.<\*>> - The values. +**Kind**: instance method of [Range](#Range) +**Returns**: Array.<Array.<\*>> - The values. #### range.value(callback) ⇒ [Range](#Range) Set the values in each cell to the result of a function called for each. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1800,8 +1801,8 @@ Set the values in each cell to the result of a function called for each. #### range.value(values) ⇒ [Range](#Range) Sets the value in each cell to the corresponding value in the given 2D array of values. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1812,8 +1813,8 @@ Sets the value in each cell to the corresponding value in the given 2D array of #### range.value(value) ⇒ [Range](#Range) Set the value of all cells in the range to a single value. -**Kind**: instance method of [Range](#Range) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Range](#Range) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -1824,14 +1825,14 @@ Set the value of all cells in the range to a single value. #### range.workbook() ⇒ [Workbook](#Workbook) Gets the parent workbook. -**Kind**: instance method of [Range](#Range) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Range](#Range) +**Returns**: [Workbook](#Workbook) - The parent workbook. #### Range~forEachCallback ⇒ undefined Callback used by forEach. -**Kind**: inner typedef of [Range](#Range) +**Kind**: inner typedef of [Range](#Range) | Param | Type | Description | | --- | --- | --- | @@ -1845,8 +1846,8 @@ Callback used by forEach. #### Range~mapCallback ⇒ \* Callback used by map. -**Kind**: inner typedef of [Range](#Range) -**Returns**: \* - The value to map to. +**Kind**: inner typedef of [Range](#Range) +**Returns**: \* - The value to map to. | Param | Type | Description | | --- | --- | --- | @@ -1860,8 +1861,8 @@ Callback used by map. #### Range~reduceCallback ⇒ \* Callback used by reduce. -**Kind**: inner typedef of [Range](#Range) -**Returns**: \* - The value to map to. +**Kind**: inner typedef of [Range](#Range) +**Returns**: \* - The value to map to. | Param | Type | Description | | --- | --- | --- | @@ -1876,7 +1877,7 @@ Callback used by reduce. #### Range~tapCallback ⇒ undefined Callback used by tap. -**Kind**: inner typedef of [Range](#Range) +**Kind**: inner typedef of [Range](#Range) | Param | Type | Description | | --- | --- | --- | @@ -1887,8 +1888,8 @@ Callback used by tap. #### Range~thruCallback ⇒ \* Callback used by thru. -**Kind**: inner typedef of [Range](#Range) -**Returns**: \* - The value to return from thru. +**Kind**: inner typedef of [Range](#Range) +**Returns**: \* - The value to return from thru. | Param | Type | Description | | --- | --- | --- | @@ -1899,7 +1900,7 @@ Callback used by thru. ### Row A row. -**Kind**: global class +**Kind**: global class * [Row](#Row) * [.address([opts])](#Row+address) ⇒ string @@ -1922,8 +1923,8 @@ A row. #### row.address([opts]) ⇒ string Get the address of the row. -**Kind**: instance method of [Row](#Row) -**Returns**: string - The address +**Kind**: instance method of [Row](#Row) +**Returns**: string - The address | Param | Type | Description | | --- | --- | --- | @@ -1936,8 +1937,8 @@ Get the address of the row. #### row.cell(columnNameOrNumber) ⇒ [Cell](#Cell) Get a cell in the row. -**Kind**: instance method of [Row](#Row) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Row](#Row) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -1948,15 +1949,15 @@ Get a cell in the row. #### row.height() ⇒ undefined \| number Gets the row height. -**Kind**: instance method of [Row](#Row) -**Returns**: undefined \| number - The height (or undefined). +**Kind**: instance method of [Row](#Row) +**Returns**: undefined \| number - The height (or undefined). #### row.height(height) ⇒ [Row](#Row) Sets the row height. -**Kind**: instance method of [Row](#Row) -**Returns**: [Row](#Row) - The row. +**Kind**: instance method of [Row](#Row) +**Returns**: [Row](#Row) - The row. | Param | Type | Description | | --- | --- | --- | @@ -1967,15 +1968,15 @@ Sets the row height. #### row.hidden() ⇒ boolean Gets a value indicating whether the row is hidden. -**Kind**: instance method of [Row](#Row) -**Returns**: boolean - A flag indicating whether the row is hidden. +**Kind**: instance method of [Row](#Row) +**Returns**: boolean - A flag indicating whether the row is hidden. #### row.hidden(hidden) ⇒ [Row](#Row) Sets whether the row is hidden. -**Kind**: instance method of [Row](#Row) -**Returns**: [Row](#Row) - The row. +**Kind**: instance method of [Row](#Row) +**Returns**: [Row](#Row) - The row. | Param | Type | Description | | --- | --- | --- | @@ -1986,22 +1987,22 @@ Sets whether the row is hidden. #### row.rowNumber() ⇒ number Gets the row number. -**Kind**: instance method of [Row](#Row) -**Returns**: number - The row number. +**Kind**: instance method of [Row](#Row) +**Returns**: number - The row number. #### row.sheet() ⇒ [Sheet](#Sheet) Gets the parent sheet of the row. -**Kind**: instance method of [Row](#Row) -**Returns**: [Sheet](#Sheet) - The parent sheet. +**Kind**: instance method of [Row](#Row) +**Returns**: [Sheet](#Sheet) - The parent sheet. #### row.style(name) ⇒ \* Gets an individual style. -**Kind**: instance method of [Row](#Row) -**Returns**: \* - The style. +**Kind**: instance method of [Row](#Row) +**Returns**: \* - The style. | Param | Type | Description | | --- | --- | --- | @@ -2012,8 +2013,8 @@ Gets an individual style. #### row.style(names) ⇒ object.<string, \*> Gets multiple styles. -**Kind**: instance method of [Row](#Row) -**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. +**Kind**: instance method of [Row](#Row) +**Returns**: object.<string, \*> - Object whose keys are the style names and values are the styles. | Param | Type | Description | | --- | --- | --- | @@ -2024,8 +2025,8 @@ Gets multiple styles. #### row.style(name, value) ⇒ [Cell](#Cell) Sets an individual style. -**Kind**: instance method of [Row](#Row) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Row](#Row) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2037,8 +2038,8 @@ Sets an individual style. #### row.style(styles) ⇒ [Cell](#Cell) Sets multiple styles. -**Kind**: instance method of [Row](#Row) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Row](#Row) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2049,8 +2050,8 @@ Sets multiple styles. #### row.style(style) ⇒ [Cell](#Cell) Sets to a specific style -**Kind**: instance method of [Row](#Row) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Row](#Row) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2061,14 +2062,14 @@ Sets to a specific style #### row.workbook() ⇒ [Workbook](#Workbook) Get the parent workbook. -**Kind**: instance method of [Row](#Row) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Row](#Row) +**Returns**: [Workbook](#Workbook) - The parent workbook. ### Sheet A worksheet. -**Kind**: global class +**Kind**: global class * [Sheet](#Sheet) * [.active()](#Sheet+active) ⇒ boolean @@ -2108,15 +2109,15 @@ A worksheet. #### sheet.active() ⇒ boolean Gets a value indicating whether the sheet is the active sheet in the workbook. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: boolean - True if active, false otherwise. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: boolean - True if active, false otherwise. #### sheet.active(active) ⇒ [Sheet](#Sheet) Make the sheet the active sheet in the workkbok. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2127,15 +2128,15 @@ Make the sheet the active sheet in the workkbok. #### sheet.activeCell() ⇒ [Cell](#Cell) Get the active cell in the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Cell](#Cell) - The active cell. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Cell](#Cell) - The active cell. #### sheet.activeCell(cell) ⇒ [Sheet](#Sheet) Set the active cell in the workbook. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2146,8 +2147,8 @@ Set the active cell in the workbook. #### sheet.activeCell(rowNumber, columnNameOrNumber) ⇒ [Sheet](#Sheet) Set the active cell in the workbook by row and column. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2159,8 +2160,8 @@ Set the active cell in the workbook by row and column. #### sheet.cell(address) ⇒ [Cell](#Cell) Gets the cell with the given address. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2171,8 +2172,8 @@ Gets the cell with the given address. #### sheet.cell(rowNumber, columnNameOrNumber) ⇒ [Cell](#Cell) Gets the cell with the given row and column numbers. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Cell](#Cell) - The cell. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Cell](#Cell) - The cell. | Param | Type | Description | | --- | --- | --- | @@ -2184,8 +2185,8 @@ Gets the cell with the given row and column numbers. #### sheet.column(columnNameOrNumber) ⇒ [Column](#Column) Gets a column in the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Column](#Column) - The column. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Column](#Column) - The column. | Param | Type | Description | | --- | --- | --- | @@ -2196,8 +2197,8 @@ Gets a column in the sheet. #### sheet.definedName(name) ⇒ undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) Gets a defined name scoped to the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) - What the defined name refers to or undefined if not found. Will return the string formula if not a Row, Column, Cell, or Range. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) - What the defined name refers to or undefined if not found. Will return the string formula if not a Row, Column, Cell, or Range. | Param | Type | Description | | --- | --- | --- | @@ -2208,8 +2209,8 @@ Gets a defined name scoped to the sheet. #### sheet.definedName(name, refersTo) ⇒ [Workbook](#Workbook) Set a defined name scoped to the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2221,15 +2222,15 @@ Set a defined name scoped to the sheet. #### sheet.delete() ⇒ [Workbook](#Workbook) Deletes the sheet and returns the parent workbook. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Workbook](#Workbook) - The workbook. #### sheet.find(pattern, [replacement]) ⇒ [Array.<Cell>](#Cell) Find the given pattern in the sheet and optionally replace it. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Array.<Cell>](#Cell) - The matching cells. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Array.<Cell>](#Cell) - The matching cells. | Param | Type | Description | | --- | --- | --- | @@ -2241,15 +2242,15 @@ Find the given pattern in the sheet and optionally replace it. #### sheet.gridLinesVisible() ⇒ boolean Gets a value indicating whether this sheet's grid lines are visible. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: boolean - True if selected, false if not. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: boolean - True if selected, false if not. #### sheet.gridLinesVisible(selected) ⇒ [Sheet](#Sheet) Sets whether this sheet's grid lines are visible. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2260,15 +2261,15 @@ Sets whether this sheet's grid lines are visible. #### sheet.hidden() ⇒ boolean \| string Gets a value indicating if the sheet is hidden or not. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: boolean \| string - True if hidden, false if visible, and 'very' if very hidden. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: boolean \| string - True if hidden, false if visible, and 'very' if very hidden. #### sheet.hidden(hidden) ⇒ [Sheet](#Sheet) Set whether the sheet is hidden or not. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2279,8 +2280,8 @@ Set whether the sheet is hidden or not. #### sheet.move([indexOrBeforeSheet]) ⇒ [Sheet](#Sheet) Move the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2291,15 +2292,15 @@ Move the sheet. #### sheet.name() ⇒ string Get the name of the sheet. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: string - The sheet name. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: string - The sheet name. #### sheet.name(name) ⇒ [Sheet](#Sheet) Set the name of the sheet. *Note: this method does not rename references to the sheet so formulas, etc. can be broken. Use with caution!* -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2310,8 +2311,8 @@ Set the name of the sheet. *Note: this method does not rename references to the #### sheet.range(address) ⇒ [Range](#Range) Gets a range from the given range address. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -2322,8 +2323,8 @@ Gets a range from the given range address. #### sheet.range(startCell, endCell) ⇒ [Range](#Range) Gets a range from the given cells or cell addresses. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -2335,8 +2336,8 @@ Gets a range from the given cells or cell addresses. #### sheet.range(startRowNumber, startColumnNameOrNumber, endRowNumber, endColumnNameOrNumber) ⇒ [Range](#Range) Gets a range from the given row numbers and column names or numbers. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Range](#Range) - The range. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Range](#Range) - The range. | Param | Type | Description | | --- | --- | --- | @@ -2350,15 +2351,15 @@ Gets a range from the given row numbers and column names or numbers. #### sheet.autoFilter() ⇒ [Sheet](#Sheet) Unsets sheet autoFilter. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - This sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - This sheet. #### sheet.autoFilter(range) ⇒ [Sheet](#Sheet) Sets sheet autoFilter to a Range. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - This sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - This sheet. | Param | Type | Description | | --- | --- | --- | @@ -2369,8 +2370,8 @@ Sets sheet autoFilter to a Range. #### sheet.row(rowNumber) ⇒ [Row](#Row) Gets the row with the given number. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Row](#Row) - The row with the given number. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Row](#Row) - The row with the given number. | Param | Type | Description | | --- | --- | --- | @@ -2381,29 +2382,29 @@ Gets the row with the given number. #### sheet.tabColor() ⇒ undefined \| Color Get the tab color. (See style [Color](#color).) -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: undefined \| Color - The color or undefined if not set. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: undefined \| Color - The color or undefined if not set. #### sheet.tabColor() ⇒ Color \| string \| number Sets the tab color. (See style [Color](#color).) -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: Color \| string \| number - color - Color of the tab. If string, will set an RGB color. If number, will set a theme color. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: Color \| string \| number - color - Color of the tab. If string, will set an RGB color. If number, will set a theme color. #### sheet.tabSelected() ⇒ boolean Gets a value indicating whether this sheet is selected. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: boolean - True if selected, false if not. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: boolean - True if selected, false if not. #### sheet.tabSelected(selected) ⇒ [Sheet](#Sheet) Sets whether this sheet is selected. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Sheet](#Sheet) - The sheet. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. | Param | Type | Description | | --- | --- | --- | @@ -2414,21 +2415,21 @@ Sets whether this sheet is selected. #### sheet.usedRange() ⇒ [Range](#Range) \| undefined Get the range of cells in the sheet that have contained a value or style at any point. Useful for extracting the entire sheet contents. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Range](#Range) \| undefined - The used range or undefined if no cells in the sheet are used. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Range](#Range) \| undefined - The used range or undefined if no cells in the sheet are used. #### sheet.workbook() ⇒ [Workbook](#Workbook) Gets the parent workbook. -**Kind**: instance method of [Sheet](#Sheet) -**Returns**: [Workbook](#Workbook) - The parent workbook. +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Workbook](#Workbook) - The parent workbook. ### Workbook A workbook. -**Kind**: global class +**Kind**: global class * [Workbook](#Workbook) * [.activeSheet()](#Workbook+activeSheet) ⇒ [Sheet](#Sheet) @@ -2455,15 +2456,15 @@ A workbook. #### workbook.activeSheet() ⇒ [Sheet](#Sheet) Get the active sheet in the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Sheet](#Sheet) - The active sheet. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Sheet](#Sheet) - The active sheet. #### workbook.activeSheet(sheet) ⇒ [Workbook](#Workbook) Set the active sheet in the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2474,8 +2475,8 @@ Set the active sheet in the workbook. #### workbook.addSheet(name, [indexOrBeforeSheet]) ⇒ [Sheet](#Sheet) Add a new sheet to the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Sheet](#Sheet) - The new sheet. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Sheet](#Sheet) - The new sheet. | Param | Type | Description | | --- | --- | --- | @@ -2487,8 +2488,8 @@ Add a new sheet to the workbook. #### workbook.definedName(name) ⇒ undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) Gets a defined name scoped to the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) - What the defined name refers to or undefined if not found. Will return the string formula if not a Row, Column, Cell, or Range. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: undefined \| string \| [Cell](#Cell) \| [Range](#Range) \| [Row](#Row) \| [Column](#Column) - What the defined name refers to or undefined if not found. Will return the string formula if not a Row, Column, Cell, or Range. | Param | Type | Description | | --- | --- | --- | @@ -2499,8 +2500,8 @@ Gets a defined name scoped to the workbook. #### workbook.definedName(name, refersTo) ⇒ [Workbook](#Workbook) Set a defined name scoped to the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2512,8 +2513,8 @@ Set a defined name scoped to the workbook. #### workbook.deleteSheet(sheet) ⇒ [Workbook](#Workbook) Delete a sheet from the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2524,8 +2525,8 @@ Delete a sheet from the workbook. #### workbook.find(pattern, [replacement]) ⇒ boolean Find the given pattern in the workbook and optionally replace it. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: boolean - A flag indicating if the pattern was found. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: boolean - A flag indicating if the pattern was found. | Param | Type | Description | | --- | --- | --- | @@ -2537,8 +2538,8 @@ Find the given pattern in the workbook and optionally replace it. #### workbook.moveSheet(sheet, [indexOrBeforeSheet]) ⇒ [Workbook](#Workbook) Move a sheet to a new position. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2550,8 +2551,8 @@ Move a sheet to a new position. #### workbook.outputAsync([type]) ⇒ string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer Generates the workbook output. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer - The data. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer - The data. | Param | Type | Description | | --- | --- | --- | @@ -2562,8 +2563,8 @@ Generates the workbook output. #### workbook.outputAsync([opts]) ⇒ string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer Generates the workbook output. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer - The data. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: string \| Uint8Array \| ArrayBuffer \| Blob \| Buffer - The data. | Param | Type | Description | | --- | --- | --- | @@ -2576,8 +2577,8 @@ Generates the workbook output. #### workbook.sheet(sheetNameOrIndex) ⇒ [Sheet](#Sheet) \| undefined Gets the sheet with the provided name or index (0-based). -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Sheet](#Sheet) \| undefined - The sheet or undefined if not found. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Sheet](#Sheet) \| undefined - The sheet or undefined if not found. | Param | Type | Description | | --- | --- | --- | @@ -2588,15 +2589,15 @@ Gets the sheet with the provided name or index (0-based). #### workbook.sheets() ⇒ [Array.<Sheet>](#Sheet) Get an array of all the sheets in the workbook. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Array.<Sheet>](#Sheet) - The sheets. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Array.<Sheet>](#Sheet) - The sheets. #### workbook.property(name) ⇒ \* Gets an individual property. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: \* - The property. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: \* - The property. | Param | Type | Description | | --- | --- | --- | @@ -2607,8 +2608,8 @@ Gets an individual property. #### workbook.property(names) ⇒ object.<string, \*> Gets multiple properties. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: object.<string, \*> - Object whose keys are the property names and values are the properties. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: object.<string, \*> - Object whose keys are the property names and values are the properties. | Param | Type | Description | | --- | --- | --- | @@ -2619,8 +2620,8 @@ Gets multiple properties. #### workbook.property(name, value) ⇒ [Workbook](#Workbook) Sets an individual property. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2632,8 +2633,8 @@ Sets an individual property. #### workbook.property(properties) ⇒ [Workbook](#Workbook) Sets multiple properties. -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: [Workbook](#Workbook) - The workbook. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: [Workbook](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2644,15 +2645,15 @@ Sets multiple properties. #### workbook.properties() ⇒ CoreProperties Get access to core properties object -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: CoreProperties - The core properties. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: CoreProperties - The core properties. #### workbook.toFileAsync(path, [opts]) ⇒ Promise.<undefined> Write the workbook to file. (Not supported in browsers.) -**Kind**: instance method of [Workbook](#Workbook) -**Returns**: Promise.<undefined> - A promise. +**Kind**: instance method of [Workbook](#Workbook) +**Returns**: Promise.<undefined> - A promise. | Param | Type | Description | | --- | --- | --- | @@ -2663,7 +2664,7 @@ Write the workbook to file. (Not supported in browsers.) ### XlsxPopulate : object -**Kind**: global namespace +**Kind**: global namespace * [XlsxPopulate](#XlsxPopulate) : object * [.Promise](#XlsxPopulate.Promise) : Promise @@ -2680,26 +2681,26 @@ Write the workbook to file. (Not supported in browsers.) #### XlsxPopulate.Promise : Promise The Promise library. -**Kind**: static property of [XlsxPopulate](#XlsxPopulate) +**Kind**: static property of [XlsxPopulate](#XlsxPopulate) #### XlsxPopulate.MIME_TYPE : string The XLSX mime type. -**Kind**: static property of [XlsxPopulate](#XlsxPopulate) +**Kind**: static property of [XlsxPopulate](#XlsxPopulate) #### XlsxPopulate.FormulaError : [FormulaError](#FormulaError) Formula error class. -**Kind**: static property of [XlsxPopulate](#XlsxPopulate) +**Kind**: static property of [XlsxPopulate](#XlsxPopulate) #### XlsxPopulate.dateToNumber(date) ⇒ number Convert a date to a number for Excel. -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: number - The number. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: number - The number. | Param | Type | Description | | --- | --- | --- | @@ -2710,15 +2711,15 @@ Convert a date to a number for Excel. #### XlsxPopulate.fromBlankAsync() ⇒ [Promise.<Workbook>](#Workbook) Create a new blank workbook. -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. #### XlsxPopulate.fromDataAsync(data, [opts]) ⇒ [Promise.<Workbook>](#Workbook) Loads a workbook from a data object. (Supports any supported [JSZip data types](https://stuk.github.io/jszip/documentation/api_jszip/load_async.html).) -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2731,8 +2732,8 @@ Loads a workbook from a data object. (Supports any supported [JSZip data types]( #### XlsxPopulate.fromFileAsync(path, [opts]) ⇒ [Promise.<Workbook>](#Workbook) Loads a workbook from file. -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: [Promise.<Workbook>](#Workbook) - The workbook. | Param | Type | Description | | --- | --- | --- | @@ -2745,8 +2746,8 @@ Loads a workbook from file. #### XlsxPopulate.numberToDate(number) ⇒ Date Convert an Excel number to a date. -**Kind**: static method of [XlsxPopulate](#XlsxPopulate) -**Returns**: Date - The date. +**Kind**: static method of [XlsxPopulate](#XlsxPopulate) +**Returns**: Date - The date. | Param | Type | Description | | --- | --- | --- | @@ -2761,5 +2762,5 @@ https://msdn.microsoft.com/en-us/library/dd950165(v=office.12).aspx Helpful guidance also take from this Github project: https://github.com/nolze/ms-offcrypto-tool -**Kind**: global constant +**Kind**: global constant From dbc04fc535c0e7ed8eaef581590a77bf444c001d Mon Sep 17 00:00:00 2001 From: Eddie Corrigall Date: Sun, 13 Jan 2019 23:06:19 -0500 Subject: [PATCH 08/13] Refactor hyperlinks and add tests --- docs/template.md | 9 ++++----- lib/Cell.js | 11 +++++++---- lib/Sheet.js | 15 +++++++++------ test/unit/Cell.spec.js | 5 +++-- test/unit/Sheet.spec.js | 30 ++++++++++++++++++++++++++++++ 5 files changed, 53 insertions(+), 17 deletions(-) diff --git a/docs/template.md b/docs/template.md index b6c848f7..8a761dcf 100644 --- a/docs/template.md +++ b/docs/template.md @@ -438,17 +438,16 @@ cell.value("Link Text") .hyperlink("http://example.com"); // Set a hyperlink with tooltip -cell.value("Link Text") - .style({ fontColor: "0563c1", underline: true }) - .hyperlink("http://example.com", "example.com"); - -// Set a hyperlink with tooltip by object cell.value("Link Text") .style({ fontColor: "0563c1", underline: true }) .hyperlink({ hyperlink: "http://example.com", tooltip: "example.com" }); // Get the hyperlink const value = cell.hyperlink(); // Returns 'http://example.com' + +// Set a hyperlink to email +cell.value("Click to Email Jeff Bezos") + .hyperlink({ email: "jeff@amazon.com", emailSubject: "I know you're a busy man Jeff, but..." }); ``` ### Serving from Express diff --git a/lib/Cell.js b/lib/Cell.js index 2d60f6f2..2041a213 100644 --- a/lib/Cell.js +++ b/lib/Cell.js @@ -168,8 +168,11 @@ class Cell { * @returns {Cell} The cell. *//* * Set the hyperlink options on the cell. - * @param {string} hyperlink - The hyperlink to set. - * @param {object} opts - Options. + * @param {{}}} opts - Options. + * @param {string|Cell} [opts.hyperlink] - The hyperlink to set, if an instance of Cell the hyperlink is internal. + * @param {string} [opts.tooltip] - Additional text to help the user understand more about the hyperlink. + * @param {string} [opts.email] - Email address. + * @param {string} [opts.emailSubject] - Email subject. * @returns {Cell} The cell. */ hyperlink() { @@ -181,8 +184,8 @@ class Cell { this.sheet().hyperlink(this.address(), hyperlink); return this; }) - .case(['string', 'object'], (hyperlink, opts) => { - this.sheet().hyperlink(this.address(), hyperlink, opts); + .case(['object'], opts => { + this.sheet().hyperlink(this.address(), opts); return this; }) .handle(arguments); diff --git a/lib/Sheet.js b/lib/Sheet.js index 950d2bed..69e959fb 100644 --- a/lib/Sheet.js +++ b/lib/Sheet.js @@ -564,10 +564,10 @@ class Sheet { *//** * Set the hyperlink attached to the cell with the given address and options. * @param {string} address - The address of the hyperlinked cell. - * @param {string} hyperlink - The hyperlink to set. * @param {{}}} opts - Options. + * @param {string|Cell} [opts.hyperlink] - The hyperlink to set, if an instance of Cell the hyperlink is the internal address. * @param {string} [opts.tooltip] - Additional text to help the user understand more about the hyperlink. - * @param {string} [opts.email] - Email address. + * @param {string} [opts.email] - Email address, if set then the hyperlink proprties is ignored. * @param {string} [opts.emailSubject] - Email subject. * @returns {Sheet} The sheet. * @ignore @@ -581,15 +581,18 @@ class Sheet { return relationship && relationship.attributes.Target; }) .case(['string', 'nil'], address => { - delete this._hyperlinks[address]; // TODO: delete relationship + delete this._hyperlinks[address]; return this; }) .case(['string', 'string'], (address, hyperlink) => { - return this.hyperlink(address, { hyperlink: hyperlink }); + const opts = {}; + opts.hyperlink = hyperlink; + return this.hyperlink(address, opts); }) - .case(['string', 'string', 'object'], (address, hyperlink, opts) => { + .case(['string', 'object'], (address, opts) => { let isHyperlinkInternalAddress = false; + let hyperlink = opts.hyperlink; if (hyperlink instanceof Cell) { isHyperlinkInternalAddress = true; hyperlink = hyperlink.address({ includeSheetName: true }); @@ -616,7 +619,7 @@ class Sheet { }; } if (opts.tooltip) { - hyperlinkAttributes.tooltip = tooltip; + hyperlinkAttributes.tooltip = opts.tooltip; } this._hyperlinks[address] = { name: 'hyperlink', diff --git a/test/unit/Cell.spec.js b/test/unit/Cell.spec.js index aa330e73..909e173f 100644 --- a/test/unit/Cell.spec.js +++ b/test/unit/Cell.spec.js @@ -203,8 +203,9 @@ describe("Cell", () => { }); it("should set the hyperlink with tooltip on the sheet", () => { - expect(cell.hyperlink("HYPERLINK", "TOOLTIP")).toBe(cell); - expect(sheet.hyperlink).toHaveBeenCalledWith("C7", "HYPERLINK", "TOOLTIP"); + const opts = { hyperlink: "HYPERLINK", tooltip: "TOOLTIP" }; + expect(cell.hyperlink(opts)).toBe(cell); + expect(sheet.hyperlink).toHaveBeenCalledWith("C7", opts); }); }); diff --git a/test/unit/Sheet.spec.js b/test/unit/Sheet.spec.js index 72fad56b..95c938dd 100644 --- a/test/unit/Sheet.spec.js +++ b/test/unit/Sheet.spec.js @@ -806,6 +806,36 @@ describe("Sheet", () => { sheet.hyperlink("ADDRESS2", undefined); expect(sheet._hyperlinks).toEqualJson({}); }); + + it("should set the hyperlink and the tooltip on the sheet", () => { + const opts = { + hyperlink: "HYPERLINK", + tooltip: "TOOLTIP" + }; + const hyperlink = "HYPERLINK"; + expect(sheet.hyperlink("ADDRESS", opts)).toBe(sheet); + expect(sheet._hyperlinks["ADDRESS"].attributes).toEqualJson({ + ref: "ADDRESS", + "r:id": "ID", + tooltip: "TOOLTIP" + }); + expect(sheet._relationships.add).toHaveBeenCalledWith("hyperlink", hyperlink, "External"); + }); + + it("should set the hyperlink as an email on the sheet", () => { + const opts = { + hyperlink: "HYPERLINK", + email: "USER@SERVER.COM", + emailSubject: "EMAIL SUBJECT" + }; + const hyperlink = "mailto:USER@SERVER.COM?subject=EMAIL%20SUBJECT"; + expect(sheet.hyperlink("ADDRESS", opts)).toBe(sheet); + expect(sheet._hyperlinks["ADDRESS"].attributes).toEqualJson({ + ref: "ADDRESS", + "r:id": "ID" + }); + expect(sheet._relationships.add).toHaveBeenCalledWith("hyperlink", hyperlink, "External"); + }); }); describe("incrementMaxSharedFormulaId", () => { From 9fd7261ee91471f23e8e014ba979693d147e6426 Mon Sep 17 00:00:00 2001 From: Eddie Corrigall Date: Mon, 14 Jan 2019 11:38:53 -0500 Subject: [PATCH 09/13] Simplify Sheet.hyperlink and add unit tests --- lib/Cell.js | 2 +- lib/Sheet.js | 57 ++++++++++++++++++++++------------------- test/unit/Sheet.spec.js | 30 ++++++++++++++++++++-- 3 files changed, 59 insertions(+), 30 deletions(-) diff --git a/lib/Cell.js b/lib/Cell.js index 2041a213..c69fcc2e 100644 --- a/lib/Cell.js +++ b/lib/Cell.js @@ -164,7 +164,7 @@ class Cell { * @returns {string|undefined} The hyperlink or undefined if not set. *//** * Set or clear the hyperlink on the cell. - * @param {string|undefined} hyperlink - The hyperlink to set or undefined to clear. + * @param {string|Cell|undefined} hyperlink - The hyperlink to set or undefined to clear. * @returns {Cell} The cell. *//* * Set the hyperlink options on the cell. diff --git a/lib/Sheet.js b/lib/Sheet.js index 69e959fb..ad7e4c84 100644 --- a/lib/Sheet.js +++ b/lib/Sheet.js @@ -565,10 +565,10 @@ class Sheet { * Set the hyperlink attached to the cell with the given address and options. * @param {string} address - The address of the hyperlinked cell. * @param {{}}} opts - Options. - * @param {string|Cell} [opts.hyperlink] - The hyperlink to set, if an instance of Cell the hyperlink is the internal address. + * @param {string|Cell} [opts.hyperlink] - The hyperlink to set, can be a Cell or an internal/external string. * @param {string} [opts.tooltip] - Additional text to help the user understand more about the hyperlink. - * @param {string} [opts.email] - Email address, if set then the hyperlink proprties is ignored. - * @param {string} [opts.emailSubject] - Email subject. + * @param {string} [opts.email] - Email address, ignored if opts.hyperlink is set. + * @param {string} [opts.emailSubject] - Email subject, ignored if opts.hyperlink is set. * @returns {Sheet} The sheet. * @ignore */ @@ -586,48 +586,51 @@ class Sheet { return this; }) .case(['string', 'string'], (address, hyperlink) => { - const opts = {}; - opts.hyperlink = hyperlink; - return this.hyperlink(address, opts); + return this.hyperlink(address, hyperlink, false); }) - .case(['string', 'object'], (address, opts) => { - let isHyperlinkInternalAddress = false; - let hyperlink = opts.hyperlink; - if (hyperlink instanceof Cell) { - isHyperlinkInternalAddress = true; - hyperlink = hyperlink.address({ includeSheetName: true }); - } else if (typeof hyperlink === 'string') { - isHyperlinkInternalAddress = addressConverter.fromAddress(hyperlink); - } - if (opts.email) { - const email = opts.email; - const subject = opts.emailSubject || ''; - hyperlink = encodeURI(`mailto:${email}?subject=${subject}`); - } - let hyperlinkAttributes; + .case(['string', 'string', 'boolean'], (address, hyperlink, internal) => { + const isHyperlinkInternalAddress = internal || addressConverter.fromAddress(hyperlink); + let nodeAttributes; if (isHyperlinkInternalAddress) { - hyperlinkAttributes = { + nodeAttributes = { ref: address, location: hyperlink, display: hyperlink }; } else { const relationship = this._relationships.add("hyperlink", hyperlink, "External"); - hyperlinkAttributes = { + nodeAttributes = { ref: address, 'r:id': relationship.attributes.Id }; } - if (opts.tooltip) { - hyperlinkAttributes.tooltip = opts.tooltip; - } this._hyperlinks[address] = { name: 'hyperlink', - attributes: hyperlinkAttributes, + attributes: nodeAttributes, children: [] }; return this; }) + .case(['string', 'object'], (address, opts) => { + if (opts instanceof Cell) { + const cell = opts; + const hyperlink = cell.address({ includeSheetName: true }); + this.hyperlink(address, hyperlink, true); + } else if (opts.hyperlink) { + this.hyperlink(address, opts.hyperlink); + } else if (opts.email) { + const email = opts.email; + const subject = opts.emailSubject || ''; + this.hyperlink(address, encodeURI(`mailto:${email}?subject=${subject}`)); + } + const hyperlinkNode = this._hyperlinks[address]; + if (hyperlinkNode) { + if (opts.tooltip) { + hyperlinkNode.attributes.tooltip = opts.tooltip; + } + } + return this; + }) .handle(arguments); } diff --git a/test/unit/Sheet.spec.js b/test/unit/Sheet.spec.js index 95c938dd..362c4c60 100644 --- a/test/unit/Sheet.spec.js +++ b/test/unit/Sheet.spec.js @@ -786,6 +786,16 @@ describe("Sheet", () => { }); }); + it("should add an internal hyperlink entry", () => { + const hyperlink = "Sheet1!A1"; + expect(sheet.hyperlink("ADDRESS", hyperlink)).toBe(sheet); + expect(sheet._hyperlinks["ADDRESS"].attributes).toEqualJson({ + ref: "ADDRESS", + location: hyperlink, + display: hyperlink + }); + }); + it("should remove a hyperlink entry", () => { sheet._hyperlinks = { ADDRESS1: {}, @@ -805,6 +815,8 @@ describe("Sheet", () => { sheet.hyperlink("ADDRESS2", undefined); expect(sheet._hyperlinks).toEqualJson({}); + + // TODO: test that relationship is deleted }); it("should set the hyperlink and the tooltip on the sheet", () => { @@ -822,9 +834,8 @@ describe("Sheet", () => { expect(sheet._relationships.add).toHaveBeenCalledWith("hyperlink", hyperlink, "External"); }); - it("should set the hyperlink as an email on the sheet", () => { + it("should add a hyperlink entry using opts.email and opts.emailSubject", () => { const opts = { - hyperlink: "HYPERLINK", email: "USER@SERVER.COM", emailSubject: "EMAIL SUBJECT" }; @@ -836,6 +847,21 @@ describe("Sheet", () => { }); expect(sheet._relationships.add).toHaveBeenCalledWith("hyperlink", hyperlink, "External"); }); + + it("should add a hyperlink entry using opts.hyperlink and ignore opts.email and opts.emailSubject", () => { + const opts = { + hyperlink: "HYPERLINK", + email: "USER@SERVER.COM", + emailSubject: "EMAIL SUBJECT" + }; + const hyperlink = "HYPERLINK"; + expect(sheet.hyperlink("ADDRESS", opts)).toBe(sheet); + expect(sheet._hyperlinks["ADDRESS"].attributes).toEqualJson({ + ref: "ADDRESS", + "r:id": "ID" + }); + expect(sheet._relationships.add).toHaveBeenCalledWith("hyperlink", hyperlink, "External"); + }); }); describe("incrementMaxSharedFormulaId", () => { From 54da13290dcd10c90fa991d960414a83b0961265 Mon Sep 17 00:00:00 2001 From: Eddie Corrigall Date: Mon, 14 Jan 2019 11:43:25 -0500 Subject: [PATCH 10/13] Match hyperlinks docs with Sheet --- lib/Cell.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/Cell.js b/lib/Cell.js index c69fcc2e..99b5a35e 100644 --- a/lib/Cell.js +++ b/lib/Cell.js @@ -169,10 +169,10 @@ class Cell { *//* * Set the hyperlink options on the cell. * @param {{}}} opts - Options. - * @param {string|Cell} [opts.hyperlink] - The hyperlink to set, if an instance of Cell the hyperlink is internal. + * @param {string|Cell} [opts.hyperlink] - The hyperlink to set, can be a Cell or an internal/external string. * @param {string} [opts.tooltip] - Additional text to help the user understand more about the hyperlink. - * @param {string} [opts.email] - Email address. - * @param {string} [opts.emailSubject] - Email subject. + * @param {string} [opts.email] - Email address, ignored if opts.hyperlink is set. + * @param {string} [opts.emailSubject] - Email subject, ignored if opts.hyperlink is set. * @returns {Cell} The cell. */ hyperlink() { From 46e6fe1c77dacb2d53767bfbd4d03bc8794bd60b Mon Sep 17 00:00:00 2001 From: Eddie Corrigall Date: Mon, 14 Jan 2019 11:49:24 -0500 Subject: [PATCH 11/13] Update Sheet.hyperlink docs for internal arg --- lib/Sheet.js | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/Sheet.js b/lib/Sheet.js index ad7e4c84..41cb3e45 100644 --- a/lib/Sheet.js +++ b/lib/Sheet.js @@ -559,6 +559,7 @@ class Sheet { * Set the hyperlink attached to the cell with the given address. * @param {string} address - The address of the hyperlinked cell. * @param {string} hyperlink - The hyperlink to set or undefined to clear. + * @param {boolean} [internal] - The flag to force hyperlink to be internal. If true, then autodetect is skipped. * @returns {Sheet} The sheet. * @ignore *//** From c80496bc5feb018fda109f6427c70d41d5b100ba Mon Sep 17 00:00:00 2001 From: Eddie Corrigall Date: Mon, 14 Jan 2019 13:22:20 -0500 Subject: [PATCH 12/13] Update docs to include opts as Cell --- lib/Cell.js | 5 +++++ lib/Sheet.js | 10 ++++++++-- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/lib/Cell.js b/lib/Cell.js index 99b5a35e..c9012e9c 100644 --- a/lib/Cell.js +++ b/lib/Cell.js @@ -166,6 +166,11 @@ class Cell { * Set or clear the hyperlink on the cell. * @param {string|Cell|undefined} hyperlink - The hyperlink to set or undefined to clear. * @returns {Cell} The cell. + *//** + * Set the hyperlink options on the cell. + * @param {string} address - The address of the hyperlinked cell. + * @param {object|Cell} opts - Options. If opts is a Cell then an internal hyperlink is added. + * @returns {Sheet} The sheet. *//* * Set the hyperlink options on the cell. * @param {{}}} opts - Options. diff --git a/lib/Sheet.js b/lib/Sheet.js index 41cb3e45..2658f0cc 100644 --- a/lib/Sheet.js +++ b/lib/Sheet.js @@ -556,14 +556,20 @@ class Sheet { * @returns {string|undefined} The hyperlink or undefined if not set. * @ignore *//** - * Set the hyperlink attached to the cell with the given address. + * Set the hyperlink on the cell with the given address. * @param {string} address - The address of the hyperlinked cell. * @param {string} hyperlink - The hyperlink to set or undefined to clear. * @param {boolean} [internal] - The flag to force hyperlink to be internal. If true, then autodetect is skipped. * @returns {Sheet} The sheet. * @ignore *//** - * Set the hyperlink attached to the cell with the given address and options. + * Set the hyperlink on the cell with the given address. If opts is a Cell an internal hyperlink is added. + * @param {string} address - The address of the hyperlinked cell. + * @param {object|Cell} opts - Options. If opts is a Cell then an internal hyperlink is added. + * @returns {Sheet} The sheet. + * @ignore + *//** + * Set the hyperlink on the cell with the given address and options. * @param {string} address - The address of the hyperlinked cell. * @param {{}}} opts - Options. * @param {string|Cell} [opts.hyperlink] - The hyperlink to set, can be a Cell or an internal/external string. From ada27eaa836997fb05e154acf7d6eae18c6b8266 Mon Sep 17 00:00:00 2001 From: Eddie Corrigall Date: Mon, 14 Jan 2019 14:13:15 -0500 Subject: [PATCH 13/13] Ready docs for hyperlinks release --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++----- docs/template.md | 8 +++++ lib/Cell.js | 7 +--- lib/Sheet.js | 7 ++-- 4 files changed, 89 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index d96ca5b1..bb6cb5e3 100644 --- a/README.md +++ b/README.md @@ -466,17 +466,24 @@ cell.value("Link Text") .hyperlink("http://example.com"); // Set a hyperlink with tooltip -cell.value("Link Text") - .style({ fontColor: "0563c1", underline: true }) - .hyperlink("http://example.com", "example.com"); - -// Set a hyperlink with tooltip by object cell.value("Link Text") .style({ fontColor: "0563c1", underline: true }) .hyperlink({ hyperlink: "http://example.com", tooltip: "example.com" }); // Get the hyperlink const value = cell.hyperlink(); // Returns 'http://example.com' + +// Set a hyperlink to email +cell.value("Click to Email Jeff Bezos") + .hyperlink({ email: "jeff@amazon.com", emailSubject: "I know you're a busy man Jeff, but..." }); + +// Set a hyperlink to an internal cell using an address string. +cell.value("Click to go to an internal cell") + .hyperlink("Sheet2!A1"); + +// Set a hyperlink to an internal cell using a cell object. +cell.value("Click to go to an internal cell") + .hyperlink(workbook.sheet(0).cell("A1")); ``` ### Serving from Express @@ -844,7 +851,8 @@ A cell * [.formula()](#Cell+formula) ⇒ string * [.formula(formula)](#Cell+formula) ⇒ [Cell](#Cell) * [.hyperlink()](#Cell+hyperlink) ⇒ string \| undefined - * [.hyperlink(hyperlink, [tooltip])](#Cell+hyperlink) ⇒ [Cell](#Cell) + * [.hyperlink(hyperlink)](#Cell+hyperlink) ⇒ [Cell](#Cell) + * [.hyperlink(opts)](#Cell+hyperlink) ⇒ [Cell](#Cell) * [.dataValidation()](#Cell+dataValidation) ⇒ object \| undefined * [.dataValidation(dataValidation)](#Cell+dataValidation) ⇒ [Cell](#Cell) * [.tap(callback)](#Cell+tap) ⇒ [Cell](#Cell) @@ -972,7 +980,7 @@ Gets the hyperlink attached to the cell. **Returns**: string \| undefined - The hyperlink or undefined if not set. -#### cell.hyperlink(hyperlink, [tooltip]) ⇒ [Cell](#Cell) +#### cell.hyperlink(hyperlink) ⇒ [Cell](#Cell) Set or clear the hyperlink on the cell. **Kind**: instance method of [Cell](#Cell) @@ -980,8 +988,23 @@ Set or clear the hyperlink on the cell. | Param | Type | Description | | --- | --- | --- | -| hyperlink | string \| object \| undefined | The hyperlink to set or undefined to clear. | -| [tooltip] | string | The tooltip to set for hyperlink. | +| hyperlink | string \| [Cell](#Cell) \| undefined | The hyperlink to set or undefined to clear. | + + + +#### cell.hyperlink(opts) ⇒ [Cell](#Cell) +Set the hyperlink options on the cell. + +**Kind**: instance method of [Cell](#Cell) +**Returns**: [Cell](#Cell) - The cell. + +| Param | Type | Description | +| --- | --- | --- | +| opts | Object \| [Cell](#Cell) | Options or Cell. If opts is a Cell then an internal hyperlink is added. | +| [opts.hyperlink] | string \| [Cell](#Cell) | The hyperlink to set, can be a Cell or an internal/external string. | +| [opts.tooltip] | string | Additional text to help the user understand more about the hyperlink. | +| [opts.email] | string | Email address, ignored if opts.hyperlink is set. | +| [opts.emailSubject] | string | Email subject, ignored if opts.hyperlink is set. | @@ -2103,6 +2126,9 @@ A worksheet. * [.tabSelected(selected)](#Sheet+tabSelected) ⇒ [Sheet](#Sheet) * [.usedRange()](#Sheet+usedRange) ⇒ [Range](#Range) \| undefined * [.workbook()](#Sheet+workbook) ⇒ [Workbook](#Workbook) + * [.hyperlink(address)](#Sheet+hyperlink) ⇒ string \| undefined + * [.hyperlink(address, hyperlink, [internal])](#Sheet+hyperlink) ⇒ [Sheet](#Sheet) + * [.hyperlink(address, opts)](#Sheet+hyperlink) ⇒ [Sheet](#Sheet) @@ -2424,6 +2450,49 @@ Gets the parent workbook. **Kind**: instance method of [Sheet](#Sheet) **Returns**: [Workbook](#Workbook) - The parent workbook. + + +#### sheet.hyperlink(address) ⇒ string \| undefined +Get the hyperlink attached to the cell with the given address. + +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: string \| undefined - The hyperlink or undefined if not set. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The address of the hyperlinked cell. | + + + +#### sheet.hyperlink(address, hyperlink, [internal]) ⇒ [Sheet](#Sheet) +Set the hyperlink on the cell with the given address. + +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The address of the hyperlinked cell. | +| hyperlink | string | The hyperlink to set or undefined to clear. | +| [internal] | boolean | The flag to force hyperlink to be internal. If true, then autodetect is skipped. | + + + +#### sheet.hyperlink(address, opts) ⇒ [Sheet](#Sheet) +Set the hyperlink on the cell with the given address and options. + +**Kind**: instance method of [Sheet](#Sheet) +**Returns**: [Sheet](#Sheet) - The sheet. + +| Param | Type | Description | +| --- | --- | --- | +| address | string | The address of the hyperlinked cell. | +| opts | Object \| [Cell](#Cell) | Options or Cell. If opts is a Cell then an internal hyperlink is added. | +| [opts.hyperlink] | string \| [Cell](#Cell) | The hyperlink to set, can be a Cell or an internal/external string. | +| [opts.tooltip] | string | Additional text to help the user understand more about the hyperlink. | +| [opts.email] | string | Email address, ignored if opts.hyperlink is set. | +| [opts.emailSubject] | string | Email subject, ignored if opts.hyperlink is set. | + ### Workbook diff --git a/docs/template.md b/docs/template.md index 8a761dcf..dac491ea 100644 --- a/docs/template.md +++ b/docs/template.md @@ -448,6 +448,14 @@ const value = cell.hyperlink(); // Returns 'http://example.com' // Set a hyperlink to email cell.value("Click to Email Jeff Bezos") .hyperlink({ email: "jeff@amazon.com", emailSubject: "I know you're a busy man Jeff, but..." }); + +// Set a hyperlink to an internal cell using an address string. +cell.value("Click to go to an internal cell") + .hyperlink("Sheet2!A1"); + +// Set a hyperlink to an internal cell using a cell object. +cell.value("Click to go to an internal cell") + .hyperlink(workbook.sheet(0).cell("A1")); ``` ### Serving from Express diff --git a/lib/Cell.js b/lib/Cell.js index c9012e9c..bc4f0dc6 100644 --- a/lib/Cell.js +++ b/lib/Cell.js @@ -168,12 +168,7 @@ class Cell { * @returns {Cell} The cell. *//** * Set the hyperlink options on the cell. - * @param {string} address - The address of the hyperlinked cell. - * @param {object|Cell} opts - Options. If opts is a Cell then an internal hyperlink is added. - * @returns {Sheet} The sheet. - *//* - * Set the hyperlink options on the cell. - * @param {{}}} opts - Options. + * @param {{}|Cell} opts - Options or Cell. If opts is a Cell then an internal hyperlink is added. * @param {string|Cell} [opts.hyperlink] - The hyperlink to set, can be a Cell or an internal/external string. * @param {string} [opts.tooltip] - Additional text to help the user understand more about the hyperlink. * @param {string} [opts.email] - Email address, ignored if opts.hyperlink is set. diff --git a/lib/Sheet.js b/lib/Sheet.js index 2658f0cc..0e8f5b19 100644 --- a/lib/Sheet.js +++ b/lib/Sheet.js @@ -554,30 +554,27 @@ class Sheet { * Get the hyperlink attached to the cell with the given address. * @param {string} address - The address of the hyperlinked cell. * @returns {string|undefined} The hyperlink or undefined if not set. - * @ignore *//** * Set the hyperlink on the cell with the given address. * @param {string} address - The address of the hyperlinked cell. * @param {string} hyperlink - The hyperlink to set or undefined to clear. * @param {boolean} [internal] - The flag to force hyperlink to be internal. If true, then autodetect is skipped. * @returns {Sheet} The sheet. - * @ignore *//** * Set the hyperlink on the cell with the given address. If opts is a Cell an internal hyperlink is added. * @param {string} address - The address of the hyperlinked cell. - * @param {object|Cell} opts - Options. If opts is a Cell then an internal hyperlink is added. + * @param {object|Cell} opts - Options. * @returns {Sheet} The sheet. * @ignore *//** * Set the hyperlink on the cell with the given address and options. * @param {string} address - The address of the hyperlinked cell. - * @param {{}}} opts - Options. + * @param {{}|Cell} opts - Options or Cell. If opts is a Cell then an internal hyperlink is added. * @param {string|Cell} [opts.hyperlink] - The hyperlink to set, can be a Cell or an internal/external string. * @param {string} [opts.tooltip] - Additional text to help the user understand more about the hyperlink. * @param {string} [opts.email] - Email address, ignored if opts.hyperlink is set. * @param {string} [opts.emailSubject] - Email subject, ignored if opts.hyperlink is set. * @returns {Sheet} The sheet. - * @ignore */ hyperlink() { return new ArgHandler('Sheet.hyperlink')