Installation API User Guide
Installation Icon

API Options and methods

ReportBro Designer Configuration Options

Option Type Default Description 
additionalFonts
 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.

@font-face {
    font-family: "myfont";
    src: url("fonts/myfont.ttf");
}
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. 
adminMode
 
boolean
 
true
 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. 
cmdExecutedCallback
 
function
 
null
 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. 
colors
 array of strings 
[
    "#000000","#444444","#666666","#999999",
    "#cccccc","#eeeeee","#f3f3f3","#ffffff",
    "#ff0000","#ff9900","#ffff00","#00ff00",
    "#00ffff","#0000ff","#9900ff","#ff00ff",
    "#ea9999","#f9cb9c","#ffe599","#b6d7a8",
    "#a2c4c9","#9fc5e8","#b4a7d6","#d5a6bd",
    "#e06666","#f6b26b","#ffd966","#93c47d",
    "#76a5af","#6fa8dc","#8e7cc3","#c27ba0",
    "#cc0000","#e69138","#f1c232","#6aa84f",
    "#45818e","#3d85c6","#674ea7","#a64d79",
    "#990000","#b45f06","#bf9000","#38761d",
    "#134f5c","#0b5394","#351c75","#741b47",
    "#660000","#783f04","#7f6000","#274e13",
    "#0c343d","#073763","#20124d","#4c1130"
]
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. 
defaultFont
 
string
 
"helvetica"
 Font which will be used as default for new text elements and styles. 
enableSpreadsheet
 
boolean
 
true
 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. 
fontSizes
 array of numbers 
[
    4,5,6,7,8,9,10,11,12,13,14,15,16,18,20,22,
    24,26,28,32,36,40,44,48,54,60,66,72,80
]
Font sizes which are available in font size drop down within the text style section. 
fonts
 array of array containing name (string) and value (string) 
[
  { name: 'Courier', value: 'courier' },
  { name: 'Helvetica', value: 'helvetica' },
  { name: 'Times New Roman', value: 'times' }
]
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. 
highlightUnusedParameters
 
boolean
 
false
 If true then unused parameters are highlighted when the report is loaded. When the report is saved the highlight marker is removed. 
localStorageReportKey
 
string
 
null
 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. 
locale
 array containing label keys and translation values 
en_us locale
 Pass your own translations to show the designer in another language. 
localeKey
 
string
 
"en_us"
 Defines the locale to use. There are currently locales available for English (US) and German with the localeKey "en_us" and "de_de" respectively. 
menuShowButtonLabels
 
boolean
 
false
 If true labels are shown next to the icon for action buttons (save, undo/redo, preview). 
menuShowDebug
 
boolean
 
false
 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. 
menuSidebar
 
boolean
 
false
 Display report designer menu bar as vertical sidebar instead of horizontal menu on top. 
patternCurrencySymbol
 
string
 
"$"
 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. 
patternLocale
 
string
 
"en"
 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'. 
patternDates
 
string
 
[
  { name: 'd.M.yyyy', value: 'patternDate1' },
  { name: 'd.M.yy, H:mm', value: 'patternDate2' },
  { name: 'd/MMM/yyyy', value: 'patternDate3' },
  { name: 'MM/dd/yyyy', value: 'patternDate4' }
]
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. 
patternNumbers
 array of array containing name (string) and description (string) 
[
  { name: '#,##0', value: 'patternNumber1' },
  { name: '0.000', value: 'patternNumber2' },
  { name: '0.00##', value: 'patternNumber3' },
  { name: '#,##0.00', value: 'patternNumber4' }
  { name: '$ #,##0.00', value: 'patternNumber5' }
]
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. 
patternAdditionalDates
 array of array containing name (string) and description (string) 
[]
 These date patterns will be added to patternDates. 
patternAdditionalNumbers
 array of array containing name (string) and description (string) 
[]
 These number patterns will be added to patternNumbers. 
reportServerBasicAuth
 map containing values for username and password 
null
 If present the basic auth header will be set for report preview requests. 
reportServerHeaders
 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. 
reportServerTimeout
 
string
 
20000
 Timeout (in msec) for the report preview ajax request. 
reportServerUrl
 
string
 
"https://www.reportbro.com/report/run"
 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. 
requestCallback
 
function
 
null
 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. 
saveCallback
 
function
 
null
 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. 
selectCallback
 
function
 
null
 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. 
showGrid
 
boolean
 
true
 If true the grid for the document content will be initially shown. 
showPlusFeatures
 
boolean
 
true
 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. 
showPlusFeaturesInfo
 
boolean
 
true
 If true then an info message is shown for features which are only available in the commercial PLUS version. 
theme
 
string
 
""
 Theme for css styling. Currently "classic" theme is supported.

ReportBro Designer Methods

Method Description 
setModified(modified)
 Sets the internal modified flag. If true the save button is enabled, otherwise the save button is disabled. 
isModified()
 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). 
getReport()
 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. 
save()
 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. 
load(report)
 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. 
loadLocalReport()
 Loads a report from local storage. The report is retrieved from local storage with the key defined in localStorageReportKey. 
preview()
 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. 
previewWithData(data)
 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. 
downloadSpreadsheet()
 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. 
processErrors(errors, clear)
 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. 
clearErrors()
 Clears all error classes (which highlight elements with errors) and all error messages. 
destroy()
 Deletes ReportBro instance including all dom nodes and all registered event handlers. 
getUniqueId()
 Returns a new unique id which can be used for any data object. 
getDocElementById(id)
 Returns document element for the given id, or null if document element does not exist. 
getParameterById(id)
 Returns parameter for the given id, or null if parameter does not exist. 
getParameterByName(parameterName)
 Returns parameter for the given name, or null if parameter does not exist. 
getStyleById(id)
 Returns style for the given id, or null if style does not exist. 
createDocElement(docElementData)
 Creates a doc element with given data. 
createParameter(parameterData)
 Creates a parameter with given data. 
createStyle(styleData)
 Creates a style with given data. 
deleteDocElement(element)
 Deletes given doc element. Deletes internal object and all related GUI elements (panel item, layout element). 
deleteParameter(parameter)
 Deletes given parameter. Deletes internal object and all related GUI elements (panel item, layout element). 
deleteStyle(style)
 Deletes given style. Deletes internal object and all related GUI elements (panel item, layout element).

ReportBro Lib Arguments

Argument Description Example 
report_definition
 The report object containing report elements, parameters, styles and document properties. This object can be obtained in ReportBro Designer by using getReport method. 

{
    'docElements': [{
        'alwaysPrintOnSamePage': True,
        'backgroundColor': '#ffe599',
        'band': 2,
        'bold': True,
        'borderAll': False,
        'borderBottom': False,
        'borderColor': '#000000',
        'borderLeft': False,
        'borderRight': False,
        'borderTop': False,
        'borderWidth': 1,
        'content': 'Sample Header Text',
        'cs_backgroundColor': '',
        'cs_bold': False,
        'cs_borderAll': False,
        'cs_borderBottom': False,
        'cs_borderColor': '#000000',
        'cs_borderLeft': False,
        'cs_borderRight': False,
        'cs_borderTop': False,
        'cs_borderWidth': '1',
        'cs_condition': '',
        'cs_font': 'helvetica',
        'cs_fontSize': 12,
        'cs_horizontalAlignment': 'left',
        'cs_italic': False,
        'cs_lineSpacing': 1,
        'cs_paddingBottom': 2,
        'cs_paddingLeft': 2,
        'cs_paddingRight': 2,
        'cs_paddingTop': 2,
        'cs_styleId': '',
        'cs_textColor': '#000000',
        'cs_underline': False,
        'cs_verticalAlignment': 'top',
        'elementType': 'text',
        'eval': False,
        'font': 'helvetica',
        'fontSize': '20',
        'height': 60,
        'horizontalAlignment': 'center',
        'id': 8,
        'italic': False,
        'lineSpacing': 1,
        'paddingBottom': 2,
        'paddingLeft': 2,
        'paddingRight': 2,
        'paddingTop': 2,
        'pattern': '',
        'printIf': '',
        'removeEmptyElement': False,
        'spreadsheet_addEmptyRow': False,
        'spreadsheet_column': '',
        'spreadsheet_hide': False,
        'styleId': '',
        'textColor': '#000000',
        'underline': False,
        'verticalAlignment': 'middle',
        'width': 595,
        'x': 0,
        'y': 30}, {
        'alwaysPrintOnSamePage': True,
        'backgroundColor': '',
        'band': 2,
        'bold': False,
        'borderAll': False,
        'borderBottom': False,
        'borderColor': '#000000',
        'borderLeft': False,
        'borderRight': False,
        'borderTop': False,
        'borderWidth': 1,
        'content': 'Date: ${report_date}',
        'cs_backgroundColor': '',
        'cs_bold': False,
        'cs_borderAll': False,
        'cs_borderBottom': False,
        'cs_borderColor': '#000000',
        'cs_borderLeft': False,
        'cs_borderRight': False,
        'cs_borderTop': False,
        'cs_borderWidth': '1',
        'cs_condition': '',
        'cs_font': 'helvetica',
        'cs_fontSize': 12,
        'cs_horizontalAlignment': 'left',
        'cs_italic': False,
        'cs_lineSpacing': 1,
        'cs_paddingBottom': 2,
        'cs_paddingLeft': 2,
        'cs_paddingRight': 2,
        'cs_paddingTop': 2,
        'cs_styleId': '',
        'cs_textColor': '#000000',
        'cs_underline': False,
        'cs_verticalAlignment': 'top',
        'elementType': 'text',
        'eval': False,
        'font': 'helvetica',
        'fontSize': 12,
        'height': 20,
        'horizontalAlignment': 'left',
        'id': 10,
        'italic': False,
        'lineSpacing': 1,
        'paddingBottom': 2,
        'paddingLeft': 10,
        'paddingRight': 2,
        'paddingTop': 2,
        'pattern': '',
        'printIf': '',
        'removeEmptyElement': False,
        'spreadsheet_addEmptyRow': False,
        'spreadsheet_column': '',
        'spreadsheet_hide': False,
        'styleId': '',
        'textColor': '#000000',
        'underline': False,
        'verticalAlignment': 'top',
        'width': 180,
        'x': 20,
        'y': 140}, {
        'alwaysPrintOnSamePage': True,
        'backgroundColor': '',
        'band': 2,
        'bold': False,
        'borderAll': False,
        'borderBottom': False,
        'borderColor': '#000000',
        'borderLeft': False,
        'borderRight': False,
        'borderTop': False,
        'borderWidth': 1,
        'content': 'Subject: ${subject}',
        'cs_backgroundColor': '',
        'cs_bold': False,
        'cs_borderAll': False,
        'cs_borderBottom': False,
        'cs_borderColor': '#000000',
        'cs_borderLeft': False,
        'cs_borderRight': False,
        'cs_borderTop': False,
        'cs_borderWidth': '1',
        'cs_condition': '',
        'cs_font': 'helvetica',
        'cs_fontSize': 12,
        'cs_horizontalAlignment': 'left',
        'cs_italic': False,
        'cs_lineSpacing': 1,
        'cs_paddingBottom': 2,
        'cs_paddingLeft': 2,
        'cs_paddingRight': 2,
        'cs_paddingTop': 2,
        'cs_styleId': '',
        'cs_textColor': '#000000',
        'cs_underline': False,
        'cs_verticalAlignment': 'top',
        'elementType': 'text',
        'eval': False,
        'font': 'helvetica',
        'fontSize': 12,
        'height': 20,
        'horizontalAlignment': 'left',
        'id': 11,
        'italic': False,
        'lineSpacing': 1,
        'paddingBottom': 2,
        'paddingLeft': 10,
        'paddingRight': 2,
        'paddingTop': 2,
        'pattern': '',
        'printIf': '',
        'removeEmptyElement': False,
        'spreadsheet_addEmptyRow': False,
        'spreadsheet_column': '',
        'spreadsheet_hide': False,
        'styleId': '',
        'textColor': '#000000',
        'underline': True,
        'verticalAlignment': 'top',
        'width': 180,
        'x': 20,
        'y': 110}],
    'documentProperties': {
        'contentHeight': '',
        'footer': True,
        'footerDisplay': 'always',
        'footerSize': '80',
        'header': True,
        'headerDisplay': 'always',
        'headerSize': '80',
        'marginBottom': '',
        'marginLeft': '',
        'marginRight': '',
        'marginTop': '',
        'orientation': 'portrait',
        'pageFormat': 'A4',
        'pageHeight': '',
        'pageWidth': '',
        'patternCurrencySymbol': '$',
        'patternLocale': 'en',
        'unit': 'mm'},
    'parameters': [{
        'eval': False,
        'expression': '',
        'id': 6,
        'name': 'page_count',
        'pattern': '',
        'testData': '',
        'type': 'number'},
        {'eval': False,
        'expression': '',
        'id': 7,
        'name': 'page_number',
        'pattern': '',
        'testData': '',
        'type': 'number'},
        {'eval': False,
        'expression': '',
        'id': 9,
        'name': 'report_date',
        'pattern': 'MM/d/yyyy',
        'testData': '2017-06-01',
        'type': 'date'},
        {'eval': False,
        'expression': '',
        'id': 12,
        'name': 'subject',
        'pattern': '',
        'testData': 'test',
        'type': 'string'}],
    'styles': []
}
 
data

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. 

{'report_date': '2017-06-01','subject': 'test'}
 
is_test_data
 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. 
True
 
additional_fonts
 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. 
[dict(value='Lobster',filename='fonts/lobster.ttf'))]
 
page_limit
 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. 
10000
 
request_headers
 Request headers used when images are fetched by url. 
{'User-Agent': 'Mozilla/5.0
(iPhone; CPU iPhone OS 12_0 like Mac OS X)'}
 
encode_error_handling
 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		 
'ignore'
 
core_fonts_encoding
 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. 
'windows-1250'

ReportBro Lib Methods

Method Description 
generate_pdf(filename='', add_watermark=False)
 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. 
generate_xlsx(filename='')
 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. 
import reportbro
data = dict(invoice_number=7, invoice_date='2020-09-01')
report = reportbro.Report(report_definition, data)
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:
Parameter Type Python Type(s) Examples Notes
Text str 
data = dict(first_name='John')
Number Decimal
int
float
str 
import decimal
data = dict(
    amount=99, total_price=decimal.Decimal('299.90'),
    avg_price=70.17, max_price='549.99')
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 
offers = []
data = dict(
    special_offer=True, offers_available=offers)
 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		 
import datetime
data = dict(
    subscription_date=datetime.date(2020, 10, 1),
    start_time=datetime.datetime(2020, 10, 7, 13, 44),
    valid_until='2020-12-31',
    end_time='2020-10-07 20:08')
 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 
import io
logo_default = open('rbro_logo.png', 'rb')
# base64 image data discarded to keep
# the example compact
logo_v2 = 'data:image/png;base64,iVBOR...II='
data = dict(
    logo_default=logo_default,
    logo_v2=logo_v2)
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 
screenshot = 'https://reportbro.com/static/images/demo_app.png'
header_img = 'file:static/images/header.png'
data = dict(screenshot=screenshot, header_img=header_img)
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 item type of List parameter is 'Text'
product_names = ['Tablet', 'Desk', 'Car']
data = dict(
    product_names=product_names)
List list 
delivery_items = [
    dict(
        name='Pineapples',
        quantity=380,
        category='Fruits'),
    dict(
        name='Tomatoes',
        quantity=2312,
        category='Vegetables')]
data = dict(
    DeliveryItems=delivery_items)
Collection dict 
invoice_details = dict(
    InvoiceNumber=123, InvoiceDate='2020-10-01',
    InvoiceAmount='224.50')
data = dict(
    InvoiceDetails=invoice_details)