-
Destination - can be one of the following:
- A File Name - Where to Save it (Any name other than "buffer")
- Literal string "buffer" - meaning it is buffered into a buffer Object to your "render" callback (see render command)
- pipe - any valid pipe that can be written too.
- Parent report - making this a child report of the parent report.
-
Options - Default is in (parentheses)
- landscape: true or (false); to make the report landscaped.
- paper: (letter), legal, A0-A10, B0-B10, C0-C10, Executive, Folio, Tabloid, RA0-RA4, SRA0-SRA4
- font: (Helvetica), Courier, Times-Roman, Symbol, ZapfDingbats or a external font file that you provide and add to the report via the "registerFont" command.
- fontSize: (12), any number from 1-128.
- margins: (72), can be a single number for all four sides; or a object array like: {left:72, top:72, bottom:72, right: 72}
- autoPrint: true or (false); to make the report automatically bring up the print dialog
- fullScreen: true or (false); to make the report automatically full screen when it loads
- negativeParentheses: true or (false); to make negative number show up like (20) rather than -20.
- info - object; you can set some of the pdf info (more info at http://pdfkit.org/docs/getting_started.html#setting_document_metadata)
-
show.
- once - Show the header/footer only once
- newPageOnly - Show on all new pages if this reportGroup is the current reportGroup
- always - show on all new pages even if this reportGroup is a parent of the current reportGroup
-
alignment.
- LEFT, CENTER, RIGHT
-
renderType.
- file - render to a file
- pipe - render to a pipe
- buffer - render to a buffer
-
trace: true or (false) - output tracing statements to the console
-
callbackDebugging: true or (false) - output callback tracing statements; trace needs to be true to use this option; and of course these two affect ALL reports.
Please note; this actually returns the a ReportGroup object; not the Report object -- this is by design since creating a new Report creates the entire structure as such:
- Primary Report Object -> ReportSection -> ReportDataSet -> ReportGroup and so all methods are as such off of the ReportGroup object.
var MyReportObject = new Report("MyCoolReport.pdf", {autoPrint: true}); Would create the report called "MyCoolReport.pdf" and auto print it when it is opened in a pdf reader.
This allows you to set userData on the report that you might want at some later point in the report -- this is rarely used.
- Data - whatever extra user data you need access to in the report
This allows you to set a formatting function to deal with any total values and formatting
- function - this is a function that will format your totals before it print them. The function prototype needs to be: function(dataIn, callback(err, formattedDataOut))
THIS IS MANDANTORY - you need to set a data object otherwise there is no point to the report.
- Data - this can be an array of arrays; and array of objects, an object, a string/number value or one of the two more advanced data class:
- a simple query function; the report system calls this function with (currentData, callback) and the prototype callback(err, data) -- when this function is called you can either call the callback with the data OR return ALL the needed data directly from this function.
- pageable class; your class needs to implement a "count", "loadRange" methods as a minimum; and optionally can have a "query" method.
** count is called with a callback(err, data) where data needs to be the count of record that are too be printed. ** loadRange is called (start, end, callback), start = first record needed, end = last record needed, callback is (err, resultData) ** query is called with (currentData, callback) where callback only has (err) as it just needs to be called when the query is done being prepared.
MyReportObject.data([{id: 1, name: 'Nathanael'}, {id: 2, name: 'Anderson'}]);
This allows you to be notified of the query result count before the printing actually happens. This is useful where you can't know the report data count before the report starts, because you are passing in a object that does all the queries itself. The report when it queries the data count, will call your RecordCountCallback function, this function will receive a record count, and a callback function. You MUST call the continueCallback function. You can optionally pass the continueCallback a boolean "false" to actually cancel the report, any other value (and no value) is considered that you want to continue printing. In the event you choose to cancel the report no report will be is generated; and the final render callback done will be passed "false" instead of a filename or buffer.
- recordCountCallback function
- dummy (the callback does not use the dummy; but to keep the same normal type of node callback (err, value))
- continueReport - boolean false = cancel report; any other value (and no value) will continue the report.
function rcCount(count, continueCallback) { if (count === 0) { console.log("No records"); callback(null, false); } else if (count > 250) { console.log("Too many records") callback(null, false); } else callback(); } MyReportObject.recordCount(rcCount);
This is so you can set a key or keys that get passed to sub-report data query functions/class objects.
- Keys - A single string key, or array of string keys, this is used to know which data to send to the "query" functions that you can pass into the .data function above -- this is used for sub-reports.
MyReportObject.keys("id");
This is used to add a sub-report; however you can use the easier method of "new Report(parentReport)" rather this "parentReport.addReport(x)"
- Report - the Report object you created
- options
- isSibling - true or (false) -- this allows you to make this report a "sibling" report rather than the normal child report.
This allows you to set the pdf information and can be passed in as one of the Report(..., OPTIONS)
- info - this is the object that contains the pdf header information you might want to change or add to the report
This is used so that the report system know how to output each detail record. This is used in most reports; but in some you might not need it.
- detailOutput - this can be a array, a string or a function
- array = [[Data Key, Data Width, Data Alignment],[...],...] Key is the key of the data to use for output, width is how wide to make this, alignment is right, (left), or center.
- string = "some text {{key_1}} more text {{key_2}}...." - where key_1 & key_2 are the index names of the data to use.
- function = This is prototyped (ReportRenderer, Data, State, Done_Callback) for Asynchronous and (ReportRenderer, Data, State) for synchronous reporting. The whole report must be either Sync or Async.
- The ReportRenderer has multiple methods for outputting to your report. Please see the ReportRenderer section for its methods.
- The Data is the current line/row of data; you will deal with a SINGLE row of data each time this function is called.
- The State is the state of the engine; it is a object with multiple keys -- please see the "State" of the engine section for the values in this.
- Done_Callback - Again, this is only on ASYNC reports; it is Done_Callback(err).
MyReportObject.detail([["name", 120], ["address", 200], ["state", 20]]); or MyReportObject.detail("{{name}} lives in the state of {{state}}");
This is printed for the FIRST PAGE ONLY (if set); this prints first!
- headerOutput - this can be a string, array of two strings or a function. Function is prototyped identical to .detail
- options -
- pageBreak - true or (false) - this will cause the header to page break before printing it.
- pageBreakBefore - true or (false) - this will cause the header to page break before printing it.
- pageBreakAfter - true or (false) - this will cause the header to page break after printing it.
MyReportObject.titleHeader("This is my Cool Report");
This is printed for EVERY page except if the titleHeader is set, if the titleHeader is set then this header is skipped on the very first page; this prints first on the page!
- headerOutput - this can be a string, array of two strings or a function. Function is prototyped identical to .detail
- options -
- pageBreak - true or (false) - this will cause the header to page break before printing it.
- pageBreakBefore - true or (false) - this will cause the header to page break before printing it.
- pageBreakAfter - true or (false) - this will cause the header to page break after printing it.
MyReportObject.pageHeader(["This is my", "cool report"]);
This is printed as the header object to any group objects. So while grouping you might need a header for who/what this is grouping on.
- headerOutput - this can be a string, array of two strings or a function. Function is prototyped identical to .detail
- options -
- pageBreak - true or (false) - this will cause the header to page break before printing it.
- pageBreakBefore - true or (false) - this will cause the header to page break before printing it.
- pageBreakAfter - true or (false) - this will cause the header to page break after printing it.
This is printed as the footer object on the final page (if set).
- footerOutput - this can be a string, array of strings or a function. Function is prototyped identical to .detail
- options -
- pageBreak - true or (false) - this will cause the header to page break before printing it.
- pageBreakBefore - true or (false) - this will cause the header to page break before printing it.
- pageBreakAfter - true or (false) - this will cause the header to page break after printing it.
This is printed as the footer object on all pages (except for the last page if the finalSummary is set).
- footerOutput - this can be a string, array of strings or a function. Function is prototyped identical to .detail
- options -
- pageBreak - true or (false) - this will cause the header to page break before printing it.
- pageBreakBefore - true or (false) - this will cause the header to page break before printing it.
- pageBreakAfter - true or (false) - this will cause the header to page break after printing it.
MyReportObject.pageFooter(function(Rpt) { Rpt.print("Hey, this page is done!"); });
This is printed as the footer object to any group objects. So while grouping you might need a footer for who/what this is grouping on.
- footerOutput - this can be a string, array of strings or a function. Function is prototyped identical to .detail
- options -
- pageBreak - true or (false) - this will cause the header to page break before printing it.
- pageBreakBefore - true or (false) - this will cause the header to page break before printing it.
- pageBreakAfter - true or (false) - this will cause the header to page break after printing it.
This allows you to change the output type of the report; this is rarely used as when you create the report you set it at creation.
- type - this is one of the Report.renderType constants
This is what actually starts the rendering of the document when you are done setting it up with all these class methods. You can use either a callback or the returned promise to choose what to do...
-
callback - this is called when the report is done being rendered; the callback will be
- If rendering to disk (err, reportName)
- if Rendering to buffer (err, Buffer)
- if rendering to pipe (err, pipe)
- If rendering is CANCELLED (i.e. like via the .recordCount callback) it will return (err, false);
-
returned Promise
- If rendering to disk resolved(reportName)
- if rendering to buffer resolved(buffer)
- if rendering to pipe resolved(pipe)
- if rendering is cancelled resolved(false)
- any errors rejected(error)
MyReportObject.render(function(Err, name) { if (name === false) { console.log("Report was cancelled"); } else { console.log("The report was saved to", name); }); -- or -- MyReportObject.render() .then((name) => { if (name === false) { console.log("Report was cancelled"); } else { console.log("The report was saved to", name); } }) .catch((err) => { console.log("Error in Report", err) });
This prints out the structure of your report for debugging purposes to the console; it can see if you messed up your groupings or some other issues with your layout of the report.
- asRendered: true or (false) - If true this lays out the output in actual output order; if false (default) this lays it out in group order so you can easily see what is attached to what object.
Gets or sets landscape or portrait mode, This can be passed in as a Report(..., OPTIONS)
- landscape: true or (false) - false = portrait, true is landscape.
Gets or sets the paper size, This can be passed in as a Report(..., OPTIONS)
- paper - can be (letter), legal, A0-A10, B0-B10, C0-C10, Executive, Folio, Tabloid, RA0-RA4, SRA0-SRA4
This gets or sets the default font for the report, This can be passed in as a Report(..., OPTIONS)
- font: (helvetica), courier, times, symbol, dingbats or a external font file that you provide and add to the report via the "registerFont" command
This sets the Default font size for the report, This can be passed in as a Report(..., OPTIONS)
- size: any number from 1-128, with (12) being the default.
This allows you to register a external font to use in your report
- name - this is the name
- definition - is a object structure {normal: './normal.ttf', bold: './bold.ttf', 'bolditalic': './bi.ttf', 'italic': './italic.ttf'} with any of the four keys for font types.
MyReportObject.registerFont("Aparajita", {normal: './aparaj.ttf', bold: './aparajb.ttf', 'italic': './aparaji.ttf'});
This allows you to set all the margins or some of them, This can be passed in as a Report(..., OPTIONS)
- margins: (72), can be a single number for all four sides; or a object array like: {left:72, top:72, bottom:72, right: 72}
This will cause the print dialog to show up when you first open the pdf document, This can be passed in as a Report(..., OPTIONS)
- autoPrint - true or (false)
This will cause the pdf document to go to full screen on opening it up, This can be passed in as a Report(..., OPTIONS)
- fullScreen - true or (false)
This will print negatives as (20) rather than -20, This can be passed in as a Report(..., OPTIONS)
- negativeParentheses - true or (false)
This will import the "pdfFile" into this report
- pdfFile - the path to the pdf file
This will allow you to create grouping on fields so that you can have group headers, footers, details for each group of records.
IMPORTANT: this will RETURN a brand NEW ReportGroup object, which will then allow you to customize it with any of these commands listed here. Please keep this in mind when doing function chaining.
- field - this is the key field to group by. Anytime this field changes; it will run the prior values footer, then this values header and start doing the details in this group.
- options - this allows you to set if you want the header to be printed only show.once at the beginning of the group, (show.newPageOnly) which means at the beginning of the group and anytime a new page occurs while this is the current group, and show.always same as "newPageOnly" but always shows as long as it is a parent of the current group.
This allows you to have a running Sum of the field; this value is propagated through the totals system allowing access to the correct total value per group.
- field - this is the key for the field name you are tracking
This allows you to have a running minimum value of the field; this value is propagated through the totals system allowing access to the correct total value per group.
- field - this is the key for the field name you are tracking
This allows you to have a running maximum value of the field; this value is propagated through the totals system allowing access to the correct total value per group.
- field - this is the key for the field name you are tracking
This allows you to have a running count of the field; this value is propagated through the totals system allowing access to the correct total value per group.
- field - this is the key for the field name you are tracking
This allows you to have a running average of the field; this value is propagated through the totals system allowing access to the correct total value per group.
- field - this is the key for the field name you are tracking
These commands are available to the header, title header, page header, page summary, page footer, footer, and detail functions while the report is running. The first object passed to your function is the ReportRenderer object; this object has the following methods you can run.
This displays a image on the current page
- name - this is the image location of disk to use or image buffer
- options -
- x - X coordinate to start
- y - Y coordinate to start
- width - the width of the image
- height - the height of the image
- scale - scale value
- fit - fit the image inside the coords, width and height
- align - align the image, left, right, center
- valign - vertically align the image, top, center or bottom.
This allow you to get or change the default font (and optionally change the font size)
- name - is a valid font name
- size - OPTIONAL, the new font size
This allows you to get or change the current font size
- size - the new size of the font. Called without to get teh current font size.
This sets the font to be Bold; if the font supports Bold & Italic at the same time and you already have Italic set, it will set it to bold-italic.
This sets the font to be Italic; if the font was already set to bold AND the font supports Bold and Italic it will add italic to the bold fond, otherwise it will just make it italic.
This resets the font back to normal; eliminating any Bold and Italic attributes
This sets the fill & stroke colors
- fillColor - the color for fills
- strokeColor - the color for strokes, called without to only set the fill color
Forces a fill with either the current color or the optionally provided color.
- color - the color for the fill, or called without to use the current color to do the fill
Gets or sets the fill color
- color - the fill color to set, or called without to get the current value
Gets or sets the current fill opacity
- Opacity - a decimal number between 0 and 1, or called without to get the current value
R.fillOpacity(0.5)
This set or gets the stroke color
- color - the color to set the strokes, or called without to get the current value
This is used to switch between -30 and (30) for display of negative numbers.
- negativeParentheses - true enables using parentheses, (false) disables and uses the normal minus sign, or called without to get the current value
This will allow you to override the default margins and set the margins for the *NEXT * page
- margins - can be a number for all four sides or a object specifying each side {left: 25, right: 25, top: 50, bottom: 50}
This allows you to get or change the paper for the *NEXT * page
- paper - can be (letter), legal, A0-A10, B0-B10, C0-C10, Executive, Folio, Tabloid, RA0-RA4, SRA0-SRA4, or called without to get the current value
This allows you to get or change the landscape mode for the *NEXT * page
- landscape - true is landscape, (false) is portrait mode, or called without to get the current value
Allows you to save the current state of the engine -- This saves font, colors, and the x coordinate. This is a STACK, so you can save multiple states; and then restore them. Make sure any state you save you use a resetState or deleteState on afterwords, as the engine uses this code a lot to keep things correct.
This resets the state of the engine to the last saved state in the saved stack.
This deletes the last saved state of the engine.
This can tell you if the page has any changes on it.
- includeHeader - true or (false). If true, this will include any header changes also; as you may want to know if the page only had any record changes on the page vs any change at all.
this returns the current page that is being worked on.
This adds a new page for you to start working on. Please note; if you are using ASYNC functions then you must have a callback function for when the newPage is done, it will call your callback so you can continue.
- saveOptions - true or (false) this will save the state while it creates a new page and then reset it back after it is done -- this allows you to keep any font, or color changes over a page change.
- callback - used for ASYNC reports; this is called when the newPage is done creating the new page. You can optionally use this in a SYNC report; but it is REQUIRED in a ASYNC report.
R.newPage(); R.newPage(function() { R.print("Hi, I'm on a new page"); });
This runs the standard header or footer code so you can keep the default header/footers but make some minor changes
- text - the string or array of two strings you want printed
- callback - used for ASYNC reports; this is called when the header/footer printing is done. You can optionally use this in a SYNC report; but it is REQUIRED in a ASYNC report.
This returns the current X or Y coordinate
This sets the current X or Y coordinate
- new - the new x or y coordinate
This sets or gets the current X or Y coordinates
- new - the new x or y coordinate, or called without for the current x or y coordinate
This adds a number to either the X or Y coordinate
- new - the value to ADD or SUBTRACT (if negative) to the existing X or Y coordinate
This adds a newLine or multiple new lines
- count - the number of lines; or if unset it will default to 1 line
- callback - used for ASYNC reports; this is called when the newLine addition(s) is/are done. You can optionally use this in a SYNC report; but it is REQUIRED in a ASYNC report.
This calculates how long this string will be with the current font and font size.
- string - the string to size
This tells you how big a current string will be using the current font and font size; it doesn't actually need a string to tell you this as all string printed using this font & font size will use this space.
This allow you to print a line the size of the last band command
- thickness - the thickness of the line; defaults to 2
- verticalGap - the gap between the prior printed item and this line (default 0)
This prints a line from startX,startY to endX, endY
- startX - Starting X coordinate
- startY - Starting Y coordinate
- endX - End X coord
- endY - End Y coord
- options:
- fillOpacity - the Opacity
- borderColor - the border color
- fillColor - The fill color
- thickness - the Line thickness
- textColor - the text color
- fill - to fill the shape
This prints a box from startX,startY with a width and height
- startX - Starting X coordinate
- startY - Starting Y coordinate
- width - Width of Box
- height - Height of Box
- options:
- fillOpacity - the Opacity
- borderColor - the border color
- fillColor - The fill color
- thickness - the Line thickness
- dash - to make Line dashed
- textColor - the text color
- fill - to fill the shape
This prints a circle from startX,startY using the radius
- startX - Starting X coordinate
- startY - Starting Y coordinate
- radius - the radius of the circle
- options:
- fillOpacity - the Opacity
- borderColor - the border color
- fillColor - The fill color
- thickness - the Line thickness
- textColor - the text color
- fill - to fill the shape
This sets or gets the gap between lines
- width - the width to set it to, without this parameter it will return the current line width
Gets the last width of the band that was printed.
This returns the minimum or maximum X or Y coordinate allowed.
This will print the date time at the current location or header or footer locations
- options -
- align - alignment, "left", "right", "center"
- header - true or false, print in the header
- footer - true or false, print in the footer
- text - the text to print this: defaults to: "Printed At: {0}:{1}{2}\non {3}" where {0} is replaces with Hour, {1} minutes, {2} am/pm and {3} the current date.
This will return the page width - any margins, so this is the actual printable area.
This will return the page height - any margins, so this is the actual printable area.
This will print the current page number at the current location, or the header / footer locations
- options
- align - alignment, "left", "right", "center"
- header - true or false, print in the header
- footer - true or false, print in the footer
- text - the text to print this: defaults to: "Page: {0}" where {0} is the current page number - You can optionally use {1} for Total number of printed pages; this increases the memory usage as the report system. Examples: "Page {0} of {1}" will print, Page 1 of 200 on page 1, and "Page 55 of 200" on page 55 if the report had 200 pages.
Imports a PDF in the current location, if this page has any printing on it - it will end this page and import after it.
- name - the file name to import
This is one of the primary methods to put any text of the page; you pass it your text and any options you want applied to the text
- text - this can be a string or an array of strings
- options -
- useCurrentX - boolean; use the current X location; rather than resetting to left margin.
- x - x coordinate to print at
- y - y coordinate to print at
- addX - add this x to the x coord before printing
- addY - add this y to the y coord before printing
- align - alignment (left, center, or right)
- wordSpacing - the gap between words
- characterSpacing - the gap between characters
- width - the maximum size you want the string to be; it will wrap it after this.
- textColor - the font color of the text
- underline - make this text underlined
- strike - make this text striked through
- fontSize - the font Size to use
- fill - the background fill color
- link - make this text a link, this is the url that the click will activate
- font - the font to use
- fontBold - true or false to be bold
- fontItalic - true or false to be italic
- ignoreEmptyStrings - ignore printing any empty strings in arrays
- opacity - the opacity of the text
- rotate - the rotation of the text (Rotated text can exceed page dimensions)
- callback - used for ASYNC reports; this is called when the printing is done. You can optionally use this in a SYNC report; but it is REQUIRED in a ASYNC report.
This is the other primary method of displaying data on a report; this creates bands of cells like a spreadsheet
- dataIn - this is an array of each cell; each cell can override the below options with most of the below options so [ { data: "Data to Print", width: "width of cell", align: "alignment", border: 1, ...}, {data:...}, ...]
- options:
- gutter - gutter between cells
- collapse - (true) or false; collapse the borders between cells
- border - the width of all the border, it can also be a object with specifics for each side {left: 2, right: 0, top: 1, bottom: 1}
- dash - true or (false); make the border line dashed
- borderColor - the color of the border
- fill - the fill color of the cell
- fillOpacity - fill Opacity decimal value of 0 to 1.
- padding - padding inside the cell
- x - X coordinate
- y - Y coordinate
- addX - add to the X coordinate
- addY - add to the Y coordinate
- font - font to use
- fontBold - true or (false)
- fontItalic - true or (false)
- textColor - the text color
- link - the url to link this cell too.
- callback - used for ASYNC reports; this is called when the printing is done. You can optionally use this in a SYNC report; but it is REQUIRED in a ASYNC report.
This is exactly the same as the band() command; other than it will skip printing any repeated data; so if row 1 has the name "Nathanael" and row 2 has the name "Nathanael" it will skip printing row 2's "Nathanael".
- SAME as the above band() command other than it has one addition option
- duplicatedTextValue - this is the value to print in the suppressed cell; defaults to one quote (")