ReportBuilder

Provides an API for programmatic construction of report definitions. Use jsreports.createReport() to get a new ReportBuilder, as shown in the example below.

Kind: global class

new ReportBuilder()

Do not call directly. Use jsreports.createReport() to get a new ReportBuilder.

Example

// Create a new report definition
var reportDef = jsreports.createReport()
 .data("time")
 .groupBy("Client_ID")
   .header()
     .text("Group header text")
   .footer()
     .text("Group footer")
 .detail()
   .text("Detail with [data]")
 .input('Client', 'text')
 .filterBy('Client_name', 'contains', '[?Client]')
 .done();

// Render the report
jsreports.render({
  report_def: reportDef,
  datasets: myDataSets,  // defined elsewhere
  target: $('#myDiv')
});

.background()

Add a page background to the report. The page background can contain the same kinds of elements as other sections. The background is rendered once on each page in PDF mode and once at the top of the report in HTML mode.

Kind: instance method of ReportBuilder

.barcode(value, encoding, left, top, width, height, opts)

Add a barcode element at the specified location.

Kind: instance method of ReportBuilder

Param Type Description
value string The expression to be evaluated and displayed as a barcode
encoding string One of CODE39, CODE128, UPC, ITF14, pharmacode, QR
left number The distance from the left edge of the section to the left edge of the element, in report units (inches or mm), not including the page margin
top number The distance from the top edge of the section to the top edge of the element, in report units
width number The width of the element in report units
height number The height of the element in report units
opts object An object containing additional properties to apply to the element

.box(fill, stroke, left, top, width, height, opts)

Add a box element at the specified location.

Kind: instance method of ReportBuilder

Param Type Description
fill string The hex color code of the fill color, or 'transparent' (e.g. '#fc0')
stroke string The hex color code of the border color, or 'transparent' (e.g. '#000')
left number The distance from the left edge of the section to the left edge of the element, in report units (inches or mm), not including the page margin
top number The distance from the top edge of the section to the top edge of the element, in report units
width number The width of the element in report units
height number The height of the element in report units
opts object An object containing additional properties to apply to the element

.chart(chartType, [valueField], [labelField], left, top, width, height, opts)

Add a chart element at the specified location.

Kind: instance method of ReportBuilder

Param Type Description
chartType string One of 'line', 'bar', 'pie'
[valueField] string The data field containing the y-values for line and bar charts, and slice sizes for pie charts
[labelField] string The field containing slice labels for pie charts
left number The distance from the left edge of the section to the left edge of the element, in report units (inches or mm), not including the page margin
top number The distance from the top edge of the section to the top edge of the element, in report units
width number The width of the element in report units
height number The height of the element in report units
opts object An object containing additional properties to apply to the element

.column(width, detail, [header], [footer], [opts])

Add a data series to the previously added table element (see table)

Kind: instance method of ReportBuilder

Param Type Description
width string | number The width of the column, either a percentage of the table width (e.g. '100%') or a number in report units (e.g. 4 meaning 4 inches)
detail string The text expression to evaluate and render in each detail cell in this column
[header] string The text expression to evaluate and render in the table header cell in this column (or null)
[footer] string The text expression to evaluate and render in the table footer cell in this column (or null)
[opts] object An object containing additional properties to apply to the column

.columnFooter(height)

Add a column header to the report.

Kind: instance method of ReportBuilder

Param Type Description
height number The height of the header, in report units (inches or mm).

.columnHeader(height)

Add a column header to the report.

Kind: instance method of ReportBuilder

Param Type Description
height number The height of the header, in report units (inches or mm).

.data(dataSourceId)

Begins a data section in the report using the specified data source ID. When called multiple times, adds additional data sections below the first, each allowing nested grouping within its own data source via subsequent calls to groupBy, header, footer, detail, etc. This should be one of the first methods you call when using the report builder API to define a report.

Kind: instance method of ReportBuilder

Param Type Description
dataSourceId string The ID of the data source; must match a defined data source ID when the report runs

.detail()

Move to the detail of the current data section

Kind: instance method of ReportBuilder

.detailHeight()

Set the height of the report's detail section, in report units (inches or mm).

Kind: instance method of ReportBuilder

.done()

Return the report definition in object form. Call this at the end of a chain of calls that define the report. The object returned by this method is the report definition that you can pass to jsreports.render() or jsreports.export().

Kind: instance method of ReportBuilder
Example

// Define a simple report with one text element
var reportDef = jsreports.createReport()
  .data('mydata')
  .text('Data value is [myfield]')
  .done();

.element()

Add an element by its type ID - for custom elements

Kind: instance method of ReportBuilder

.filterBy(field, comparison, compareTo)

Add a filter to restrict which records are shown in the report. To filter by a user input, use '[?InputName]' syntax in the compareTo argument.

Kind: instance method of ReportBuilder

Param Type Description
field string Name of the data field to filter
comparison string One of: is, isnot, contains, doesnotcontain, gt, lt, gte, lte
compareTo string Expression against which the data field will be compared

.footer(height)

Add a footer to the current level. By default, the level is the report itself; if groupBy has been called, then the footer will be added to the most recent grouping level.

Kind: instance method of ReportBuilder

Param Type Description
height number The height of the footer, in report units (inches or mm).

.groupBy(groupBy, [sortBy], [sortDir])

Add a new sub-grouping. If groupBy has already been called, this adds a sub-grouping beneath that grouping. Records will be grouped by the values in the groupBy data field and the groups will be arranged relative to each other based on the sortBy data field, if specified. Groups do not have headers or footers by default; use addHeader and addFooter to add them.

Kind: instance method of ReportBuilder

Param Type Description
groupBy string The data field containing the values defining the groups
[sortBy] string The data field by which groups should be sorted relative to each other (default: same as groupBy)
[sortDir] string One of: 'asc', 'desc' (ascending = A-Z, 0-9) (default: 'asc')

.header(height)

Add a header to the current level. By default, the level is the report itself; if groupBy has been called, then the header will be added to the most recent grouping level.

Kind: instance method of ReportBuilder

Param Type Description
height number The height of the header, in report units (inches or mm).

.hideDetail()

Make the report's detail section invisible.

Kind: instance method of ReportBuilder

.image(url, left, top, width, height, opts)

Add an image element at the specified location.

Kind: instance method of ReportBuilder

Param Type Description
url string The url of the image, either relative or absolute
left number The distance from the left edge of the section to the left edge of the element, in report units (inches or mm), not including the page margin
top number The distance from the top edge of the section to the top edge of the element, in report units
width number The width of the element in report units
height number The height of the element in report units
opts object An object containing additional properties to apply to the element

.input(name, type, [defaultValue])

Add a user input to the report. Inputs appear in the report viewer toolbar and allow you to filter the report by user-provided values. To filter by an input value, see addFilter.

Kind: instance method of ReportBuilder

Param Type Description
name string User-visible name of the input field
type string One of "text", "number", "date"
[defaultValue] string The default value for the input

.margins(top, right, bottom, left)

Set the page margins for the report. Margins will use the units defined for the report in setPage, or inches if setPage is not called. If only one argument is supplied, it will be used for all four margins.

Kind: instance method of ReportBuilder

Param Type Description
top number The top margin height, in report units (inches or mm).
right number The right margin width, in report units.
bottom number The bottom margin height, in report units.
left number The left margin width, in report units.

.name(name)

Set the report's name (used to generate filenames for download)

Kind: instance method of ReportBuilder

Param Type Description
name string The new name for the report

.page(width, height, units)

Set page dimensions for the report.

Kind: instance method of ReportBuilder

Param Type Description
width number The width of the page, in report units (inches or mm).
height number The height of the page, in report units (inches or mm).
units string The report units ('in' or 'mm'), defaults to inches

Example

// Set the report to 8.5 x 11 inches (US letter size)
jsreports.createReport()
  .setPage(8.5, 11, "inches")

.pageFooter(height)

Add a page footer to the report.

Kind: instance method of ReportBuilder

Param Type Description
height number The height of the footer, in report units (inches or mm).

.pageHeader(height)

Add a page header to the report.

Kind: instance method of ReportBuilder

Param Type Description
height number The height of the header, in report units (inches or mm).

.series(valueField, [labelField], [colorField])

Add a data series to the previously added chart element (see chart)

Kind: instance method of ReportBuilder

Param Type Description
valueField string The data field containing the y-values for line and bar charts, and slice sizes for pie charts
[labelField] string The field containing slice labels for pie charts
[colorField] string The field containing slice labels for pie charts

.showDetail()

Make the report's detail section visible.

Kind: instance method of ReportBuilder

.sortDetailBy(sortBy, [sortDir])

Order records in the report detail section by the given data field, in the given direction.

Kind: instance method of ReportBuilder

Param Type Description
sortBy string The name of the data field by which to sort
[sortDir] string One of: 'asc', 'desc' (ascending = A-Z, 0-9) (default: 'asc')

.table(left, top, width, height, opts)

Add a table element at the specified location.

Kind: instance method of ReportBuilder

Param Type Description
left number The distance from the left edge of the section to the left edge of the element, in report units (inches or mm), not including the page margin
top number The distance from the top edge of the section to the top edge of the element, in report units
width number The width of the element in report units
height number The height of the element in report units
opts object An object containing additional properties to apply to the element

Example

.table(0, 1.25, 4.75, 2.5, { data: 'changeItems', hasFooter: true, 
    groupBy: 'category', fontSize: 9, hideRowWhenExpr: '!description' 
})
.column('50%', '   [description]', '', '', { 
    align: 'left', group0Header: '[category]' })
.column('25%', '[currentPeriod]', 'This Period', '[SUM(currentPeriod)]', { 
    align: 'right',
    detailStyle: {
        pattern: '#,##0.00'
    },
    group0Header: '[SUM(currentPeriod)]',
    group0HeaderStyle: {
        pattern: '#,##0.00'
    }
})
.column('25%', '[ytd]', 'Year-to-Date', '[SUM(ytd)]', { 
    align: 'right',
    detailStyle: {
        pattern: '#,##0.00'
    },
    group0Header: '[SUM(ytd)]',
    group0HeaderStyle: {
        pattern: '#,##0.00'
    }
})

.text(text, left, top, width, height, opts)

Add a text element at the specified location.

Kind: instance method of ReportBuilder

Param Type Description
text string The content of the text element.
left number The distance from the left edge of the section to the left edge of the element, in report units (inches or mm), not including the page margin
top number The distance from the top edge of the section to the top edge of the element, in report units
width number The width of the element in report units
height number The height of the element in report units
opts object An object containing additional properties to apply to the element

.toString()

Like done(), but returns the report definition in string format.

Kind: instance method of ReportBuilder