Migration guide from 2.3 to 2.4

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

How to embed the component into your website

Starting from version 2.4, jQuery is no longer required. Before embedding the component, include flexmonster.js:

<script src="flexmonster/flexmonster.js"></script>

In previous versions the $.flexmonster() and embedPivotComponent() functions were used to embed the component. In version 2.4, they were deprecated. However, they are still supported for backward compatibility. Note, to use $.flexmonster() you need to include the jQuery library before flexmonster.js.

To embed Flexmonster in version 2.4, create the pivot table object like this:

var pivot = new Flexmonster({
    container:String,
    componentFolder:String, 
    global:Object, 
    width:Number, 
    height:Number, 
    report:Object|String, 
    toolbar:Boolean, 
    customizeCell:Function,
    licenseKey:String
})

Notice that the container property should specify a selector for the HTML element that you would like to use as a container for the component. This is the only required property in the configuration object. If you run new Flexmonster({container: "pivotContainer"}), where "pivotContainer" is the selector of the container HTML element, – an empty component without the Toolbar will be added with the default width and height. The configuration object can have the following properties:

container – String. The selector of the HTML element that will be a container for the component.
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.
toolbar – Boolean. The parameter to embed the Toolbar (the one that is shown in the pivot table demo) or not. Default value: false.
customizeCell – Function. Allows the customization of separate cells.
licenseKey – String. Your license key.

Event handlers can also be set as properties for the Flexmonster object.

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

API updates

Please have a look at the changes in our API:

The customizeCell hook was improved:
- The html property (string containing HTML) was replaced with a special cell builder cell. It is an object that contains the current representation of the cell on the grid and through which the cell representation can be customized. It has the following properties and methods:
  - attr – Object. All attributes and their values for the HTML element. Custom attributes can be added to the cell and, for example, used in CSS selectors to identify the cell. Read more info about CSS attribute selectors here.
  - classes – Array of strings. The array of classes assigned to the cell. The addClass() method should be used to add new classes.
  - style – Object. A CSS object of the element that will be put in the style attribute of the element for inline styling.
  - tag – String. The tag of the element (each cell has a tag: "div").
  - text – String. The text of the element. It may also contain HTML, for example, icons to expand, collapse, drill up and down, sorting, etc.
  - addClass(value: String) – Method. Use this method to add new classes to the element.
  - toHtml() – Method. Returns the HTML string that represents the cell. It gathers all the properties of the cell builder object into HTML. This is how the cell gets added to the grid.
- The data property, which contains information about the cell, now provides more information. Check out the full list of properties in the CellDataObject.
Note that customizeCell is NOT backward compatible. You need to update your customizeCell functions in accordance with these changes.
The ConditionalFormatObject was updated:
- The formula property property was simplified, now it should contain only the condition (e.g. '#value > 100').
- The trueStyle property was renamed to format. Also, inside the format object, the fontSize property should be set as "14px" instead of "14".
- The falseStyle property was removed.
For example, this definition of the condition object:
```
var condition = {
    id: 1,
    formula: 'if(#value > 400000, "trueStyle")',
    trueStyle: {
        fontSize : 10,
        backgroundColor: "#33BB33" 
   }
};
```
should be replaced with the following one:
```
var condition = {
    id: 1,
    formula: '#value > 400000',
    format: {     
        fontSize : "10px",
        backgroundColor: "#33BB33"
    }
};
```
There is also a new property formatCSS in the ConditionalFormatObject. This is a string which represents the ready to use CSS string of the format style object (formerly trueStyle).
The syntax from the previous version is functional in terms of backward compatibility.
The fullscreen API call was removed. Use Fullscreen from the Toolbar instead.
The getPages API call was renamed to getReportFilters.
The property pages from the ReportObject was renamed to reportFilters (with backward compatibility).
The properties configuratorMatchHeight and pagesFilterLayout were removed from the OptionsObject.
The default value of configuratorActive property inside the OptionsObject was changed to false.
Two new events were added:
- beforegriddraw – String. Triggered before grid rendering.
- aftergriddraw – String. Triggered after grid rendering.

Built-in themes

Starting from version 2.4, you can choose between several predefined CSS themes. All themes are placed inside the theme/ folder. To set a theme, add the CSS reference. For example, to show the lightblue theme, insert the following line of code:

<link rel="stylesheet" type="text/css" href="/theme/lightblue/flexmonster.min.css" />

Our 2.3-styled theme is available as well and can be set like this:

<link rel="stylesheet" type="text/css" href="/theme/old/flexmonster.min.css" />

Changes in CSS

In version 2.4 we decided to simplify the maintenance of CSS. The following changes were made:

flexmonster.css and flexmonster.toolbar.css were merged into one file flexmonster.css. Note that the changes with CSS files are NOT backward compatible, so you need to replace your old flexmonster.css file. Also note that selectors were changed, so you need to update any custom CSS files based on flexmonster.css.
We started using Less (a CSS pre-processor). With the download package you get CSS, minified CSS, and the Less source code files. It allows you to add your own styles on top of Less files and then compile them to CSS. This is extremely useful for creating your own themes. Just copy the Less file with one of our themes and redefine several variables with basic colors to create your custom theme.

The order of tabs in the Toolbar was changed. Additionally, the icons are now a vector. If you like the new icons, you can use them in your customizeToolbar function (a JS function for the beforetoolbarcreated event) like this:

// add new tab
tabs.unshift({
  id: "fm-tab-save",
  title: "Save",
  handler: "savetabHandler",
  icon: this.icons.save
});

tabs.unshift({
  id: "fm-tab-reload",
  title: "Reload",
  handler: "reloadCube",
  icon: this.icons.connect
});

You can use the icon property to add your own icons. This property has the type string and represents an HTML tag containing the custom icon for the new tab. Note, in this case any CSS with old icons should be removed.

Accelerators

Starting from version 2.4, our Accelerators work considerably faster. If you are using Flexmonster Accelerator for Microsoft Analysis Services or Flexmonster Accelerator for Pentaho Mondrian, keep in mind that they should be updated as well.

Documentation for older versions

If you need documentation from some older versions, it is always available at the following links:

Changes to Flexmonster Software License Agreement