We have updated WebDataRocks EULA, effective as of April 18, 2024. Learn more about what's changed.
Download

Data type prefixes

Data type prefixes are added to field names in the first data record. Use the prefixes to set field data types in CSV.

The following prefixes are available:

NameDescription
-Numbers.
+Strings.
d+Dates divided into 3 subfields: Year, Month, Day.
ds+Dates displayed in the "dd/MM/yyyy" format.
D+Dates represented as the multilevel hierarchy: Year > Month > Day.
D4+Dates represented as the multilevel hierarchy: Year > Quarter > Month > Day.
dt+Dates displayed in the "dd/MM/yyyy HH:mm:ss" format.
t+Time intervals displayed in the "HH:mm:ss" format.
m+Months. Natural sorting is applied to field members.
w+Days of the week. Natural sorting is applied to field members.

Examples

1) Here is a sample CSV data where the ds+ and w+ prefixes are added to the field names:

ds+Invoice Date, Quantity, Country, w+Week Day
2018-05-15, 3, France, Tuesday
2018-05-16, 4, Italy, Wednesday
2018-05-17, 2, Spain, Thursday
2018-05-12, 2, Japan, Saturday

After loading the CSV data and selecting fields in the Field List, you can see that the Invoice Date is displayed as a string in the "dd/MM/yyyy" format, and the Week Day is interpreted as a day of the week:

2) You can represent a date as a multilevel hierarchy using the D+ or the D4+ prefix.

Here is an example with the D+ prefix:

D+Invoice Date, -Quantity, -Price, +Country
2018-05-15, 3, 329, France
2018-05-16, 4, 139, Italy
2018-05-17, 2, 429, Spain
2018-05-12, 2, 559, Japan

See how the Invoice Date is displayed in the pivot table when the CSV file is loaded to WebDataRocks:

This demo is also available on our CodePen.

To create multilevel hierarchies from fields of other types, use the JSON data source.

See also

In this guide, you can learn how to format your CSV data so WebDataRocks can process it.

WebDataRocks supports the following CSV format:

  • The first data record contains field names and optional data type prefixes.
  • Each data record is on a separate line.
  • Field names and values are separated by the same character: comma (,), semicolon (;), or a custom field separator.
  • A field name or value is enclosed in double quotes (") if it contains line breaks or a field separator. A double quote inside such values must be escaped using another double quote. For example: "The ""A, B, C"" magazine".

Here is an example of a valid CSV file:

Invoice Date,Quantity,Country,Week Day
2018-05-15,3,France,Tuesday
2018-05-16,4,Italy,Wednesday
2018-05-17,2,Spain,Thursday
2018-05-12,2,Japan,Saturday

See also

The mapping object for JSON is specified as the first element of the JSON array. This object is used for setting data types, creating multilevel hierarchies, and changing captions.

Properties

NameTypeDescription
typeStringoptional The field’s data type. Possible values: 
  • "number"
  • "string"
  • "date"
  • "date string"
  • "year/month/day"
  • "year/quarter/month/day"
  • "datetime"
  • "time"
  • "month"
  • "weekday"
  • "level"
  • "hidden"
 Read more about available data types in JSON.
captionStringoptional The field’s caption.
hierarchyStringoptional The name of the hierarchy. Used for multilevel hierarchies. Set this property to make the field a level of the specified hierarchy. In this case, the type must be set to "level". 
parentStringoptional The caption of the parent hierarchy level. Used for multilevel hierarchies. In this case, the type must be set to "level". 
levelStringoptional The caption of the hierarchy level. Used for multilevel hierarchies. In this case, the type must be set to "level".

Examples

1) Setting the mapping object in a JSON array of objects:

let jsonData = [
  {
    "Product": {
      type: "string"
    },
    "Price": {
      type: "number"
    }
  },
  {
    "Product": "Apple",
    "Price": 2.50
  },
  {
    "Product": "Cherry",
    "Price": 5.25
  }
];

See the full example on CodePen.

2) Setting the mapping object in a JSON array of arrays:

let jsonData = [
  {
    "Product": {
      type: "string"
    },
    "Price": {
      type: "number"
    },
  },
  ["Apple", 2.50],
  ["Cherry", 5.25]
];

Try a live demo on CodePen.

See also

Using the mapping object for JSON, you can create multilevel hierarchies from fields of any type.

In this guide, we’ll create a Food hierarchy with Category, Item, and Serving Size levels based on the data below:

[
  {
    "Category": "Breakfast",
    "Item": "Frittata",
    "Serving Size": "4.8 oz (136 g)",
    "Calories": 300
  },
  {
    "Category": "Breakfast",
    "Item": "Boiled eggs",
    "Serving Size": "4.8 oz (135 g)",
    "Calories": 250
  }
]

Step 1. In the mapping object, set the type of Category, Item, and Serving Size fields as "level":

[
  {
    "Category": {
      type: "level"
    },
    "Item": {
      type: "level"
    },
    "Serving Size": {
      type: "level"
    },
    "Calories": {
      type: "number"
    }
  },
  {
    "Category": "Breakfast",
    "Item": "Frittata",
    "Serving Size": "4.8 oz (136 g)",
    "Calories": 300
  },
  {
    "Category": "Breakfast",
    "Item": "Boiled eggs",
    "Serving Size": "4.8 oz (135 g)",
    "Calories": 250
  }
]

Step 2. Use the hierarchy, parent, and level properties of the mapping object to create the Food hierarchy:

[
  {
    "Category": {
      type: "level",
      hierarchy: "Food"
    },
    "Item": {
      type: "level",
      hierarchy: "Food",
      level: "Dish",
      parent: "Category"
    },
    "Serving Size": {
      type: "level",
      hierarchy: "Food",
      level: "Size",
      parent: "Dish"
    },
    "Calories": {
      type: "number"
    }
  },
  {
    "Category": "Breakfast",
    "Item": "Frittata",
    "Serving Size": "4.8 oz (136 g)",
    "Calories": 300
  },
  {
    "Category": "Breakfast",
    "Item": "Boiled eggs",
    "Serving Size": "4.8 oz (135 g)",
    "Calories": 250
  }
]

See how this dataset will be visualized in WebDataRocks:

Check out a live demo on CodePen.

See also

In this guide, you can learn how to format your JSON data so WebDataRocks can process it.

WebDataRocks supports two JSON formats:

1) Array of objects. Each object in the array is an unordered collection of key-value pairs, where the key is a field name and the value is a field member. Example:

let jsonData = [
  {
    "Product": "Apple",
    "Price": 2.50
  },
  {
    "Product": "Cherry",
    "Price": 5.25
  }
];

2) Array of arrays. The first subarray contains field names, while other subarrays contain the respective field members. The field’s name and members must have the same position in the subarrays. Example:

let jsonData = [
  ["Product", "Price"],
  ["Apple", 2.50],
  ["Cherry", 5.25]
];

Regardless of what JSON format you choose, the first element of each array can be the mapping object for JSON. This object is used to set data types and create multilevel hierarchies.

See also

This object contains configurations that will be applied to all reports in WebDataRocks. If needed, you can override global configurations in a report.

Check out how global configurations are saved in a report: Saving the report with global configs.

Properties

NameTypeDescription
dataSourceData Source Objectoptional Contains information about the data source.
optionsOptions Objectoptional Defines the view and functionality available for users.
localizationString|Objectoptional Sets a localization. For more details, refer to the language localization tutorial.

Examples

1) Setting a data source that will be used in all reports:

const pivot = new WebDataRocks({
  container: "#wdr-component",
  global: {
    dataSource: {
      type: "json",
      filename: "https://cdn.webdatarocks.com/data/data.json"
    }
  }
});

See the full code on CodePen.

2) Setting options to make all reports read-only:

const pivot = new WebDataRocks({
  container: "#wdr-component",
  global: {
    options: {
      grid: {
        showFilter: false,
        showReportFiltersArea: false,
      },
      configuratorButton: false,
      drillThrough: false,
      sorting: "off", 
    },
  }
});

Check out a live demo on CodePen.

3) Setting a localization that will be applied to all reports:

const pivot = new WebDataRocks({
  container: "#wdr-component",
  global: {
    localization: "https://cdn.webdatarocks.com/loc/es.json"
  }
});

See an example on CodePen.

4) Overriding global configurations in the report:

const pivot = new WebDataRocks({
  container: "#wdr-component",
  global: {
    dataSource: {
      type: "json",
      data: // Inline JSON data
    },
    options: {
      grid: {
        showFilter: false,
      },
      configuratorButton: false,
      sorting: "off", 
    },
  },
  report: {
    dataSource: {
      type: "csv",
      filename: "https://cdn.webdatarocks.com/data/data.csv"
    },
    options: {
      grid: {
        showFilter: true,
      },
      configuratorButton: true,
    },
  }
});

Try it out on CodePen.

See also

This guide describes how to integrate WebDataRocks with Flutter.

Prerequisites

This tutorial is split into the following sections:

Run our sample project from GitHub

Step 1. Download or clone the sample project from GitHub with the following commands:

git clone https://github.com/webdatarocks/pivot-flutter
cd pivot-flutter

Step 2. Install dependencies described in the pubspec.yaml file:

dart pub get

If you get an error on this step, add the Flutter SDK location to the PATH environment variable. Learn more in the Flutter docs.

Step 3. Connect a mobile device. Learn how to configure Android and iOS devices.

Step 4. Run the project:

flutter run

You can see the result on your mobile device.

To stop the project, press Ctrl + C (Control + C on macOS) in the console.

Available examples

The sample project contains the following examples:

Integrate with Flutter

To integrate WebDataRocks into a Flutter app, take the following steps:

Step 1 (optional). Create a project

If you don’t have an existing Flutter project, create one with the following command:

flutter create wdr_project && cd wdr_project

If you get an error on this step, add the Flutter SDK location to the PATH environment variable. Learn more in the Flutter docs.

Step 2. Download WebDataRocks

Get WebDataRocks package for Flutter by running the following command from your project’s root folder:

flutter pub add flutter_webdatarocks

Note. Our flutter_webdatarocks wrapper loads WebDataRocks files from CDN.

Step 3. Configure build settings

Ensure the required Android and iOS versions are used in your Flutter project.

Android

  • compileSdkVersion ≥ 32.
  • targetSdkVersion ≥ 32.
  • minSdkVersion ≥ 19.

iOS

  • iOS Deployment Target ≥ 9.
  • MinimumOSVersion ≥ 9.

Learn how to configure Android and iOS build settings in Flutter.

Step 4. Add WebDataRocks

Step 4.1. Create a .dart file (e.g., WDR.dart) in the lib/ folder of your project:

import 'package:flutter/material.dart';
 
class WDR extends StatelessWidget {
  const WDR({super.key});
 
  @override
  Widget build(BuildContext context) {
  }
}

Step 4.2. Import flutter_webdatarocks into the WDR.dart file:

import 'package:flutter/material.dart';
import 'package:flutter_webdatarocks/flutter_webdatarocks.dart';

class WDR extends StatelessWidget {
  const WDR({super.key});
 
  @override
  Widget build(BuildContext context) {
  }
}

Step 4.3. Create a WebDataRocks instance and return it from the build() method:

import 'package:flutter/material.dart';
import 'package:flutter_webdatarocks/flutter_webdatarocks.dart';

class WDR extends StatelessWidget {
  const WDR({super.key});
 
  @override
  Widget build(BuildContext context) {
    WebDataRocks pivot = WebDataRocks(
      toolbar: true, 
      report: const {
        "dataSource": {
          "dataSourceType": "csv",
          "filename": "https://cdn.webdatarocks.com/data/data.csv"
        }
      }
    );
    return pivot;
  }
}

The toolbar and the report are WebDataRocks initialization parameters. See the list of supported parameters.

Step 4.4. Add the WebDataRocks instance to a Flutter widget where the pivot table should appear. For example, copy and paste the code below into your main.dart file:

import 'package:flutter/material.dart';
import 'WDR.dart';
 
void main() {
  runApp(MaterialApp(
    title: 'WebDataRocks Demo',
    home: Scaffold(
      appBar: AppBar(
        backgroundColor: const Color.fromARGB(255, 5, 152, 223),
        foregroundColor: const Color.fromARGB(255, 233, 233, 233),
        title: const Text('WebDataRocks Demo')),
      // The WebDataRocks instance
      body: const WDR()))
  ); 
}

Step 5. Launch the app

Step 5.1. Run the following command to make sure a mobile device is connected:

flutter devices

If the device is not shown, check out Flutter setup guides for Android and iOS.

Step 5.2. Launch your app with the following command:

flutter run

See the results on the mobile device.

To stop the project, press Ctrl + C (Control + C on macOS) in the console.

WebDataRocks initialization parameters

In Flutter, most WebDataRocks initialization parameters are supported, except for the following:

Use methods and events

Using methods

You can invoke WebDataRocks methods via the variable with the WebDataRocks instance (e.g., pivot):

pivot.openFieldsList();

Check out an example on GitHub.

Note. In Flutter, all WebDataRocks API calls are asynchronous, except for on() and off().

Supported WebDataRocks methods

Most WebDataRocks methods are supported in Flutter, apart from the following:

Note. Unsupported methods can be accessed via JavaScript.

Using events

Subscribing

Attach a handler to a WebDataRocks event using the on() API call:

void updateHandler() {
  // Event handler
}

pivot.on("update", updateHandler);

An event handler can also be defined as an anonymous function:

pivot.on("update", () {
  // Event handler
});

To get data from an event, add the data input parameter to the handler:

pivot.on("cellclick", (data) {
  // Event handler
});

Check out an example on GitHub.

See the full list of WebDataRocks events.

Unsubscribing

Event handlers can be removed via the off() API call:

  • Remove all handlers from a specific event:
    pivot.off("cellclick");
  • Remove a specific event handler:
    pivot.off("cellclick", cellclickHandler);

Access unsupported WebDataRocks features through JavaScript

Using JavaScript, you can access WebDataRocks methods that are not directly supported in Flutter.

For instance, let’s highlight cells you click using customizeCell:

Step 1. Import webview_flutter in the .dart file with WebDataRocks (e.g., WDR.dart):

import 'package:flutter/material.dart';
import 'package:flutter_webdatarocks/flutter_webdatarocks.dart';
import 'package:webview_flutter/webview_flutter.dart';
 
class WDR extends StatelessWidget {
  const WDR ({super.key});
 
  @override
  Widget build(BuildContext context) {
    WebDataRocks pivot = WebDataRocks(
      toolbar: true, 
      report: const {
        "dataSource": {
          "dataSourceType": "csv",
          "filename": "https://cdn.webdatarocks.com/data/data.csv"
        }
      }
    );
    return pivot;
  }
}

Step 2. Create an anonymous async handler for the cellclick event. JavaScript code will be run in the handler:

@override
Widget build(BuildContext context) {
  WebDataRocks pivot = WebDataRocks(
    toolbar: true, 
    report: const {
      "dataSource": {
        "dataSourceType": "csv",
        "filename": "https://cdn.webdatarocks.com/data/data.csv"
      }
    }
  );
  pivot.on("cellclick", (data) async {
    // Your JavaScript code will be run here
  });
  return pivot;
}

Step 3. Create a WebViewController instance (e.g., controller) in the handler:

pivot.on("cellclick", (data) async {
  // Your JavaScript code will be run here
  WebViewController controller = await pivot.controller.future;
});

Step 4. Call the runJavascript() method on the controller and specify JavaScript code as a parameter:

pivot.on("cellclick", (data) async {
  // Your JavaScript code will be run here
  WebViewController controller = await pivot.controller.future;
  controller.runJavascript('''
    webdatarocks.customizeCell((cellBuilder, cellData) => {
      if(cellData.label === "${data['label']}") {
        cellBuilder.style.background = "rgba(5, 152, 223, 0.5)";
      }
    });
  ''');
});

Note. runJavascript() does not return the result of your JavaScript code. To return the result, use the runJavascriptReturningResult() method instead.

Now every time you click a grid cell, it is highlighted with a blue color.

Check out another example of using JavaScript in our sample GitHub project.

We use only open-source components in WebDataRocks. Here is a list of these libraries and links to their respective licenses:

See also

This page contains information about browsers compatible with WebDataRocks.

Starting from version 1.4, WebDataRocks follows the ES6 standard. As a result, the component will work correctly only in browsers that fully support ES6. You can find these browsers and their versions in the below table:

BrowserVersion
Chrome51+
Firefox54+
Microsoft Edge15-18, 79+
Opera 38+
Safari 10+
iOS Safari 10+
Internet ExplorerNot supported*

*To work with WebDataRocks in Internet Explorer, use WebDataRocks versions earlier than 1.4. The component’s version history is available on npm. See how to install a specific package version from npm.
To include exact WebDataRocks versions from our CDN, follow this guide.