Methods and Parameters¶

Please note that if you want to use any of the constants, you will have to "touch" the plugin at least once (in your solution onOpen for example).
Adding a simple:

plugins.VelocityReport;

is enough to ask Servoy to load the constants in the scripting environment.

addDefaultChartParameter, clearDefaultChartParameter, removeDefaultChartParameter, setDefaultChartParameters¶

These methods can be used to manage a map of default parameters for charts, you can:

add a new parameter, using addDefaultChartParameter(String key, Object value)
clear the map of parameter, using clearDefaultChartParameters()
remove one value, using removeDefaultChartParameter(String key)
set more than one value at a time, using setDefaultChartParameters(JSObject mapOfParameters)

The list of default parameters that you can set for charts (which will be used for all charts, but can be overriden by any call to getChart()), is:

id
width
height
title
titleColor
titleSize
background
areaFill
transparency
margins
legendMargins
legendPosition
grid
markers
rangeMarkers
min[Value]
max[Value]
xMin[Value]
xMax[Value]
yMin[Value]
yMax[Value]
xAxis
yAxis
topAxis
rightAxis
useLocalEngine
resolution
urlLimit

Have a look at the Charting parameters list to know about these parameters

addDefaultReportParameter, clearDefaultReportParameter, removeDefaultReportParameter, setDefaultReportParameters¶

These methods can be used to manage a map of default parameters for the report, you can:

add a new parameter, using addDefaultReportParameter(String key, Object value)
clear the map of parameter, using clearDefaultReportParameter()
remove one value, using removeDefaultReportParameter(String key)
set more than one value at a time, using setDefaultChartParameters(JSObject mapOfParameters)

The list of default parameters that you can set for reports (which will be used for all reports, but can be overriden by any call to create a report), is:

dateFormat, the default format for dates in reports, same syntax as the dataProvider format
numberFormat, the default format for number in reports, same syntax as the dataProvider format
oneBasedLoops, set whether to use 1-based loops (Servoy behavior) or 0-based loops (default, Java behavior) for fooundset.getRecord() and dataset.getRow()
jsonDateFormat, set to one of JSONDATE constants to produce different date output in JSON
convertDate, a boolean, default false, set the fromJSON() method to try and convert date strings to a Date object
printParams, a JSObject which defines the default parameters to use for printing:
- showDialog: a boolean, default to true
- size: one of the PRINTSIZE constants, default to NA_LETTER
- tray: cannot be used if size is set, one of the PRINTMEDIATRAY constants, default to MAIN
- orientation: one of the PRINTORIENTATION constants, default to PORTRAIT
- copies: an integer for the number of copies to print, default to 1
- sheetCollate: one of the PRINTSHEETCOLLATE constants, used when printing many copies (for example, the pages of a 3-page, 2-copy with PRINTSHEETCOLLATE.COLLATED will print as (1,2,3,1,2,3), but the pages of the same document with PRINTSHEETCOLLATE.UNCOLLATED will be printed as (1,1,2,2,3,3)) - default to COLLATED
- sides: one of the PRINTSIDE constants, useful for printers capable of printing on both sides of pages, default to ONE_SIDED
- preferredPrinter: a String with the name of a printer available, default to null which will use the default printer of the system
- scaleWidth: a Number (double) to scale the output width (default 1.0 = 100%)
- scaleHeight: a Number (double) to scale the output height (default 1.0 = 100%)
- areaUnit: One of PRINTUNIT (INCH, CM, MM)
- areaWidth: The width of the page to print (in the unit expressed by areaUnit) - used instead of size to force a non standard size
- areaHeight: The height of the page to print (in the unit expressed by areaUnit) - used instead of size to force a non standard size

addDefaultPreviewParameter, clearDefaultPreviewParameter, removeDefaultPreviewParameter, setDefaultPreviewParameters¶

These methods can be used to manage a map of default parameters for the report, you can:

add a new parameter, using addDefaultPreviewParameter(String key, Object value)
clear the map of parameter, using clearDefaultPreviewParameter()
remove one value, using removeDefaultPreviewParameter(String key)
set more than one value at a time, using setDefaultPreviewParameters(JSObject mapOfParameters)

The list of default parameters that you can set for the preview window or component (which will be used for all preview, but can be overriden by any call to create preview, and manipulated in realtime using the Viewer object properties and methods), is:

useSaveLocalPDF, a boolean to determine if a PDF should be saved locally
useTogglePaginated, a boolean to setup the preview with a toggle paginate button
useFontZoom, a boolean to setup the preview with a zoom font button
useZoom, a boolean to setup the preview with a zoom button
usePrint, a boolean to setup the preview with a print button
savePDFResolution, an integer to determine the resolution of the PDF (one of REPORT.resolution)
saveCallback, a Servoy callback function to call when the user clicks on the save button
printCallback, a Servoy callback function to call when the user clicks on the print button
documentLoadedCallback, a Servoy callback function to call when the document is loaded in the preview window
showToolBar, a boolean to determine whether to show the toolbar or not
showStatus, a boolean to determine whether to show the status zone or not
[preview]Bounds, an array of [x,y,w[idth],h[eight]] integers to setup the preview boundaries
h[orizontal]Scrollbar, a boolean to force show the horizontal scrollbar
v[ertical]Scrollbar, a boolean to force show the vertical scrollbar
border, a boolean to show a border around the document or not
printParams, a JSObject which defines the default parameters to use for printing:
- showDialog: a boolean, default to true
- size: one of the PRINTSIZE constants, default to NA_LETTER
- tray: cannot be used if size is set, one of the PRINTMEDIATRAY constants, default to MAIN
- orientation: one of the PRINTORIENTATION constants, default to PORTRAIT
- copies: an integer for the number of copies to print, default to 1
- sheetCollate: one of the PRINTSHEETCOLLATE constants, used when printing many copies (for example, the pages of a 3-page, 2-copy with PRINTSHEETCOLLATE.COLLATED will print as (1,2,3,1,2,3), but the pages of the same document with PRINTSHEETCOLLATE.UNCOLLATED will be printed as (1,1,2,2,3,3)) - default to COLLATED
- sides: one of the PRINTSIDE constants, useful for printers capable of printing on both sides of pages, default to ONE_SIDED
- preferredPrinter: a String with the name of a printer available, default to null which will use the default printer of the system
- scaleWidth: a Number (double) to scale the output width (default 1.0 = 100%)
- scaleHeight: a Number (double) to scale the output height (default 1.0 = 100%)
- areaUnit: One of PRINTUNIT (INCH, CM, MM)
- areaWidth: The width of the page to print (in the unit expressed by areaUnit) - used instead of size to force a non standard size
- areaHeight: The height of the page to print (in the unit expressed by areaUnit) - used instead of size to force a non standard size

See the FAQ for more information on these parameters.

evaluateWithContext¶

This method will allow you to use the power of Velocity to build some text or html using a String template and a Context object.
The signature is:
String evaluateWithContext(String templateContent, JSObject contextObject, [REPORT.resolution])

Basically, you pass it a String, containing placeholders ($variable) and then pass it a JSObject (new Object() or {}) filled with any kind of Servoy object to replace the placeholders.
Optionally you can define a REPORT.resolution (either REPORT.RESOLUTION_LOW or REPORT.RESOLUTION_HIGH, or an integer) for charts.

See Velocity to know more about Velocity templating, and Charting for charts options

getBarcode¶

This method will create a Barcode URL that you will be able to use in html, either in a report or in a HTML_AREA field.
The signature is:
BarcodeWrapper getBarcode(JSObject parameters, [REPORT.resolution])

You can use the BarcodeWrapper object as a simple String to be put in html.
See the Barcode page for more info on the parameters to use and how to produce barcodes.

getChart¶

This method will create a Chart URL that you will be able to use in html either in a report or in a HTML_AREA field
The signature is:
ChartWrapper getChart(CHART.type, JSObject parameters, boolean useLocalEngine, [REPORT.resolution])

You can use the ChartWrapper object as a simple String to be put in html.
See the Charting page for more info on the parameters to use and how to produce charts.

getMedia¶

Will return a media URL suitable for use in preview on the web and in PDF reports.
The signature is
MediaWrapper getMedia(String mediaName, [String id], [int width], [int height], [String cssClass])

You can use the MediaWrapper object as a simple String to be put in html, it is especially useful to produce a URL for PDF and for html preview in web client.

getByteMedia¶

@since v3.2

Will embed an <object> tag into the xHTML with Base64 encoded content of the image byte array.
The PDF engine will produce the image directly based on that encoded content.

The signature is
ByteMediaWrapper getByteMedia(byte[], [String id], [int width], [int height], [String cssClass])

getNonQuotable¶

@since v3.5.7

Will create an object that will not be quoted in JSON serialization, useful in Velocity templates used in browsers, to return references to client side javascript functions.

The signature is
NonQuotableWrapper getNonQuotable(String value)

getPDFReport¶

Execute the merging of a template and context and produce a PDF out of the xhtml, then returns the PDF bytes.
The signature is
byte[] getPDFReport(String templateNameOrContent, JSObject contextObject, [REPORT.resolution], [PDF.version])

Given a xhtml template as String or the name of a template file on the server, and a JSObject (new Object() or {}) containing any relevant Servoy objects to fill the report, and optionally a resolution (either REPORT.RESOLUTION_LOW for web or REPORT.RESOLUTION_HIGH for printing, or an integer factor), and a PDF.version form one of the PDF constants), it will compile a PDF report and return the bytes of the file, to be saved to disk or to the database.

getVersion¶

Will return the version of the plugin (useful for debugging), the version is also visible on the servoy admin plugins page

installFonts¶

Will look into the content of a /fonts/ sub-folder in the root report folder of the server to download the font files on the client.
Can use an optional callback function to be called upon download completion of each font. The process will store the fonts in a /fonts/ subfolder of the /.servoy/ cache folder directory, and will check if the fonts are present and if they need to be updated.
The signature is
void installFonts([callbackFunction])
The font installed will be usable in the preview Window and Panel and embedded in the resulting PDF, providing you are using them in your template with CSS.
NB: on the web client when using PREVIEW.PDF, the preview being done in a browser, the html displayed report will fallback to the system installed fonts.

previewReport¶

This method will open a new (modeless) Dialog with a preview of the PDF report, done from a xhtml template as String or the name of a template file on the server, merging a JSObject (new Object() or {}) containing any relevant Servoy objects to fill the report, an optional Servoy method to call with PDF byte[] when the save button is clicked, another optional method to call with the PDF byte[] when the print button is clicked, and a preview mode for the web client (either PREVIEW.PDF or PREVIEW.HTML).
The signature is:
Viewer previewReport(String templateNameOrContent, JSObject contextObject, [Function saveCallBackFunction], [Function printCallBackFunction], [PREVIEW.mode])

What differenciates between a template name or the actual content, is the presence of a "fromString" boolean in the contextObject. If true, the plugin will verify that the text is html, and will use it as such, otherwise it will try to download the template file from the server. If you give the method a template content instead of a file, you will need to set a "baseHREF" property in the contextObject as well, this is because if the html refers to external files (for CSS or images), the plugin will need to know where to find them, so a URL relative to the place where you would have put the html file will serve to locate these files (the URL can be http, https, but also file:/// for local files on the client side).
On the smart client, the method returns a Viewer which will allow manipulating the Dialog with scripting and updating the report.

previewToComponent¶

This one is similar to the previous, except that it will not open a new Dialog, but will render the preview panel inside a JPanel given as first parameter.
The signature is:
Viewer previewToComponent(JPanel parent, String templateNameOrContent, JSObject contextObject, [Function saveCallBackFunction], [Function printCallBackFunction])

This method will NOT work on web client since it uses a Java Swing bean.
On the smart client, the method returns a Viewer which will allow manipulating the panel with scripting and updating the report.

printReport¶

Will print the report in a background Thread (calling the standard print setup dialog beforehand).
Can also be called from the Viewer object.
The signature is
printReport(String templateNameOrContent, JSObject contextObject, [JSObject printParams])

The method will work in smart client only! On web client, use previewReport instead with a PREVIEW.MODE set to PDF as this will return a PDF suitable for printing.

The printParams object overrides the one from the defaultReportParameters, with the same properties available:

showDialog: a boolean, default to true
size: one of the PRINTSIZE constants, default to NA_LETTER
tray: cannot be used if size is set, one of the PRINTMEDIATRAY constants, default to MAIN
orientation: one of the PRINTORIENTATION constants, default to PORTRAIT
copies: an integer for the number of copies to print, default to 1
sheetCollate: one of the PRINTSHEETCOLLATE constants, used when printing many copies (for example, the pages of a 3-page, 2-copy with PRINTSHEETCOLLATE.COLLATED will print as (1,2,3,1,2,3), but the pages of the same document with PRINTSHEETCOLLATE.UNCOLLATED will be printed as (1,1,2,2,3,3)) - default to COLLATED
sides: one of the PRINTSIDE constants, useful for printers capable of printing on both sides of pages, default to ONE_SIDED
preferredPrinter: a String with the name of a printer available, default to null which will use the default printer of the system
scaleWidth: a Number (double) to scale the output width (default 1.0 = 100%)
scaleHeight: a Number (double) to scale the output height (default 1.0 = 100%)
areaUnit: One of PRINTUNIT (INCH, CM, MM)
areaWidth: The width of the page to print (in the unit expressed by areaUnit) - used instead of size to force a non standard size
areaHeight: The height of the page to print (in the unit expressed by areaUnit) - used instead of size to force a non standard size

renderTemplate¶

Same as evaluateWithContext, but using a template located on the server side within the default report folder.
The signature is:
String renderTemplate(String templateContent, JSObject contextObject, [REPORT.resolution])

wrapTemplate¶

Can be used to add sub templates created from a dynamic (in-memory) String resource coming from anywhere.
The signature is:
WrappedTemplate wrapTemplate(String|Function|File|JSFile|byte[])

You can use this method to create a dynamic template, put it in the context and later use it in the template. For example:

function getSubTemplate() {
    return "#foreach($record in $foundset)\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
  $record.id
#end";
}

You can add it to your context object:

context.subTemplate = plugins.VelocityReport.wrapTemplate(getSubTemplate); 
// or even:
context.subTemplate = plugins.VelocityReport.wrapTemplate(getSubTemplate()); // in which case the String itself will be used

Then in your template you will be able to use:

#parse($subTemplate)

toJSON¶

Used to serialize a JavaScript object, and array or a FoundSetWrapper (see below).
This method produces pure JSON serialization.
An optional boolean can be used. When set to true, it will serialize null values, otherwise, by default it will not serialize them.

var serialized = plugins.VelocityReport.toJSON(object, [serializeNull]);

fromJSON¶

Used to deserialized an object or array from a String previously serialized from the toJSON method.
This method will only deserialize as objects, arrays and primitive values, it cannot produce a foundset or a dataset.

var object = plugins.VelocityReport.fromJSON(serializedString);

There are 2 optional parameters to this method, so the full signature is fromJSON(serializedString, [convertHtmlEntities], [convertDate])
- convertHtmlEntities (boolean, default=false) - setting it to true will translate & / < / > into their respective character (&, <, >)
- convertDate (boolean, default=true) - by default the method will attempt to parse date strings and convert these to Date objects, setting it to false will return the date string as-is

wrapFoundset¶

Can be used to create a FoundSetWrapper object, that will be serialized with related foundsets, for JSON or XML usage.
The resulting object can then be used in a context to be returned as JSON/XML or serialized to JSON using the plugins.VelocityReport.toJSON() method.

The signature is:
FoundSetWrapper wrapFoundset(foundset, arrayOfRelationNames);

var foundsetWrapper = plugins.VelocityReport.wrapFoundset(foundset, ['orders_to_order_items', 'orders_to_companies', 'orders_to_contacts', 'orders_to_order_items.order_items_to_products']);
var context = {fs: foundsetWrapper};
return plugins.Velocity.createResponse(context);

getReportFolder¶

Will return the folder folder (as set in the servoy-admin plugin properties)

getServerURL¶

Will return the server URL (as set in the servoy-admin plugin properties)

Files (0)

Project

General

Profile

VelocityReport Plugin

Wiki