Menu
Free Trials
Table of contents

Migration guide

From Flexmonster Pivot Table & Charts 2.2 to 2.3

The new version of Pivot Table & Charts offers a couple of new methods. Some existing methods were improved and some were removed. This guide will help you to migrate from the previous version to the new one.

To migrate from the previous major version to 2.3 you should read the following:

  1. License keys
  2. How to embed pivot component into your website
  3. API updates
  4. New methods
  5. Removed methods
  6. New structure of report object
  7. Event list
  8. Toolbar localization
  9. Folder structure
  10.  Documentation for version 2.2

License keys

Version 2.3 requires new license keys. If you have active maintenance – contact our support team and you will get new Development and Production license keys for free. To renew annual maintenance or for further details please contact our sales team.

How to embed pivot component 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 the following way:

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

In the previous version embedPivotComponent() function was used to embed the component. In the version 2.3 it was removed, but it will be supported in this version in terms of backward compatibility. Instead of embedPivotComponent() you should use a jQuery call:

var pivot = $("#pivotContainer").flexmonster({
    componentFolder:String, 
    global:Object, 
    width:Number, 
    height:Number, 
    report:Object|String, 
    toolbar:Boolean, 
    licenseKey:String})

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

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

  • componentFolder – URL of the component’s folder which contains all necessary files. Also, it is used as a base URL for report files, localization files, styles and images. The default value for componentFolder is flexmonster/.
  • global – object that allows you to preset options for all reports. These options can be overwritten for concrete reports. The structure of the object is the same as for report.
  • width – width of the component on the page (pixels or percent). The default value for width is 100%.
  • height – height of the component on the page (pixels or percent). The default value for height is 500.
  • report – property to set a report. It can be inline report JSON, URL to report JSON or URL to report XML (in the previous version this property was called configUrl). The structure of report object was changed. Chapter New structure of report object explains how to use the new structure.
  • toolbar – parameter to embed the toolbar (the one that is shown in Pivot Table demo) or not. The default value is false – without toolbar (in the previous version this property was called withToolbar).
  • licenseKey – the license key.

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

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

API updates

Here is a list of methods that were changed:

  1. save
    In the previous version reports were saved in XML format. Now save returns report as JSON object. See New structure of report object for further details.
  2. getAllMeasures and getMeasures
    calculated property was removed from the measure object. To see, if some measure was calculated, check 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, you need to change its name everywhere 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 you should change
    options.showTotals = false;
    to
    options.grid.showTotals = false;
    You need to do the same for all the renamed options. All references to removed options should be deleted. You can find the renamed options among other changes of report object here.
  4. setHandler
    setHandler was replaced with on() and off(). Event list was extended. Check the full list here.
  5. getReport and setReport
    Object structure was changed. Chapter New structure of report object explains how to use the new structure.

New methods

These methods were added to the version 2.3:

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

More detailed information about each API call you can find in 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. JSON data source can be used instead. The first element of JSON is used to define data types, captions, group fields under one dimension, define hierarchies.
    var jsonData = [
      {
        "Color":{"type": "string"},
        "M":{"type": "month", 
            "dimensionUniqueName": "Days", // addDimension analog
            "dimensionCaption": "Days",
            "caption":"Month"},
        "W":{"type": "weekday", 
            "dimensionUniqueName": "Days", 
            "dimensionCaption": "Days", 
            "caption":"Week Day"},
        "Country":{"type":"level", // addHierarchy analog
            "hierarchy": "Geography", 
            "level":"Country"},
        "State":{"type":"level", 
            "hierarchy": "Geography", 
            "level":"State", 
            "parent": "Country"},
        "City":{"type":"level", 
            "hierarchy": "Geography", 
            "parent": "State"},
        "Price":0,
        "Quantity":{"type": "number"}
      },
      { // addDataRecord and addDataArray analog
        "Color":"green",
        "M":"September",
        "W":"Wed",
        "Country" : "Canada",
        "State" : "Ontario",
        "City" : "Toronto",
        "Price":174,
        "Quantity":22
      },
      {
        "Color":"red",
        "M":"March",
        "W":"Mon",
        "Time":"1000",
        "Country" : "USA",
        "State" : "California",
        "City" : "Los Angeles",
        "Price":1664,
        "Quantity":19
      }
    ];
    
  3. addStyleToMember
  4. addUrlToMember
  5. getColumnWidth
  6. getLabels
  7. getRowHeight
  8. getValue should be removed. It can be replaced with getCell().
    flexmonster.getCell(1,1);
    
  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 two ways:
    • using global.localization inside 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"
      	}
      };
      flexmonster.setReport(report);
      
  18.  setRowHeight
  19.  setSelectedCell
  20.  setStyle
  21.  zoomTo

New structure of report object

In version 2.3 report object was structured. Properties were logically grouped into sub-objects. For example, all related to data sources properties are inside dataSource sub-object now.

JSON report objects of the previous version and XML reports are fully supported in terms of backward compatibility. It means you can open or set reports from the previous major version. Please note, that all reports will be saved in new JSON structure. Thus, the component can be used to migrate to the new version of reports. Also, we created a small utility for converting XML reports to JSON. That is an easy and convenient way of migrating to the new format.

Here is an example of new report object:

{
    "dataSource": {
        "dataSourceType": "microsoft analysis services",
        "proxyUrl": "http://olap.flexmonster.com/olap/msmdpump.dll",
        "dataSourceInfo": "WIN-IA9HPVD1RU5",
        "catalog": "Adventure Works DW Standard Edition",
        "cube": "Adventure Works",
        "binary": false
    },
    "slice": {
        "rows": [
            {
                "uniqueName": "[Geography].[Geography]",
                "filter": {
                    "members": [
                        "[Geography].[Geography].[City].&[Malabar]&[NSW]",
                        "[Geography].[Geography].[City].&[Lavender Bay]&[NSW]",
                        "[Geography].[Geography].[City].&[Matraville]&[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": [
                        "[Geography].[Geography].[Country].&[Australia]"
                    ]
                },
                {
                    "tuple": [
                        "[Geography].[Geography].[City].&[Lane Cove]&[NSW]"
                    ]
                }
            ]
        },
        "drills": {
            "drillAll": false,
            "rows": [
                {
                    "tuple": [
                        "[Geography].[Geography].[Country].&[Australia]"
                    ]
                },
                {
                    "tuple": [
                        "[Geography].[Geography].[State-Province].&[NSW]&[AU]"
                    ]
                },
                {
                    "tuple": [
                        "[Geography].[Geography].[City].&[Darlinghurst]&[NSW]"
                    ]
                }
            ]
        }
    },
    "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 report object 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 options.memberProperties
pages slice.pages
pages.customSorting slice.pages.sortOrder
pages.sortName slice.pages.sort
password dataSource.password
recordsetDelimiter dataSource.recordsetDelimiter
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 slice.useOlapFormatting
username dataSource.username
viewType options.viewType
zoom removed
Also, these new options were added:
options.grid.pagesFilterLayout
options.selectEmptyCells

Please note:

    • showFiltersExcel was removed from options. Instead, you can use showFilter parameter of export options inside exportTo() API call, as follows:
      flexmonster.exportTo("excel", {showFilters: true})
      Or
      flexmonster.exportTo("excel", {showFilters: false})
      In exportTo() showFilters is false by default.
    • drillAll was removed from options and moved to slice inside report object
    • expandAll was removed from options and moved to slice inside report object
    • ignoreQuotedLineBreaks was removed from options and moved to dataSource inside report object
    • useOlapFormatting was removed from options and moved to slice inside report object
//To format values from data source according 
//to the format defined in the cube
var report = flexmonster.getReport();
report.slice.useOlapFormatting = true;
flexmonster.setReport(report);

    Event list

    List of renamed events:

    • jsPivotCreationCompleteHandler was renamed to reportcomplete – String, triggered when OLAP structure or data from the report, localization file and all data source files were loaded successfully and the grid/chart was 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 Fields List is opened.
    • jsFieldsListCloseHandler was renamed to fieldslistclose – String, triggered when the built-in Fields 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 reportfileloaded – String, triggered when the component loaded 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 the 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 Open file dialog was opened and customer clicks Cancel button. It happens when:
      1. customer uses menu Connect -> to local CSV/JSON
      2. API method updateData() is called with parameter browseForFile = true
    • dataloaded – String, triggered when the component loaded data. Please use olapstructureloaded for OLAP data sources.
    • loadingdata – String, triggered when data starts loading from local or remote CSV, JSON. Please use loadingolapstructure for OLAP data sources.
    • loadinglocalization – String, triggered when localization file starts loading.
    • loadingolapstructure – String, triggered when the structure of OLAP cube starts loading.
    • loadingreportfile – String, triggered when a report file started loading.
    • localizationerror – String, triggered when some error appeared while loading localization file.
    • localizationloaded – String, triggered when localization file was loaded.
    • olapstructureerror – String, triggered when some error appeared while loading OLAP structure.
    • olapstructureloaded – String, triggered when OLAP structure was loaded.
    • openingreportfile – String, triggered when:
      1. customer uses menu Open -> Local report
      2. API method open() is called
    • querycomplete – String, triggered after the data query was complete.
    • queryerror – String, triggered if some error occurred while running the query.
    • ready – String, triggered when the component’s initial configuration completed and the component is ready to receive API calls.
    • reportfilecancelled – String, triggered when the customer uses menu Open -> Local report and clicks Cancel button.
    • reportfileerror – String, triggered when some error occurred during the loading of the report file.
    • runningquery – String, triggered before 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 it is necessary to load data from the external data storage in case of OLAP data source. Data query is started when:
      1. Slice was changed;
      2. Any filter was used;
      3. Drill up/drill down was used;
      4. Columns or rows were expanded;
      5. Drill through was used.

    Toolbar localization

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

     "toolbar": {
        "connect": 
    …
    }
    

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

    Folder structure

    FOLDERS CONTENTS
    assets/ Contains the theme images
    lib/ Includes additional JavaScript libraries
    toolbar/ Contains toolbar files: images, JS, and CSS
    flexmonster.css The theme CSS
    flexmonster.js The main Pivot Table JavaScript file

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

    Documentation for version 2.2

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