API Options and methods
ReportBro Designer Configuration Options
Option | Type | Default | Description |
---|---|---|---|
|
array of array containing name (string) and value (string) |
|
These fonts will be added to fonts.
In case additional (non-standard) fonts are used they must be made
available with a font-face css defintion, e.g.
The font-family must match the value
from the font entry. It must further match the value definition of
additional fonts passed to the ReportBro Lib instance.
See ReportBro Lib methods
on how to configure additional fonts on the server.
|
|
|
|
If false no parameters can be added, deleted or modified. This can be used when existing reports can be adapted by your web application users. Since parameters are more complex and reference server data, it is usually not recommended for normal users to change them. |
|
|
|
If true the save method is called when report is previewed. |
|
|
|
Function which is called when a command is executed.
For example this could be used to perform auto-save after every n-th
executed command.
The function gets two parameters, first the executed command and second a boolean value which is false if this is an undo command. |
|
array of strings |
|
Colors which are shown in the color palette for color selection. Each entry is a color hex code containing red, green and blue hex values. |
|
|
|
Font which will be used as default for new text elements and styles. |
|
|
|
If false the spreadsheet section for various elements (text, image, table, barcode) is hidden. Further no xlsx download link is shown in the preview tab. |
|
array of numbers |
|
Font sizes which are available in font size drop down within the text style section. |
|
array of array containing name (string) and value (string) |
|
Fonts which are available in font drop down within the text style section. Each font entry contains an array with name and value, where name is displayed in the drop down and value is used to identify the font in ReportBro Designer and ReportBro Lib. |
|
|
|
If true then unused parameters are highlighted when the report is loaded. When the report is saved the highlight marker is removed. |
|
|
|
Defines the maximum number of allowed image elements in the report template. If value is null there is no image limit. |
|
|
|
If set images are downscaled to reduce image size. Images are scaled down so that width and height are less than or equal to imageMaxSize. |
|
|
|
Images are converted to WebP format to reduce image size.
If set to true and the browser does not support WebP format an error message is shown.
If set to false and the browser does not support WebP format images are converted to png or kept in the original format (depending which image is smaller). |
|
|
|
If set and saveCallback is not set this key is used to store the report in the Browser's local storage when the save method is called. Further it is used in the loadLocalReport method to load the report from local storage. |
|
array containing label keys and translation values |
|
Pass your own translations to show the designer in another language. |
|
|
|
Defines the locale to use. There are currently locales available for English (US) and German with the localeKey "en_us" and "de_de" respectively. |
|
|
|
If true labels are shown next to the icon for action buttons (save, undo/redo, preview). |
|
|
|
If true action buttons are shown to log the report template in the javascript console and to open a dialog where a report template can be inserted. |
|
|
|
Display report designer menu bar as vertical sidebar instead of horizontal menu on top. |
|
|
|
The default pattern currency symbol in the document properties. This is only used for a new report, otherwise it is overriden from loaded report. The pattern currency symbol is inserted when a number is formatted with a pattern containing the currency symbol. |
|
|
|
The default pattern locale in the document properties. This is only used for a new report, otherwise it is overriden from loaded report. The pattern locale is used when a date or number is formatted with a pattern. Allowed values are 'de', 'en', 'es', 'fr' and 'it'. |
|
|
|
The patterns are shown in a popup window when a date pattern input is selected. Each pattern entry contains an array with name and description. The name must be a valid date pattern. See Date Pattern Syntax for further details. |
|
array of array containing name (string) and description (string) |
|
The patterns are shown in a popup window when a number pattern input is selected. Each pattern entry contains an array with name and description. The name must be a valid number pattern. See Number Pattern Syntax for further details. |
|
array of array containing name (string) and description (string) |
|
These date patterns will be added to patternDates. |
|
array of array containing name (string) and description (string) |
|
These number patterns will be added to patternNumbers. |
|
map containing values for username and password |
|
If present the basic auth header will be set for report preview requests. |
|
map containing custom header values |
|
If present these header values will be set for report preview requests. If you support CORS (Cross-Origin Resource Sharing) server-side then you must allow those headers in your server response with the 'Access-Control-Allow-Headers' header. |
|
|
|
Timeout (in msec) for the report preview ajax request. |
|
|
|
The url which is used in the preview method to generate the report. Replace this url with your endpoint in case you are running your own server to generate reports. Initially a 'PUT' request is sent to the server to verify the report and upload report definition in case the report is valid. A uuid key is returned for this request which uniquely identifies the report. This key is used in the following 'GET' request in the url for pdf preview and when downloading the xlsx file. |
|
|
|
Function which is called before a request (for pdf or xlsx preview) is sent.
This can be used to modify the request parameters like
reportServerTimeout or
reportServerHeaders.
The function gets a parameter object which contains all available request parameters which can be modified. |
|
|
|
Function which is called when save button is clicked. This can be used to get the report (see getReport) and make an ajax call to your web app to save the report in your application. If the report was saved successfully you should set the modified flag to false (see setModified) so the save button gets disabled. |
|
|
|
Function which is called when an element is selected or deselected. The function takes two arguments, the selected object (element, parameter, style or document properties) and a bool parameter if the object was selected or deselected. |
|
|
|
If true the grid for the document content will be initially shown. |
|
|
|
If true then features which are only available in the commercial PLUS version are shown. These features require reportbro-lib-plus on the server for report generation. |
|
|
|
If true then an info message is shown for features which are only available in the commercial PLUS version. |
|
|
|
Theme for css styling. Currently "classic" theme is supported. |
ReportBro Designer Methods
Method | Description |
---|---|
|
Sets the internal modified flag. If true the save button is enabled, otherwise the save button is disabled. |
|
Returns the internal modified flag. If the flag is true the save button is enabled, otherwise the save button is disabled and there was no change to the report since the flag was last set to false (this happens after save or by calling the setModified API method). |
|
Returns an object containing the whole report, including report elements, parameters, styles and document properties. This object is used to generate reports in the report-lib package. Use this method to save designed reports on your server. |
|
Called when pressing the save button in the ReportBro Designer menu bar. Executes a callback initialized as saveCallback or saves the report in local storage if localStorageReportKey property is defined. The method needs either saveCallback or localStorageReportKey. |
|
Takes a report object as parameter and loads it into the ReportBro Designer. The report object can be obtained with the getReport method. The usual process is to save a designed report in your web application using getReport and upload it to your server. Later you retrieve the report from your application and use the load method to initialize ReportBro Designer with it. |
|
Loads a report from local storage. The report is retrieved from local storage with the key defined in localStorageReportKey. |
|
Uses the current report and test data to make a request to the report server (using reportServerUrl) to get a report document. PDF documents are displayed in the preview tab within ReportBro Designer. |
|
Similar to preview but uses the given data instead of test data. This can be useful in case you want to test a report with real data (usually retrieved by an ajax call from your server in advance). In case there are any errors during report creation the errors are directly displayed in ReportBro Designer. |
|
Downloads the xlsx report (using reportServerUrl) in a separate tab. It uses the report previously created for preview (with preview or previewWithData method). This is a workaround to preview xlsx reports in ReportBro Designer. Because there is no embedded preview the report must be opened in a separate tab. Since the url cannot contain any post parameters the last previewed report, which is saved server-side and identified by a key, is downloaded. |
|
Displays the given errors. This method is called after a failed report preview. You can use it in case you want to perform additional validations (e.g. after each save operation) and want to display possible errors. The errors are returned from reportbro-lib during report creation. errors is a list of errors where each item is a map which contains
object_id (Number), field (String), msg_key (String) and optional info (String).
clear can be used to clear existing errors from a previous
validation.
|
|
Clears all error classes (which highlight elements with errors) and all error messages. |
|
Deletes ReportBro instance including all dom nodes and all registered event handlers. |
|
Returns a new unique id which can be used for any data object. |
|
Returns document element for the given id, or null if document element does not exist. |
|
Returns parameter for the given id, or null if parameter does not exist. |
|
Returns parameter for the given name, or null if parameter does not exist. |
|
Returns style for the given id, or null if style does not exist. |
|
Creates a doc element with given data. |
|
Creates a parameter with given data. |
|
Creates a style with given data. |
|
Deletes given doc element. Deletes internal object and all related GUI elements (panel item, layout element). |
|
Deletes given parameter. Deletes internal object and all related GUI elements (panel item, layout element). |
|
Deletes given style. Deletes internal object and all related GUI elements (panel item, layout element). |
ReportBro Lib Arguments
Argument | Description | Example |
---|---|---|
|
The report object containing report elements, parameters, styles and document properties. This object can be obtained in ReportBro Designer by using getReport method. |
|
|
Dictionary containing all data for the report. This structure must correspond with the defined parameters. E.g. if the report contains a list or a date parameter then data must also contain a list or date parameter with the same name. See below on details how to pass parameters. |
|
|
Set to True in case the given data contains test data which is specified within the parameters in ReportBro Designer. Set to False if the data comes from your web application. This setting influences the error messages in case report generation fails due to invalid data. |
|
|
In case additional (non-standard) fonts are used they must be made available for
ReportBro Lib so they can be embedded into the pdf file. This argument is a list of
dicts value: used to identify the font. It has to match the configured font-family value in ReportBro Designer. See additionalFonts property on how to configure additional fonts in ReportBro Designer. filename: filename including relative or absolute path to .ttf file. bold_filename: filename for bold font. If not specified the regular font will be used for bold text. italic_filename: filename for italic font. If not specified the regular font will be used for italic text. bold_italic_filename: filename for bold italic font. If not specified the regular font will be used for bold italic text. uni: TTF Unicode flag, if set to True (default), TrueType font subset embedding will be enabled and text will be treated as utf8 by default. |
|
|
Defines the maximum number of pages printed in a pdf document. If the page limit is exceeded during report generation then an exception will be thrown. If set to None or 0 there will be no page limit. |
|
|
Request headers used when images are fetched by url. |
|
|
Defines behaviour when a character cannot be encoded with the encoding used for the core fonts.
The following options exist: 'strict': raise a UnicodeDecodeError exception 'ignore': just leave the character out of the result 'replace': use U+FFFD replacement character |
|
|
defines the encoding when using the core fonts. Default is 'windows-1252' which is usually the best choice for English and many European languages including Spanish, French, and German. |
|
|
Options to change default conversion for string content in spreadsheet.
The dict parameter can contain the following keys: 'strings_to_numbers': enable converting strings to numbers. Default is False. 'strings_to_formulas': enable converting strings to formulas. Default is True. 'strings_to_urls': enable converting strings to urls. Default is True. |
|
|
If set to True an image source can contain a relative path to an image file on the local file system. If set to False an error is thrown in case a path is specified for an image. |
|
|
If set to True an image source can contain an external url. The image will be downloaded on the fly when rendering the report. If set to False an error is thrown in case an url is specified for an image. |
|
ReportBro Lib Methods
Method | Description |
---|---|
|
Generates a pdf report and returns it as a byte string (unless a filename is given). If add_watermark is set to True a watermark image (ReportBro logo) will be displayed on the bottom of each page. If filename is specified the report will be saved to disk under the given filename and no report will be returned by the method. |
|
Generates a xlsx spreadsheet and returns it as a byte string (unless a filename is given). If filename is specified the spreadsheet will be saved to disk under the given filename and no spreadsheet will be returned by the method. |
Report Parameters
When passing parameters to a report you must specify a dict which contains
the data for all parameters, e.g.
Each parameter which is specified in the report template (in ReportBro Designer)
can be passed to the Report instance in a Python dictionary. The name in the dict
must match the parameter name in the report template. The parameter value
must be given depending on the parameter type:
import reportbro
data = dict(invoice_number=7, invoice_date='2020-09-01')
report = reportbro.Report(report_definition, data)
Parameter Type | Python Type(s) | Examples | Notes |
---|---|---|---|
Text | str |
|
|
Number |
Decimal int float
|
|
It is preferred to pass Decimals because floats can lead to
rounding issues and internally all Number parameters are converted
to Decimal anyway.
Always pass a string parameter to the Decimal constructor to avoid any possible rounding issues with floats. e.g. Decimal('3.4') instead of Decimal(3.4), the latter would result in 3.3999... instead of 3.4 |
Boolean |
bool Any Python object |
|
If no bool value is given then the value will be passed to the bool() function which uses the standard truth testing procedure to return True/False. |
Date | datetime date |
|
When a string is given the format can either be '%Y-%m-%d'(only date), '%Y-%m-%d %H:%M'(date with time) or '%Y-%m-%d %H:%M:%S'(date with time including seconds) |
Image |
str Any I/O object which supports read and close methods |
|
If a string is given the image must be base64 encoded. The format for base64 images is "data:image/<image type>;base64,<encoded image data>"<image type> must either be "png", "jpg" or "jpeg". <encoded image data> contains the base64 encoded image data. Supported image file extensions are "png", "jpg" and "jpeg". NOTE: an image source can also be specified by a URI which points to an image. In this case the parameter type must be set to Text, see below. |
Text (Parameter used in image source) | str |
|
The URI must start with "http://", "https://" or "file:" and end with the image file extension ("png", "jpg" or "jpeg"). If a local file ("file:" protocol) is used the file must be inside the current working dir of the application, i.e. no ".." directory specifiers are allowed. |
Simple List |
list
|
|
|
List |
list
|
|
|
Collection |
dict
|
|