Back to homepage

beforetoolbarcreated

This event is triggered before the Toolbar initialization. Use this event to override the default functionality of the Toolbar and customize it without changing webdatarocks.toolbar.js.

As an argument, beforetoolbarcreated gets the toolbar object. Override the existing tabs and add the custom ones using getTabs() method. Each tab is described by the Tab Object.

Tab Object properties

Name	Type	Description
title	String	A label of the tab.
id	String	Id used in CSS styles.
handler	String	Name of the function that handles click on this tab.
icon	String	HTML tag that contains a custom icon for this new tab. You can choose one of the basic vector icons defined in webdatarocks.toolbar.js file.
args	Any	optionalArgument to pass to handler.
menu	Array	optionalDropdown menu items.
mobile	Boolean	optionalIf false, this tab isn’t shown on mobile devices.
ios	Boolean	optionalIf false, this tab isn’t shown on iOS devices.
android	Boolean	optionalIf false, this tab isn’t shown on Android devices.

Example

This sample shows how to add tabs to the Toolbar:

Read a detailed Customizing the Toolbar tutorial to change a view and functionality of the Toolbar.

Number format object is used for defining number formatting in the component.

Properties

Name	Type	Description
name	String	Should be unique because each format is identified by name. The default value is "". The default number format is applied to the measures for which no specific number format exists.
thousandsSeparator	String	Symbol used as a thousand separator. The default value is " " (space).
decimalSeparator	String	Symbol used as a decimal separator. The default value is ".".
decimalPlaces	Number	Defines the number of decimals to appear after decimal separator in the fractional part of the number. The default value is -1, it means the number will not be changed and it will be shown in its original form.
maxDecimalPlaces	Number	Defines the maximum number of decimals to appear after decimal separator in the fractional part of the number. The default value is -1, it means the number will not be changed and it will be shown in the original form.
maxSymbols	Number	Defines the maximum amount of symbols that can be displayed in a cell. The default value is 20.
currencySymbol	String	Symbol which appears near the value (hours, percent, currency symbol etc.). The default value is "".
currencySymbolAlign	String	Defines the positioning of a currency symbol. It could be either "left" or "right". The default value is "left".
isPercent	Boolean	Enables formatting data in percentage form. The behavior is similar to MS Excel. The default value is false. When setting isPercent to true, the numbers will be multiplied by 100 and % symbol will be appended to the result. For example, 0.42 will be converted to 42%. An important thing to note is if currencySymbol is set as % then setting the value of isPercent to true will not multiply the result by 100.
nullValue	String	Specifies the format of null values on the grid. The default value is "".
infinityValue	String	Specifies the format of infinity values on the grid. The default value is "Infinity".
divideByZeroValue	String	Specifies the format of values divided by zero. The default value is "Infinity".
textAlign	String	Defines the positioning of formatted values in cells on the grid. The alignments are "right" or "left". The default value is "right".

Example

Set default number formatting:

Each conditional formatting rule is described by the Conditional Format Object. To define conditional formatting, specify the necessary rules in the report.conditions property.

Properties

Name	Type	Description
formula	String	Condition rule. Can include AND, OR, ==, !=, >, >=, <,<=, -, +, *, /, isNaN(), !isNaN(). #value is used for referring to the value of the cell in the condition. Example: '#value > 3'.
format	Object	Style object applied if the cell value meets the condition. Set color value as hex color codes. This is important for exports to PDF and Excel.
id	Number	optional Identifier in the conditional formatting rule. If id is not specified, the id for the rule is set inside the component automatically.
row	Number	optional Row index where the condition is applied.
column	Number	optional Column index where the condition is applied.
measure	String	optional Measure name to which the condition will be applied.
isTotal	Boolean	optional If undefined, the condition will affect all cells. If true, the condition affects subtotals and totals cells alone. If false it affects only the regular cells.

Example

Add a conditional formatting rule:

const pivot = new WebDataRocks({
  container: "#wdr-component",
  toolbar: true,
  height: 395,
  report: {
    conditions: [{
      formula: "#value > 1000000",
      format: {
        backgroundColor: "#C5E1A5",
        color: "#000000",
        fontFamily: "Arial",
        fontSize: "12px"
      }
    }],
    dataSource: {
      filename: "https://cdn.webdatarocks.com/data/data.csv"
    }
  }
});

Try it out on CodePen.

exportTo(exportType:String, parameters:Object, callback:Function|String)

Exports the content from the grid to Excel, PDF or HTML. Such an export file can be saved both locally and to a server.

Parameters

Name	Type	Description
exportType	String	One of the following export types: "excel", "pdf" or "html".
parameters	Object	optional Describes export parameters. Can have the following properties:
filename	String	optional The name of the export file. The default name is pivot.
destinationType	String	optional Destination for the download. By default, destinationType is set to "file", which means the export file is saved locally. Set destinationType as "server" to save the export file to the server.
url	String	optional The URL to the server script saving the export file. It is required when saving the export file to the server (the export file is passed as a POST parameter).
excelSheetName	String	optional Property to set custom sheet name when exporting to Excel.
showFilters	Boolean	optional If true, shows the filters in exported Excel file.
header	String	optional Only for PDF and HTML export. HTML string added to the export file as a header. For example, "<div>##CURRENT-DATE##</div>".
footer	String	optional Only for PDF and HTML export. HTML string added to the export file as a footer. For example, "<div>##CURRENT-DATE##</div>".
pageOrientation	String	optional Page orientation for PDF file. By default, pageOrientation is set to "portrait", which means the export file is saved in portrait mode. Set pageOrientation as "landscape" to save the export file in landscape mode.
callback	Function | String	optional Callback handler, which is called after the export process is finished.

Examples

1) Export content to Excel or PDF:

2) Export content to PDF with a custom header, save it to a server and add a callback:

webdatarocks.exportTo(
  "pdf",
  {
    header:"<div>##CURRENT-DATE##</div>",
    destinationType: "server",
    url: "URL to server script saving the file"
  },
  function () {
    console.log("Export process is finished");
  }
);

load(reportURL:String)

Loads the report file with all configurations from the specified URL.

Parameters

Name	Type	Description
reportURL	String	The URL to the report JSON file (either local or remote).

Example

Load a report from the specified location:

save(parameters:Object)

Saves all current configurations, such as data source, formatting, which data is displayed. All these configurations are saved in a JSON file called report. Such report can be saved both locally and to a server.

Parameters

Gets parameters object as an input parameter. This object can have the following properties:

Name	Type	Description
filename	String	optional The name of the report file. The default name is report.json.
destination	String	optional Destination for the download. By default, destination is set to "file", which means the report is saved locally. Set destination as "server" to save the report to the server.
url	String	optional The URL to the server script saving the report. It is required when saving the report to the server (the report file is passed as a POST parameter).
embedData	Boolean	optional If true, CSV data is embedded within the report. By default, the report with CSV data is saved with the reference to CSV file.
withDefaults	Boolean	optional If true, the report is saved with the default values for all options.
withGlobals	Boolean	optional If true, the report is saved with the options defined in global object.

Example

Save a report with custom name:

customizeCell(customizationCellFunction: Function)

A hook that is triggered for each cell to customize its content and style. Supports adding links, custom styles, and formatting. Available both as an initialization parameter and an API call.

Parameters

customizationCellFunction — a function that defines which cells will be customized and how. Receives the following parameters:

Parameter	Type	Description
cellStyle	Cell Style Object	Contains information about the cell representation. Use this object to customize cell appearance.
cellData	Cell Data Object	Contains information about the cell and its data.

Cell Style Object

Parameter	Type	Description
attr	Object	Specifies the cell’s attributes and their values. It allows adding custom attributes, which later can be used in CSS selectors. Additional info about CSS attribute selectors.
classes	Array of Strings	Contains all cell’s classes. A new class can be added via the addClass() method (see below).
style	Object	Contains a CSS style for the cell.
tag	String	Contains a tag element of the cell.
text	String	Contains a text of the cell (may contain HTML elements, e.g., images).
addClass(value: String)	Method	Adds a new class to the cell.
toHtml()	Method	Returns the cell as an HTML string.

Example

Add colors to alternate rows:

updateData(newDataSource:Object)

Connects to a new data source whereas filtering, sorting, etc. remain the same.

Parameters

Gets newDataSource object as an input parameter. This object can have the following properties:

Name	Type	Description
filename	String	optional The URL to JSON or CSV file. Also can be the URL to the server-side script generating the data.
fieldSeparator	String	optional Specific field delimiter for CSV data. By default, WebDataRocks can parse comma-separated values or semicolon-separated values. For all other cases, fieldSeparator should be specified.
data	String	optional Property to specify JSON data. WebDataRocks supports a certain kind of JSON data – array of objects, where each object is an unordered collection of KEY/VALUE pairs.

Example

Connect to a new CSV file in WebDataRocks reporting tool:

WebDataRocks reporting tool is embedded using new WebDataRocks() API call.

new WebDataRocks({
    container: String,
    toolbar: Boolean,
    report: Report Object | String,
    width: Number,
    height: Number,
    customizeCell: Function,
    global: Global Object
})

To embed WebDataRocks in the simplest configuration, return to the Quick start tutorial.

Parameters

Name	Type	Description
container	String	An id of the HTML element where pivot table is rendered.
toolbar	Boolean	optional Parameter to embed the Toolbar.
report	Report Object | String	optional Property to define which data is shown and other configurations.
width	Number	optional The width of the pivot table in pixels or percent (100% by default).
height	Number	optional The height of the pivot table in pixels or percent (500 by default).
customizeCell	Function	optional Function that renders each cell and can change its content (see how to use).
global	Global Object	optional Property to set default configurations for all reports.

You can also specify event handlers as initialization parameters. See the full list of events and try a live demo on CodePen.

Returns

The reference to the WebDataRocks object. API calls can be used via this object.

Example

Embed WebDataRocks reporting tool with the Toolbar:

Move up