Migration guide from 2.9 to 3.0

This guide helps you migrate from version 2.9 to 3.0, as well as summarizes the breaking changes and new features in the 3.0 major version.

Update Flexmonster to 3.0 and then check out the following sections:

Backward compatibility: what continues to work out of the box after the upgrade.
Updates: changes that may affect your existing setup.
New features: new capabilities introduced in version 3.0.
Implemented features: the list of features that can already be used.
Example of how to migrate from 2.9 to 3.0

To see which features are planned to be implemented, check out the Roadmap.

Update Flexmonster

To use version 3.0, update imports depending on how you used version 2.9: from CDN or ZIP package.

Backward compatibility

This section covers backward compatibility between the old and new versions. After updating Flexmonster, your existing implementation will continue to work.

Legacy initialization

For backward compatibility, the legacy initialization through new Flexmonster() is still supported: after updating flexmonster.js and flexmonster.css, the Flexmonster control will be created.

See how to update imports to use version 3.0.

Report conversion

Flexmonster will automatically convert reports created in version 2.9 into the new 3.0 configuration format. Note that only implemented configurations will be applied. See the Implemented features list.

API compatibility

The existing API remains functional, except for methods that have not been implemented yet. Learn more in the Implemented features.

Also, note that the names of some methods have been updated. See the Changes in method names section for details.

Styling and customization

While the JavaScript logic is backward compatible, styling and customizations are not. You need to manually update the following:

CSS customization
Toolbar customization

Updates

The following sections describe the updates introduced in Flexmonster 3.0, including changes to initialization, structure of configuration objects, API methods, and supported data types.

Initialization

Starting from version 3.0, Flexmonster initialization is done via the static fm3.Controls.Flexmonster() method.

The method has two parameters: container and params. The params parameter describes configurations and is defined by BaseInputParamsObject.

Report deprecation and API updates

In version 2.9 API, the report is the primary way to configure the component. It contains the data source, the slice, options, and other settings.

Now, configurations for the component are stored in the state and options objects of the BaseInputParamsObject.

See the following tables for details on where the report properties were relocated:

Data source configurations

Version 2.9	Version 3.0
`report.dataSource`	`state.dataset.dataSource`
`report.dataSource.type`	`state.dataset.dataSource.type`
`report.dataSource.data`	`state.dataset.dataSource.data`
`report.dataSource.url`	`state.dataset.dataSource.url`
`report.dataSource.filename`	`state.dataset.dataSource.url`
`report.dataSource.index`	`state.dataset.dataSource.name`
`report.dataSource.mapping`	`state.dataset.dataSource.mapping`
`report.dataSource.mapping.<unique_name>.caption`	`state.dataset.dataSource.mapping.<unique_name>.caption`
`report.dataSource.mapping.<unique_name>.type`	`state.dataset.dataSource.mapping.<unique_name>.type`
`report.dataSource.requestHeaders`	`state.dataset.dataSource.requestHeaders`
`report.dataSource.withCredential`	`state.dataset.dataSource.withCredential`
`report.dataSource.fieldSeparator`	`state.dataset.dataSource.parserConfig.delimiter`
`report.dataSource.thousandsSeparator`	Deprecated

Slice configurations

Version 2.9	Version 3.0
`report.slice`	`state.slice`
`report.slice.rows`	`state.slice.rows`, `state.slice.fields` (for the flat table)
`report.slice.columns`	`state.slice.columns`, `state.slice.fields` (for the flat table)
`report.slice.measures`	`state.slice.values`
`report.slice.rows.uniqueName`, `report.slice.columns.uniqueName`, `report.slice.measures.uniqueName`	`state.slice.rows.name`, `state.slice.columns.name`, `state.slice.values.name`, `state.slice.fields.name` (for the flat table)
`report.slice.measures.aggregation`	`state.slice.values.aggregation`, `state.slice.fields.aggregation` (flat table)
`report.slice.flatOrder`	Deprecated

Options configurations

Version 2.9	Version 3.0
`report.options`	`options`
`report.options.viewType`	Deprecated
`report.options.grid`	`options.flatTable`, `options.pivotTable`
`report.options.grid.type`	`options.viewType`
`report.options.grid.showHeaders`	`options.flatTable.showSheetHeaders`, `options.pivotTable.showSheetHeaders`
`report.options.grid.grandTotalsPosition`	`options.flatTable.grandTotalsPosition`
`report.options.showFieldListSearch`	`options.flatFieldList.showSearch`, `options.pivotFieldList.showSearch`

Changes in method names

Some API method names have changed in version 3.0. Your old code will still work, but if you want to fully switch to the new version, update the following method names:

Version 2.9	Version 3.0
`closeFieldsList()`	`closeFieldList()`
`getSelectedCell()`	`getSelectedCells()`
`openFieldsList()`	`openFieldList()`

See the Implemented features section to check which API calls are supported in 3.0.

Changes in data types

There have also been some changes to data types:

Previously, all numeric data was categorized under a single number type. In version 3.0, this type was split into two independent types:
- integer — Use this type for whole numbers without decimals.
- float — Use this type for numbers with fractional parts.
The date string type was renamed to date.

See all available data types and how to set them in version 3.0.

New features

The following sections show the new features introduced in Flexmonster version 3.0.

New architecture

Version 3.0 introduces a modular architecture that separates UI controls from data and state management. The single Flexmonster component from 2.9 is now split into independent modules that can be used separately: pivot table, flat table, pivot field list, flat field list, and toolbar.

To initialize the specific part of the interface, use the respective method or HTML tag:

Module	Method	Tag
Composite control	fm3.Controls.Flexmonster()	<fm-flexmonster>
Pivot table control	fm3.Controls.PivotTable()	<fm-pivot-table>
Flat table control	fm3.Controls.FlatTable()	<fm-flat-table>
Pivot field list control	fm3.Controls.PivotFieldList()	<fm-pivot-field-list>
Flat field list control	fm3.Controls.FlatFieldList()	<fm-flat-field-list>
Toolbar control	fm3.Controls.Toolbar()	<fm-toolbar>

Flexmonster Pivot server

In Flexmonster 3.0, the Flexmonster Pivot server has been reimagined as a core part of the product. While it remains optional, we strongly recommend using it to achieve the best performance and scalability.

To use the new version, you need to install the Flexmonster server.

Also, you can migrate your existing server configurations to the new version.

State and dataset

Version 3.0 uses the StateObject to manage report configurations, with the DatasetObject acting as the data source within it.

You can share one StateObject among multiple controls, or use a single DatasetObject across several states. Any update to the state or data is automatically synchronized across all connected components.

New data types

The boolean data type was added.

Parser configurations

New settings have been added to configure data parsing:

Support for loading files that do not include a header row.
For JSON: use this feature on the server or in the client-side parser.
For CSV: use this feature on the server or in the client-side parser.
Decimal separator for values in numeric data.
For JSON: configure it on the server or in the client-side parser.
For CSV: configure it on the server or in the client-side parser.
A record delimiter for CSV.

Managing totals in the flat table

In version 3.0, you can set the visibility of a total value for each field in the flat table independently by using the showTotal property in the slice.

Implemented features

See the list of already implemented features in version 3.0.

Data sources

Slice

Options

Set the visibility of spreadsheet headers for pivot and flat controls.
Set the position and visibility of the totals for the flat control.
Set search visibility for pivot and flat field list controls.

API calls

Programmatically open the field list for composite and toolbar controls.
Programmatically close the field list for composite and toolbar controls.
Get information about a specific cell for pivot, flat, and composite controls.
Get information about selected cells for pivot and composite controls.
Get currently specified options for the composite control.
Programmatically scroll to the specified row for pivot, flat, and composite controls.
Programmatically scroll to the specified column for pivot, flat, and composite controls.
Programmatically change the default view of the table for the component controls.
Set and clear sorting for the flat control.

Migration example

Example of migration from 2.9 to 3.0:

Live example