Need a special offer?Find out if your project fits.
  1. API reference
  • Introduction
  • Connecting to Data Source
  • Browser compatibility
  • Documentation for older versions
  • All documentation

    Migration guide from 2.2 to 2.3

    The new version of Flexmonster offers several new methods. Additionally, some existing methods were improved and some were removed. This guide will help you migrate from the previous version to the new one.

    License keys

    Version 2.3 requires new license keys. If you have an active maintenance – contact our customer service team and you will receive new development and production license keys for free. To renew annual maintenance or for further details, please contact our Sales team.

    How to embed Flexmonster into your website

    Version 2.3 is based on jQuery. In order for the component scripts to work as expected, make sure you include a reference to the jQuery library in the document before the scripts. It should look like this:

    <script src="flexmonster/lib/jquery.min.js"></script>
    <script src="flexmonster/flexmonster.js"></script>

    In the previous version, the embedPivotComponent() function was used to embed the component. Now, in version 2.3 it has been deprecated, but will be supported in this version for backward compatibility. Instead of  embedPivotComponent(), use a jQuery call like this:

    var pivot = $("#pivotContainer").flexmonster({

    As a parameter, the jQuery call takes a selector of the HTML element that you would like to have as a container for the component.

    All the properties are optional in the configuration object. If you run $("#pivotContainer").flexmonster() – an empty component without the Toolbar will be added with the default width and height. The configuration object passed to the jQuery call can have the following properties:

    • componentFolder – String. The URL of the component’s folder that contains all the necessary files. It is also used as the base URL for report files, localization files, styles, and images. Default value: "flexmonster/".
    • globalGlobalObject. Allows you to preset options for all reports. These options can be overridden for specific reports.
    • width – Number | String. The width of the component on the page (either in pixels or as a percentage). Default value: "100%".
    • height – Number | String. The height of the component on the page (either in pixels or as a percentage). Default value: 500.
    • reportReportObject | String. The property to set a report. It can be an inline report JSON or a URL to the report JSON. XML reports are also supported for backward compatibility. In the previous version this property was called configUrl. The structure of the ReportObject has also changed. The chapter New structure of the ReportObject explains how to use the new structure.
    • toolbar – Boolean. The parameter to embed the Toolbar (the one that is shown in the pivot table demo) or not. In the previous version this property was called withToolbarDefault value: false
    • licenseKey – String. Your license key.

    Event handlers can also be set as properties for the jQuery call. Find the list here.

    The jQuery initialization statement returns a reference to the created component instance. The API methods are available through this reference.

    After initialization, you can obtain an instance reference to the component by using a selector like this: var pivot = $("#pivot").data("flexmonster");

    API updates

    Here is a list of methods that were changed:

    1. save
      In the previous version, reports were saved in an XML format. Now save returns the report as a JSON object. See the New structure of the ReportObject for further details.
    2. getAllMeasures and getMeasures
      The calculated property was removed from the measure object. To see if a measure was calculated, check the formula property of the measure object. It defines whether the measure is calculated or not.
    3. getOptions and setOptions
      Some of the component’s options were changed. If some option was renamed, its name must be changed anywhere it was used. For example:
      var options = flexmonster.getOptions(); options.showTotals = false; flexmonster.setOptions(options); flexmonster.refresh(); 
      In version 2.3 showTotals was renamed to grid.showTotals, so change
      options.showTotals = false;
      options.grid.showTotals = false;
      The same needs to be done for all the renamed options. All references to removed options should be deleted. See the renamed options among the other changes to the ReportObject here.
    4. setHandler
      setHandler was replaced with on() and off(). The event list was extended. The full list can be found here.
    5. getReport and setReport
      The object structure was changed. The chapter New structure of the ReportObject explains how to use the new structure.

    New methods

    These methods were added to version 2.3:

    1. dispose() – prepares the pivot table instance to be deleted by the browser’s garbage collection.
    2. getData(options: Object, callbackHandler: Function, updateHandler: Function) – enables integration with 3rd party charting libraries (FusionCharts, Highcharts, Google Charts, etc). Returns the data from the pivot table component. The options object can have the slice property. If slice in options is not defined, the API call will return the data displayed in the pivot table.
    3. off(eventName: String, functionName: String) – removes the event listener. If the functionName property is not defined, all event listeners will be removed.
    4. updateData(params: Object | Array) – the addJSON and connectTo API calls were replaced by this API call. It is used to update the data for the report without clearing the report.

    More detailed information about each API call is available in the API Reference.

    Removed methods

    1. addMeasure should be removed. It can be replaced with addCalculatedMeasure(measure).
    2. addDataArray, addDataRecord, addDimension, and addHierarchy should be removed. A JSON data source should be used instead. The first element of the JSON object is used to define data types, captions, group fields under one dimension, and hierarchies.
      var jsonData = [
      "Color":{ "type": "string" },
      "type": "month",
      "dimensionUniqueName": "Days", // addDimension analog
      "dimensionCaption": "Days",
      "type": "weekday",
      "dimensionUniqueName": "Days",
      "dimensionCaption": "Days",
      "caption":"Week Day"
      // addHierarchy analog
      "hierarchy": "Geography",
      "hierarchy": "Geography",
      "parent": "Country"
      "hierarchy": "Geography",
      "parent": "State"
      "Quantity":{ "type": "number" }
      // addDataRecord and addDataArray analog
      "Country" : "Canada",
      "State" : "Ontario",
      "City" : "Toronto",
      "Country" : "USA",
      "State" : "California",
      "City" : "Los Angeles",
    3. addStyleToMember
    4. addUrlToMember
    5. getColumnWidth
    6. getLabels
    7. getRowHeight
    8. getValue should be removed. It can be replaced with getCell().
    9. gridColumnCount
    10.  gridRowCount
    11.  percentZoom
    12.  removeAllMeasures should be removed. It can be replaced with removeAllCalculatedMeasures().
    13.  removeMeasure should be removed. It can be replaced with removeCalculatedMeasure(name).
    14.  setChartTitle should be removed. It can be replaced with
      flexmonster.setOptions({chart:{title: "Chart One"}})
    15.  setColumnWidth
    16.  setGridTitle should be removed. It can be replaced with
      flexmonster.setOptions({ grid:{title: "Table One"}})
    17. setLabels should be removed. It can be replaced in one of two ways:
      • Using global.localization inside the global object:
        var global = {
        localization: "loc-en.json",
        dataSource: {
        dataSourceType: "csv", filename: "data.csv"
        var pivot = $("#pivotContainer").flexmonster({
        global: global,
        licenseKey: "XXX"
      • While setting a report with setReport():
        var report = {
        localization: "loc-en.json",
        dataSource: {
        dataSourceType: "csv",
        filename: "data.csv"
    18.  setRowHeight
    19.  setSelectedCell
    20.  setStyle
    21.  zoomTo

    The new structure of the ReportObject

    In version 2.3 the ReportObject was restructured. Properties were logically grouped into sub-objects. For example, data sources related properties are located inside the dataSource sub-object now.

    JSON ReportObjects from the previous version and XML reports are fully supported in terms of backward compatibility. This means that you can open or set reports from the previous major version. Note that all reports will now be saved in the new JSON structure, so the component can be used to migrate reports to the new version. We also created a small utility for converting XML reports to JSON. This is an easy and convenient way of migrating to the new format.

    Here is an example of the new ReportObject:

        "dataSource": {
            "dataSourceType": "microsoft analysis services",
            "proxyUrl": "",
            "dataSourceInfo": "WIN-IA9HPVD1RU5",
            "catalog": "Adventure Works DW Standard Edition",
            "cube": "Adventure Works",
            "binary": false
        "slice": {
            "rows": [
                    "uniqueName": "[Geography].[Geography]",
                    "filter": {
                        "members": [
                            "[Geography].[Geography].[City].&[Lavender Bay]&[NSW]",
                            "[Geography].[Geography].[City].&[Milsons Point]&[NSW]"
                        "negation": true
                    "sort": "asc"
                    "uniqueName": "[Sales Channel].[Sales Channel]",
                    "sort": "asc"
            "columns": [
                    "uniqueName": "[Measures]"
            "measures": [
                    "uniqueName": "[Measures].[Reseller Order Count]",
                    "aggregation": "none",
                    "active": true,
                    "format": "29mvnel3"
            "expands": {
                "expandAll": false,
                "rows": [
                        "tuple": [
                        "tuple": [
                            "[Geography].[Geography].[City].&[Lane Cove]&[NSW]"
            "drills": {
                "drillAll": false,
                "rows": [
                        "tuple": [
                        "tuple": [
                        "tuple": [
        "options": {
            "viewType": "grid",
            "grid": {
                "type": "compact",
                "title": "",
                "showFilter": true,
                "showHeaders": true,
                "fitGridlines": false,
                "showTotals": true,
                "showGrandTotals": "on",
                "showExtraTotalLabels": false,
                "showHierarchies": true,
                "showHierarchyCaptions": true,
                "showReportFiltersArea": true,
                "pagesFilterLayout": "horizontal"
            "chart": {
                "type": "bar",
                "title": "",
                "showFilter": true,
                "multipleMeasures": false,
                "oneLevel": false,
                "autoRange": false,
                "reversedAxes": false,
                "showLegendButton": false,
                "showAllLabels": false,
                "showMeasures": true,
                "showOneMeasureSelection": true,
                "showWarning": true,
                "activeMeasure": ""
            "configuratorActive": true,
            "configuratorButton": true,
            "configuratorMatchHeight": false,
            "showAggregations": true,
            "showCalculatedValuesButton": true,
            "editing": false,
            "drillThrough": true,
            "showDrillThroughConfigurator": true,
            "sorting": "on",
            "datePattern": "dd/MM/yyyy",
            "dateTimePattern": "dd/MM/yyyy HH:mm:ss",
            "saveAllFormats": false,
            "showDefaultSlice": true,
            "showEmptyData": false,
            "defaultHierarchySortName": "asc",
            "selectEmptyCells": true,
            "showOutdatedDataAlert": false
        "conditions": [
                "formula": "if(#value < 40, 'trueStyle')",
                "trueStyle": {
                    "backgroundColor": "#FFCCFF",
                    "color": "#000033",
                    "fontFamily": "Arial",
                    "fontSize": 12
                "falseStyle": {}
        "formats": [
                "name": "29mvnel3",
                "thousandsSeparator": " ",
                "decimalSeparator": ".",
                "decimalPlaces": -1,
                "maxDecimalPlaces": -1,
                "maxSymbols": 20,
                "currencySymbol": "$",
                "currencySymbolAlign": "left",
                "nullValue": "",
                "infinityValue": "Infinity",
                "divideByZeroValue": "Infinity",
                "textAlign": "right",
                "isPercent": false
        "tableSizes": {
            "columns": [
                    "tuple": [],
                    "measure": "[Measures].[Reseller Order Count]",
                    "width": 182
        "localization": "loc-ua.json"

    Here is a table that illustrates how the properties of the ReportObject were changed between versions 2.2 and 2.3:

    Version 2.2 Version 2.3
    browseForFile dataSource.browseForFile
    chartActiveMeasure options.chart.activeMeasure
    chartActiveMeasures options.chart.activeMeasures
    chartActiveTupleIndex options.chart.activeTupleIndex
    chartAutoRange options.chart.autoRange
    chartMultipleMeasures options.chart.multipleMeasures
    chartOneLevel options.chart.oneLevel
    chartOneLevelTuple options.chart.oneLevelTuple
    chartPosition options.chart.position
    chartReversedAxes options.chart.reversedAxes
    chartTitle options.chart.title
    chartType options.chart.type
    classicView grid.type
    columnHeaderSizes tableSizes.columns
    columnSizes tableSizes.columns
    columnSorting slice.sorting.column
    columns slice.columns
    columns.customSorting slice.columns.sortOrder
    columns.sortName slice.columns.sort
    conditions conditions
    configuratorActive options.configuratorActive
    configuratorButton options.configuratorButton
    configuratorMatchHeight options.configuratorMatchHeight
    customData dataSource.customData
    customFields customFields
    customSort slice.sortOrder
    dataSourceType dataSource.dataSourceType
    datePattern options.datePattern
    dateTimePattern options.dateTimePattern
    defaultHierarchySortName options.defaultHierarchySortName
    drillAll slice.drills.drillAll
    drillThrough options.drillThrough
    drilledColumns slice.drills.columns
    drilledRows slice.drills.rows
    editing options.editing
    effectiveUserName dataSource.effectiveUserName
    expandAll slice.expands.expandAll
    expandedColumns slice.expands.columns
    expandedRows slice.expands.rows
    fieldSeparator dataSource.fieldSeparator
    filename dataSource.filename
    fitGridlines options.grid.fitGridLines
    flatOrder slice.flatOrder
    flatView options.grid.type
    formats formats
    gridTitle options.grid.title
    ignoreQuotedLineBreaks dataSource.ignoreQuotedLineBreaks
    labels labels
    localSettingsUrl localization
    localeIdentifier dataSource.localeIdentifier
    maxChunkSize removed
    measures slice.measures
    memberProperties slice.memberProperties
    pages slice.pages
    pages.customSorting slice.pages.sortOrder
    pages.sortName slice.pages.sort
    password dataSource.password
    roles dataSource.roles
    rowFilterSizes tableSizes.rows
    rowHeaderSizes tableSizes.rows
    rowSizes tableSizes.rows
    rowSorting slice.sorting.row
    rows slice.rows
    rows.customSorting slice.rows.sortOrder
    rows.sortName slice.rows.sort
    saveAllFormats options.saveAllFormats
    showAggregations options.showAggregations
    showAllChartLabels options.chart.showAllLabels
    showCalculatedValuesButton options.showCalculatedValuesButton
    showChartLegendButton options.chart.showLegendButton
    showChartMeasures options.chart.showMeasures
    showChartOneMeasureSelection options.chart.showOneMeasureSelection
    showChartsWarning options.chart.showWarning
    showDefaultSlice options.showDefaultSlice
    showDrillThroughConfigurator options.showDrillThroughConfigurator
    showEmptyData options.showEmptyData
    showFilter options.grid.showFilter
    showFilterInCharts options.chart.showFilter
    showFiltersExcel removed
    showGrandTotals options.grid.showGrandTotals
    showHeaders options.grid.showHeaders
    showHierarchies options.grid.showHierarchies
    showHierarchyCaptions options.grid.showHierarchyCaptions
    showMemberProperties options.showMemberProperties
    showOutdatedDataAlert options.showOutdatedDataAlert
    showReportFiltersArea options.grid.showReportFiltersArea
    showTotals options.grid.showTotals
    sorting options.sorting
    useOlapFormatting options.useOlapFormatting
    username dataSource.username
    viewType options.viewType
    zoom removed
    Also, these new options were added:


    • showFiltersExcel was removed from options. Instead, use the showFilter parameter from export options inside the exportTo() API call, as follows:
      flexmonster.exportTo("excel", {showFilters: true})


      flexmonster.exportTo("excel", {showFilters: false})

      In exportTo() showFilters is false by default.

    • drillAll was removed from options and moved to slice inside the ReportObject.
    • expandAll was removed from options and moved to slice inside the ReportObject.
    • ignoreQuotedLineBreaks was removed from options and moved to dataSource inside the ReportObject.
      //To stop ignoring line breaks in quotes
      var report = flexmonster.getReport();
      report.dataSource.ignoreQuotedLineBreaks = false;

    Event list

    List of renamed events:

    • jsPivotCreationCompleteHandler was renamed to reportcomplete – String. Triggered when the OLAP structure or data from the report, localization file, and all data source files are loaded successfully and the grid/chart is rendered. This event means the operations can be performed with the component.
    • jsCellClickHandler was renamed to cellclick – String. Triggered when a cell is clicked on the grid.
    • jsFieldsListOpenHandler was renamed to fieldslistopen – String. Triggered when the built-in Field List is opened.
    • jsFieldsListCloseHandler was renamed to fieldslistclose – String. Triggered when the built-in Field List is closed.
    • jsFilterOpenHandler was renamed to filteropen – String. Triggered when a filter icon is pressed.
    • jsFullScreenHandler was removed.
    • jsReportChangeHandler was renamed to reportchange – String. Triggered when a report is changed in the component.
    • jsReportLoadedHandler was renamed to reportcomplete – String. Triggered when the component finishes loading a report file.
    • jsPivotUpdateHandler was renamed to update – String. Triggered when the component loaded data, updated data slice, filter or sort. In other words, when a change occurred in the component. 

    List of new events:

    • celldoubleclick – String. Triggered when a cell is clicked on the grid twice.
    • dataerror – String. Triggered when some error occurred during the loading of data. Please use olapstructureerror for OLAP data sources.
    • datafilecancelled – String. Triggered when the Open file dialog was opened and a user clicks the Cancel button. It happens when:
      1. A user clicks menu Connect -> To local CSV/JSON.
      2. The API method updateData() is called with the parameter browseForFile: true.
    • dataloaded – String. Triggered when the component finishes loading data. Please use olapstructureloaded for OLAP data sources.
    • loadingdata – String. Triggered when data starts loading from local or remote CSV or JSON. Please use loadingolapstructure for OLAP data sources.
    • loadinglocalization – String. Triggered when the localization file starts loading.
    • loadingolapstructure – String. Triggered when the structure of an OLAP cube starts loading.
    • loadingreportfile – String. Triggered when a report file starts loading.
    • localizationerror – String. Triggered when an error appears while loading a localization file.
    • localizationloaded – String. Triggered when a localization file finishes loading.
    • olapstructureerror – String. Triggered when an error appears while loading an OLAP structure.
    • olapstructureloaded – String. Triggered when an OLAP structure finishes loading.
    • openingreportfile – String. Triggered when:
      1. A user clicks Open -> Local report.
      2. The API method open() is called.
    • querycomplete – String. Triggered after a data query is complete.
    • queryerror – String. Triggered if an error occurs while running the query.
    • ready – String. Triggered when the component’s initial configuration is complete and the component is ready to receive API calls.
    • reportfilecancelled – String. Triggered when a user clicks the menu Open -> Local report and clicks the Cancel button.
    • reportfileerror – String. Triggered when an error occurs during the loading of the report file.
    • runningquery – String. Triggered before a data query is started. It is used for both cases when data is already loaded and stored in the component’s local storage or when data is loaded from external data storage in the case of an OLAP data source. A data query is started when:
      1. A slice is changed.
      2. Any filter is used.
      3. A drill-up or a drill-down query is performed.
      4. Columns or rows are expanded.
      5. A drill through is used.

    Localization of the Toolbar

    In the previous version, the Toolbar could be localized by passing translations to the toolbarLocalization parameter in embedPivotComponent(). Now localization of the Toolbar is set inside the localization file. To set localization for only the Toolbar, open your localization file, find the following code:

     "toolbar": {

    Replace the respective terms with your language. Save the file and reload the component. For more details on how to set localization for the pivot table, please read Localizing the component.

    Folder structure

    Folders Contents
    assets/ Contains the theme images
    lib/ Includes additional JavaScript libraries
    toolbar/ Contains the Toolbar files: images, JS, and CSS
    flexmonster.css The theme CSS
    flexmonster.js The main Flexmonster JavaScript file

    Note that the folder structure was changed. Now html5-assets/ is replaced with assets/, lib/ and flexmonster.css.

    Documentation for version 2.2

    If you are looking for documentation from version 2.2, it is available here: Documentation 2.2 and API Reference 2.2.