Integration with React Native

This tutorial will help you integrate Flexmonster with the React Native framework. It is based on the React Native: Getting Started guide.

Prerequisites

Run the sample project from GitHub

Step 1. To get our sample project, download it as ZIP or clone it with the following commands:

git clone https://github.com/flexmonster/pivot-react-native
cd pivot-react-native

Step 2. Install the npm dependencies described in package.json:

npm install

If the above command failed, run it with the --force flag:

npm install --force

Step 3. If you are using React 17 or earlier, change the last two lines of code in the component/PivotTable.js file:

Uncomment the following line:

//export { PivotTable as PivotTableComponent };

Comment the line below:

export var PivotTableComponent = React.forwardRef((props, ref) => <PivotTable />);

Step 4. Run your application from the console:

expo start

The application can be shut down manually with Ctrl + C.

Available examples

The sample project contains several examples of using Flexmonster methods and events in React Native.

When initialized, the component is subscribed to the cellclick event. As a cell is clicked for the first time, the cellclick's handler is removed, and the component subscribes to the update event.

The application also has two buttons: Show chart and Show grid. The Show chart button switches to the charts view using the showCharts() method. Show grid uses the showGrid() method to switch to the grid view.

Learn more about using methods and events in this section.

Integrate Flexmonster into a React Native application

To integrate Flexmonster into a React Native app, follow these steps:

Step 1. If you don’t already have a React Native app, create one by running these commands in the console:

expo init my-app --template blank
cd my-app

Step 2. If you created a new app, install the npm dependencies described in package.json:

npm install

Step 3. Install the Flexmonster React Native module with the following command:

npm install react-native-flexmonster --save-exact

Note We recommend installing Flexmonster with the --save-exact flag to avoid unexpected component updates.

Step 4. Import FlexmonsterReactNative into App.js:

import * as FlexmonsterReactNative from 'react-native-flexmonster';

Step 5. Insert Flexmonster Pivot into App.js:

export default function App() {
  return (
    <View style={{ flex: 1 }}>
      <FlexmonsterReactNative.Pivot
       report="https://cdn.flexmonster.com/reports/report.json" 
      />
    </View>
  );
}

Step 6. Run your application from the console:

expo start

The application can be shut down manually with Ctrl + C.

Using methods and events in React Native

Most of Flexmonster’s methods and events work in React Native just like in plain JavaScript. However, some of them are not available, which includes:

customizeCell
customizeContextMenu
beforetoolbarcreated
getData — as a result, integrating with 3rd party charting libraries is not supported in React Native. Nevertheless, you can use our built-in Flexmonster Pivot Charts to visualize your data.

See which methods and events can be used in React Native out of the box.

This section explains how to use events and methods in React Native.

Create a React reference

To use Flexmonster methods and events in React Native, we will need a React ref to the Flexmonster instance. Create a ref and attach it to the FlexmonsterReactNative.Pivot element:

<FlexmonsterReactNative.Pivot
 ref={flexmonster => this.flexmonster = flexmonster}
 report="https://cdn.flexmonster.com/reports/report.json"
/>

Now we can reference the Flexmonster instance throughout the React component.

See how the ref is attached to the component in the sample project.

Use methods

A method’s usage depends on its role. There are two types of methods:

Methods that perform an action
Methods that return a value

Methods that perform an action

To call methods that perform some action, just use the ref to Flexmonster instance:

function showMyChart() {
  this.flexmonster.showCharts("pie");
}

return (
  <View style={{ flex: 1 }}> 
    <FlexmonsterReactNative.Pivot
     ref={flexmonster => this.flexmonster = flexmonster}
     report="https://cdn.flexmonster.com/reports/report.json"
    />
  </View>
);

See how methods that perform an action are used in our sample project.

Methods that return a value

Methods that return a value are called similarly to methods that perform an action. To use their returned value, catch it with the then() method:

function reportComplete() {
  this.flexmonster.getReport().then(function(report) {
    console.log(report);
  });
}

return (
  <View style={{ flex: 1 }}> 
    <FlexmonsterReactNative.Pivot
     ref={flexmonster => this.flexmonster = flexmonster}
     report="https://cdn.flexmonster.com/reports/report.json"
    />
  </View>
);

Use events

You can subscribe to events in two ways:

Via props
Via the on() method

Subscribing to events via props

To subscribe to events via props, simply define the needed event as a FlexmonsterReactNative.Pivot prop and assign an event handler to it:

return (
  <View style={{ flex: 1 }}> 
    <FlexmonsterReactNative.Pivot   
     cellclick={this.onclickHandler} 
     report="https://cdn.flexmonster.com/reports/report.json"
    />
  </View>
);

onclickHandler = () => {
  alert("The cell was clicked!");
}

The sample React Native project demonstrates how to subscribe to an event via props.

Subscribing to events via the on() method

You can also subscribe to an event using the on() API call. Now we will need the previously created this.flexmonster ref:

return (
  <View style={{ flex: 1 }}> 
    <FlexmonsterReactNative.Pivot
     ref={flexmonster => this.flexmonster = flexmonster}
     report="https://cdn.flexmonster.com/reports/report.json"
    />
  </View>
); 

myFunction = () => {
  this.flexmonster.on("aftergriddraw", () => {
    alert("aftergriddraw");
  });
}

To unsubscribe from an event, use the off() method:

return (
  <View style={{ flex: 1 }}> 
    <FlexmonsterReactNative.Pivot
     ref={flexmonster => this.flexmonster = flexmonster}
     report="https://cdn.flexmonster.com/reports/report.json"
    />
  </View>
);  

myFunction = () => {
  this.flexmonster.on("aftergriddraw", () => {
    alert("aftergriddraw");
    this.flexmonster.off("aftergriddraw"); 
  });
}

Have a look at the sample React Native project and see how on() and off() methods are used.

Customizing Flexmonster in React Native

This section describes the specifics of customizing Flexmonster in React Native.

The Flexmonster React Native module embeds the component into a React Native application using the WebView library, which creates a separate browser window with Flexmonster. Since WebView is an independent part of the application, the component cannot be accessed directly from the app and vice versa.

This approach comes with some limitations. Methods that are defined in the application and require direct access to Flexmonster cannot be used. This includes, for example, customizeCell, customizeContextMenu, and beforetoolbarcreated.

To use these features, you need to modify the Flexmonster React Native module. Follow the steps below to see how the React Native module can be customized.

Step 1. Download the sample project from GitHub

Follow steps 1-4 from the guide on how to run the sample project from GitHub.

Step 2. Download the Flexmonster React Native module from GitHub

The sample project includes the Flexmonster React Native module as an npm dependency, but we will connect it manually to add custom functionality.

Download the .zip archive with the module from GitHub or run the following command in the console:

git clone https://github.com/flexmonster/react-native-flexmonster

Step 3. Add the module to your project

Copy the src/index.js file from the react-native-flexmonster/ folder to the project folder (e.g., pivot-react-native/). Rename the file if needed (e.g., to react-native-flexmonster.js).

Step 4. Use the module from GitHub

Replace the React Native module from npm with the module from GitHub by updating the module import statement in the App.js file:

import * as FlexmonsterReactNative from './react-native-flexmonster';

Step 5. Customize the module

Make the necessary updates to the react-native-flexmonster.js file. Note that all the updates should be made in the HTML template.

The steps below describe how to customize cells on the grid:

Step 5.1. Add a customizeCellFunction to the module's htmlTemplate variable:

<script>
  new Flexmonster({
    // initialization parameters
  });
  function customizeCellFunction (cell, data) {
    if (data.type == "value") {
      if (data.rowIndex % 2 == 0) {
        cell.addClass("alter1");
      } else {
        cell.addClass("alter2");
      }
    }
  }
  ${this.registerEvents()}
</script>

Step 5.2. Add CSS classes that will be applied to the rows. This can be done right after the <script></script> section of the htmlTemplate variable:

<script>
  new Flexmonster(
    // initialization parameters
  );
  function customizeCellFunction (cell, data) {
    // function implementation
  }
  ${this.registerEvents()}
</script>

<style>
  #fm-pivot-view #fm-grid-view div.alter1 {
    background-color: #f7f7f7;
  }
  #fm-pivot-view #fm-grid-view div.alter2 {
    background-color: #fcfcfc;
  }
</style>

Step 5.3. Call the customizeCell method and pass the customizeCellFunction to it. Note that customizeCell can be defined in two ways:

As a regular API call

<script>
  new Flexmonster({
    // initialization parameters
  });
  function customizeCellFunction (cell, data) {
    // function implementation
  }
  ${this.registerEvents()}
  flexmonster.customizeCell(customizeCellFunction);
</script>

As an initialization parameter

new Flexmonster({
  container: "pivotContainer",
  //other initialization parameters
  report: JSON.parse('${JSON.stringify(this.props.report)}'),
  customizeCell: customizeCellFunction
});

Step 6. Run the project

Run the project from the console with the following command:

expo start

Now all the cells on the grid will be customized by the customizeCellFunction. Other customizations can be achieved in the same way.

What’s next?

You may be interested in the following articles:

Changes to Flexmonster Software License Agreement