Skip to content

API.md

Latest commit

 

History

History
363 lines (260 loc) · 17.6 KB

API.md

File metadata and controls

363 lines (260 loc) · 17.6 KB

xlsx-datafill API reference

Classes

XlsxDataFill

Data fill engine, taking an instance of Excel sheet accessor and a JSON object as data, and filling the values from the latter into the former.

XlsxPopulateAccess

xslx-populate library based accessor to a given Excel workbook. All these methods are internally used by XlsxDataFill, but can be used as a reference for implementing custom spreadsheet accessors.

XlsxDataFill

Data fill engine, taking an instance of Excel sheet accessor and a JSON object as data, and filling the values from the latter into the former.

Kind: global class

new XlsxDataFill(accessor, opts)

Constructs a new instance of XlsxDataFill with given options.

Param Type Description
accessor object An instance of XLSX spreadsheet accessing class.
opts Object Options to be used during processing.
opts.templateRegExp RegExp The regular expression to be used for template recognizing. Default is /\{\{([^}]*)\}\}/, i.e. Mustache.
opts.fieldSplitter string | RegExo The string or regular expression to be used as template fields splitter. Default is `
opts.joinText string The string to be used when the extracted value for a single cell is an array, and it needs to be joined. Default is ,.
opts.mergeCells string | boolean Whether to merge the higher dimension cells in the output. Default is true, but valid values are also "both", "vertical" and "horizontal".
opts.duplicateCells string | boolean Whether to duplicate the content of higher dimension cells, when not merged. Default is false. Same valud values as mergeCells.
opts.followFormulae boolean If a template is located as a result of a formula, whether to still process it. Default is false.
opts.copyStyle boolean Copy the style of the template cell when populating. Even when false, the template styling is applied. Default is true.
opts.callbacksMap object.<string, function()> A map of handlers to be used for data and value extraction.

xlsxDataFill.options(newOpts) ⇒ XlsxDataFill | Object

Setter/getter for XlsxDataFill's options as set during construction.

Kind: instance method of XlsxDataFill
Returns: XlsxDataFill | Object - The required options (in getter mode) or XlsxDataFill (in setter mode) for chaining.

Param Type Description
newOpts Object | null If set - the new options to be used. Check up here.

xlsxDataFill.fillData(data) ⇒ XlsxDataFill

The main entry point for whole data population mechanism.

Kind: instance method of XlsxDataFill
Returns: XlsxDataFill - For invocation chaining.

Param Type Description
data Object The data to be applied.

XlsxDataFill.XlsxPopulateAccess : XlsxPopulateAccess

The built-in accessor based on xlsx-populate npm module

Kind: static property of XlsxDataFill

XlsxPopulateAccess

xslx-populate library based accessor to a given Excel workbook. All these methods are internally used by XlsxDataFill, but can be used as a reference for implementing custom spreadsheet accessors.

Kind: global class

new XlsxPopulateAccess(workbook, XlsxPopulate)

The XlsxPopulate object need to be passed in order to extract certain information from it, without referring the whole library, thus avoiding making the xlsx-datafill package a dependency.

Param Type Description
workbook Workbook The workbook to be accessed.
XlsxPopulate XlsxPopulate The actual xlsx-populate library object.

xlsxPopulateAccess.workbook() ⇒ Workbook

Returns the configured workbook for direct XlsxPopulate manipulation.

Kind: instance method of XlsxPopulateAccess
Returns: Workbook - The workbook involved.

xlsxPopulateAccess.cellValue(cell) ⇒ string

Gets the textual representation of the cell value.

Kind: instance method of XlsxPopulateAccess
Returns: string - The textual representation of cell's contents.

Param Type Description
cell Cell The cell to retrieve the value from.

xlsxPopulateAccess.setCellValue(cell, value) ⇒ XlsxPopulateAccess

Sets the cell value.

Kind: instance method of XlsxPopulateAccess
Returns: XlsxPopulateAccess - Either the requested value or chainable this.

Param Type Description
cell Cell The cell to retrieve the value from.
value * The requested value for setting.

xlsxPopulateAccess.cellType(cell) ⇒ string

Gets the textual representation of the cell value.

Kind: instance method of XlsxPopulateAccess
Returns: string - The type of the cell - 'formula', 'richtext', 'text', 'number', 'date', 'hyperlink', or 'unknown';

Param Type Description
cell Cell The cell to retrieve the value from.

xlsxPopulateAccess.setCellFormula(cell, formula) ⇒ XlsxPopulateAccess

Sets the formula in the cell

Kind: instance method of XlsxPopulateAccess
Returns: XlsxPopulateAccess - For chaining.

Param Type Description
cell Cell The cell to retrieve the value from.
formula string the text of the formula to be set.

xlsxPopulateAccess.cellDistance(from, to) ⇒ Array.<Number>

Measures the distance, as a vector between two given cells.

Kind: instance method of XlsxPopulateAccess
Returns: Array.<Number> - An array with two values [, ], representing the distance between the two cells.

Param Type Description
from Cell The first cell.
to Cell The second cell.

xlsxPopulateAccess.cellSize(cell) ⇒ Array.<Number>

Determines the size of cell, taking into account if it is part of a merged range.

Kind: instance method of XlsxPopulateAccess
Returns: Array.<Number> - An array with two values [, ], representing the occupied size.

Param Type Description
cell Cell The cell to be investigated.

xlsxPopulateAccess.setCellStyle(cell, name, value) ⇒ XlsxPopulateAccess

Sets a named style of a given cell.

Kind: instance method of XlsxPopulateAccess
Returns: XlsxPopulateAccess - For invocation chaining.

Param Type Description
cell Cell The cell to be operated.
name string The name of the style property to be set.
value string | object The value for this property to be set.

xlsxPopulateAccess.cellRef(cell, withSheet) ⇒ string

Creates a reference Id for a given cell, based on its sheet and address.

Kind: instance method of XlsxPopulateAccess
Returns: string - The id to be used as a reference for this cell.

Param Type Description
cell Cell The cell to create a reference Id to.
withSheet boolean Whether to include the sheet name in the reference. Defaults to true.

xlsxPopulateAccess.buildRef(cell, adr, withSheet) ⇒ string

Build a reference string for a cell identified by @param adr, from the @param cell.

Kind: instance method of XlsxPopulateAccess
Returns: string - A reference string identifying the target cell uniquely.

Param Type Description
cell Cell A cell that is a base of the reference.
adr string The address of the target cell, as mentioned in @param cell.
withSheet boolean Whether to include the sheet name in the reference. Defaults to true.

xlsxPopulateAccess.getCell(address, sheetId) ⇒ Cell

Retrieves a given cell from a given sheet (or an active one).

Kind: instance method of XlsxPopulateAccess
Returns: Cell - A reference to the required cell.

Param Type Description
address string | object | array The cell adress to be used
sheetId string | idx The id/name of the sheet to retrieve the cell from. Defaults to an active one.

xlsxPopulateAccess.duplicateCell(cell, range) ⇒ XlsxPopulateAccess

Duplicates a cell across a given range.

Kind: instance method of XlsxPopulateAccess
Returns: XlsxPopulateAccess - For chain invokes.

Param Type Description
cell Cell Cell, which needs duplicating.
range Range The range, as returned from getCellRange

xlsxPopulateAccess.getCellRange(cell, rowOffset, colOffset) ⇒ Range

Constructs and returns the range starting from the given cell and spawning given rows and cells.

Kind: instance method of XlsxPopulateAccess
Returns: Range - The constructed range.

Param Type Description
cell Cell The starting cell of the range.
rowOffset Number Number of rows away from the starting cell. 0 means same row.
colOffset Number Number of columns away from the starting cell. 0 means same column.

xlsxPopulateAccess.offsetCell(cell, rows, cols) ⇒ Cell

Gets the cell at a certain offset from a given one.

Kind: instance method of XlsxPopulateAccess
Returns: Cell - The resulting cell.

Param Type Description
cell Cell The reference cell to make the offset from.
rows int Number of rows to offset.
cols int Number of columns to offset.

xlsxPopulateAccess.rangeMerged(range, status) ⇒ XlsxPopulateAccess

Merge or split range of cells.

Kind: instance method of XlsxPopulateAccess
Returns: XlsxPopulateAccess - For chain invokes.

Param Type Description
range Range The range, as returned from getCellRange
status boolean The merged status to be set.

xlsxPopulateAccess.setRangeFormula(range, formula) ⇒ XlsxPopulateAccess

Sets a formula for the whole range. If it contains only one - it is set directly.

Kind: instance method of XlsxPopulateAccess
Returns: XlsxPopulateAccess - For chain invokes.

Param Type Description
range Range The range, as returned from getCellRange
formula String The formula to be set.

xlsxPopulateAccess.rangeRef(range, withSheet) ⇒ String

Return the string representation of a given range.

Kind: instance method of XlsxPopulateAccess
Returns: String - The string, representing the given range.

Param Type Description
range Range The range which address we're interested in.
withSheet boolean Whether to include sheet name in the address.

xlsxPopulateAccess.forAllCells(cb) ⇒ XlsxPopulateAccess

Iterate over all used cells of the given workbook.

Kind: instance method of XlsxPopulateAccess
Returns: XlsxPopulateAccess - For chain invokes.

Param Type Description
cb function The callback to be invoked with cell argument for each used cell.

xlsxPopulateAccess.copyStyle(dest, src) ⇒ XlsxPopulateAccess

Copies the styles from src cell to the dest-ination one.

Kind: instance method of XlsxPopulateAccess
Returns: XlsxPopulateAccess - For invocation chaining.

Param Type Description
dest Cell Destination cell.
src Cell Source cell.