Migration guide from 2.2 to 2.3

This migration guide describes significant new features and breaking changes in version 2.3. To see the full list of new features and fixes in version 2.3, visit the Release notes page.

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({
    componentFolder:String, 
    global:Object, 
    width:Number, 
    height:Number, 
    report:Object|String, 
    toolbar:Boolean, 
    licenseKey:String})

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/".
global – GlobalObject. 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.
report – ReportObject | 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 withToolbar. Default 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:

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.
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.
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 = pivot.getOptions();
options.showTotals = false;
pivot.setOptions(options);
pivot.refresh(); 
```
In version 2.3 showTotals was renamed to grid.showTotals, so change
```
options.showTotals = false;
```
to
```
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.
setHandler
setHandler was replaced with on() and off(). The event list was extended. The full list can be found here.
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:

dispose() – prepares the pivot table instance to be deleted by the browser’s garbage collection.
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.
off(eventName: String, functionName: String) – removes the event listener. If the functionName property is not defined, all event listeners will be removed.
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

addMeasure should be removed. It can be replaced with addCalculatedMeasure(measure).

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" },
        "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
    }
];

addStyleToMember
addUrlToMember
getColumnWidth
getLabels
getRowHeight
getValue should be removed. It can be replaced with getCell().
```
pivot.getCell(1,1); 
```
gridColumnCount
gridRowCount
percentZoom
removeAllMeasures should be removed. It can be replaced with removeAllCalculatedMeasures().
removeMeasure should be removed. It can be replaced with removeCalculatedMeasure(name).
setChartTitle should be removed. It can be replaced with
```
pivot.setOptions({chart:{title: "Chart One"}})
```
setColumnWidth
setGridTitle should be removed. It can be replaced with
```
pivot.setOptions({ grid:{title: "Table One"}})
```

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"
    }
};
pivot.setReport(report);

setRowHeight
setSelectedCell
setStyle
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": "https://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 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:
	`options.grid.pagesFilterLayout`
	`options.selectEmptyCells`

Note:

showFiltersExcel was removed from options. Instead, use the showFilter parameter from export options inside the exportTo() API call, as follows:
```
pivot.exportTo("excel", {showFilters: true})
```
Or
```
pivot.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 = pivot.getReport();
report.dataSource.ignoreQuotedLineBreaks = false;
pivot.setReport(report);

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": {
    "connect": 
…
}

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.

Changes to Flexmonster Software License Agreement