O.generate.table

Generators for table-based file formats, such as Microsoft Excel .xls files, TSV and CSV. (Currently only xls and xlsx files are supported.)

property O.generate.table.FORMATS

An array of all the supported formats.

function O.generate.table.xls(filename)

Returns a generator object for a Microsoft Excel .xls file, with the given filename. The filename should not include the .xls extension.

xls files have a 64k row limit.

function O.generate.table.xlsx(filename)

Returns a generator object for a Microsoft Excel .xlsx file, with the given filename. The filename should not include the .xlsx extension.

xlsx files support many more rows than xls files.

Usage

  • Call the function for the required format, with the filename as an argument. Returns a generator object.
  • Call newSheet() to create a sheet with the required name.
  • For each row, add cells by using the JavaScript Array interface, or calling the cell() function, then nextRow()
  • Create any more sheets by repeating.
  • Call finish()
  • Do something with the generated file, such as storing it in the file store with O.file(), or returning it as an HTTP responses by assigning it to E.response.body.

Cell values

Type Output
String Output as string
Number Output as number where possible, converted to string otherwise
Date Output as date where possible, converted to string otherwise
StoreObject descriptiveTitle() output as string
Ref Object loaded, descriptiveTitle() output as string
SecurityPrincipal name property output as string
Other JavaScript object toString() output as string

Table generator interface

Each format of table generator implements this interface.

Array functions

While creating a row, the generator implements the JavaScript Array interface, with element access through the [] operator.

property supportsMultipleSheets

true if the format supports multiple sheets in the same file. If false and a file is made with multiple sheets, a zip file will be created containing multiple files.

function newSheet(name, firstRowIsHeader)

Start a new sheet. If this is not called explicitly, a sheet will be generated automatically with a generic name.

Returns itself, making the function suitable for chaining.

function cell(value, options)

Adds a cell to the end of the row. Returns itself, making the function suitable for chaining.

options may be omitted. If it is included and is not recognised option for the given value, it it silently ignored.

Option Action
date (string) For Date value, only put the date part in the sheet.

property length

Length of the current row, as with a normal JavaScript Array.

function push(value)

Append a value to the current row, just like a normal JavaScript Array.

function nextRow()

Start a new row. length set to 0.

Returns itself, making the function suitable for chaining.

function pageBreak()

Add a page break before the current row, if supported by the output format. If the output format doesn’t support page breaks, the function will return without error and have no effect.

Returns itself, making the function suitable for chaining.

function sortedSheets()

If called at any time before finish(), the sheets will be sorted when finish() is called.

Returns itself, making the function suitable for chaining.

function finish()

Finish the generation, and prepare for serialisation.

When you use these generators to generate a response, this function will be called automatically by the request handling framework.

property hasFinished

Returns true if finish() has been called.

Returns itself.