vega_embed_flutter 0.5.0+2

  • Readme
  • Changelog
  • Example
  • Installing
  • 63

pub package

vega_embed_flutter #

A Flutter widget to embed vega-lite charts to flutter web. Works only in Flutter web as of now. Internall it uses vega-embed js library to embed these specs using JS interops and HTMLElementView. A Demo page with examples for available vega-embed options is available below.

A demo page

A full fledged demo page with various charts utilizing this package is avalaible here

Demo Page Gif

Credits #

This widget is made possible only because of the great works done by the team behind vega-embed, vega-Lite and vega. For a detailed documentation of how visualize using Vega-lite specs please head to their doumentaition page.

General Setup Steps #

Start by adding the script tag for vega related java script files. For example.

Index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-lite@4"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
    <title>vega_flutter</title>
  </head>
  <body>
    <script src="main.dart.js" type="application/javascript"></script>
  </body>
</html>

Add your vega lite schema files #

Vega-Lite and Vega defines its visualsation in the form of json file. So for you project it would be easy to maintain all this vega-lite spec files in a folder say vega_lite_specs folder. For example

$Project_root\vega_lite_specs
              |_ bart_chart.json
              |_ interactive_multiline_plot.json
              |_ interactive_splom.json

Add assets entry in pupspec.yaml #

In order for the web build to pick up the json schemas add it your pubspec.yaml. For e.g.

flutter:
  uses-material-design: true
  # This line includes all the files these directories during the build process
  # and placess them under build/web/assets folder.
  assets:
    - vega_lite_specs/

Import the file and use the widget #

Just import the vega_embed_flutter library as below

import 'package:vega_embed_flutter/vega_embed_flutter.dart';

Create a normal stateless/ful widget and use it as a normal stateless/ful widget.

class BarChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return VegaLiteEmbedder(
      viewFactoryId: 'MyBarChart',
      vegaLiteSpecLocation: '/assets/vega_lite_specs/bar_chart.json',
    );
  }
}

VegaEmbed Options [WIP] #

Following vega-embed options are tested and are available as part of demo page. If you need further comprehensive options to be tested or enabled please do raise and issue so that I can spend time on options which are necessary.

For a detailed description of what each vega embed options check this page. https://github.com/vega/vega-embed#options

Embed OptionsWorkingComments
mode🚧Avialble but not tested.
theme💯Check here for detials on the themes. Valid values are [excel, ggplot2, quartz, vox, fivethirtyeight , dark, latimes, urbaninstitute, googlecharts]
defaultStyle✔️
renderer✔️
logLevel🚧
tooltip🤔Let me know if you need it
loader
patch
width✔️Note: ⚠️ width mentioned in spec overrides this.
height✔️Note: ⚠️ Height mentioned in spec overrides this.
padding✔️
actions🚧Note: ⚠️ an example is shown to remove actions. But its not complete to spec.
scaleFactor✔️Note: This is a scale factor for the exported file, not the plot.
config🤔Let me know if you need it. Porting config object to dart will take lot of effort to test.
editorUrl🚧Avialble but not tested.
sourceHeader🚧Avialble but not tested.
sourceFooter🚧Avialble but not tested.
hover🤔Let me know if you need it.
i18n✔️
downloadFileName✔️
formatLocale🚧Avialble but not tested.
timeFormatLocale🚧Avialble but not tested.

Any kind of code, idea, suggestions are welcome. Please check the repository and file your feedbacks and bugs which is highly appreciated.

[0.5.0] - [0.5.0+2] 23 April 2020. #

  • Added more vega embed options and tested.
  • Added more examples for embed options.
  • Now the demo page includes code samples.
  • Edited the example md to include live page and corrected some spelling errors.

[0.1.1+1] - [0.1.1+3] 17 March 2020. #

  • edited the example section.
  • added git hub actions.

[0.1.1] - 16 March 2020. #

  • Now the widget accepts and passes the VegaEmbedOptions.
  • Created a full fledged demo page.
  • Example includes better documentation.

[0.1.0] - 10 March 2020. #

  • Removed double Rendering.
    • Now uses the vega-embed and vega-tool tip styles directly.
  • Multiple Charts in Single page is working now.
  • Changed the example folder structure.
  • Renamed VegaLiteSchemLocation to VegaLiteSpecLocation.
  • Differentiating Schema vs Spec.

[0.0.1] - 06 March 2020. #

  • A basic version of vega_embed for flutter.
    • Works with single charts.
    • Interactions works as well.

TODO:

  • Enable flutter webview to support mobile platform.
  • Extend vega-embed options to fully suport all options.
  • [x] Provide more vega-lite references.
  • [x] Document the theming section
  • [x] Add a section vega-embed options.
  • [x] Add a definitve and documented demo. A basic example is available in the exampe folder.
  • [x] Set up a live page with mutltitude of charts.
  • [x] Enable vega-embed theming.
  • [x] Work on rendering multiple charts in the same page.

example/example.md

Examples from the Repo #

This is an example flutter web app which renders multiple vega-lite specs in one page using column and row arrangements.

Running the example from the repo. #

This example can be run by changing into the example folder and running for web using the following commands.

$> git clone https://github.com/Abhilash-Chandran/vega_embed_flutter.git
$> cd vega_embed_flutter/example
$> flutter run -d chrome

This will run the availale example and open a browser with the predefined charts embeded using VegaLiteEmbedder widget.

Result of repo example. #

The example from the repo showcase multiple charts being laid out in a single page with different default theming options provided by the vega-embed project. It additionally shows the embed options demo page. A live version of this page can be found here. https://abhilash-chandran.github.io/vega_embed_flutter/#/

Repo example output

Getting started with your own chart #

This instructions assumes user has enable flutter-web config essential for flutter web development. If not please check this get-started page.

  1. Create directory for your project say 'vega_embed_test'
  2. Create a flutter-web project using flutter create . command.
  3. Edit your pubspec.yaml file to install the vega_embed_flutter package.
    • e.g. add vega_embed_flutter: ^0.1.0 to the dependecies

Start by adding the script tag for vega related java script files. For example.

Index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-lite@4"></script>
    <script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
    <title>vega_flutter</title>
  </head>
  <body>
    <script src="main.dart.js" type="application/javascript"></script>
  </body>
</html>

Creating vega-lite spec json file #

For example here we can create bar-chart.vl.json file under the directory vega_lite_specs as shown below.

 vega*lite_specs
       |_>  bar-charts.vl.json
       |_>  another-chart.vl.json

Add contents to bar-charts.vl.json #

Following is a simple bar chart with embeded data.

{
  "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
  "description": "A simple bar chart with embedded data.",
  "width": 500,
  "data": {
    "values": [
      { "a": "A", "b": 28 },
      { "a": "B", "b": 55 },
      { "a": "C", "b": 43 },
      { "a": "D", "b": 91 },
      { "a": "E", "b": 81 },
      { "a": "F", "b": 53 },
      { "a": "G", "b": 19 },
      { "a": "H", "b": 87 },
      { "a": "I", "b": 52 }
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": { "field": "a", "type": "ordinal" },
    "y": { "field": "b", "type": "quantitative" }
  }
}

Ther are extension in VS-Code for visualizing the vega-lite specs in VS code itself. Also additional online editors are availblable for this. Check this vega-lite ecosystem page. This can act as a quick prototype before rendering it as a flutter widget.

Add the assets in pubspec.yaml #

In order to access the above created json as an asset, it must added to the pubspec.yaml as folows.

flutter:
  assets:
    - vega_lite_specs/ # Note: adds all the specs in this directory but not folders.
    - other_image_assets/
    - miscelaneous_js/custom.js

Use the VegaLiteEmbedder widget #

Create a stateless/ful widget and use the VegaLitEmbder widget as shown below. // Note that assets are to be accessed from "/assets" folder. Vega-embed resolves this json as a relative URL say 'http://domain:port/mycustompage/assets/vega_lite_specs/bar_chart.json'.

Also the viewFactoryId attribute should be unique across multiple VegaLiteEmbedder widget. This is a requirement from HTMLElementView widget which is internally used by this embedder widget.

import 'package:vega_embed_flutter/vega_embed_flutter.dart';

/// A simple bar chart with inline data.
class BarChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return VegaLiteEmbedder(
      viewFactoryId: 'MyBarChart',
      vegaLiteSpecLocation: '/assets/vega_lite_specs/bar_chart.json',
    );
  }
}

Edit you main.dart #

In your main.dart file include this new BarChart widget as part of other widgets. Thats it. Then run your application flutter run -d web.

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

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Vega=embed demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyPage(),
    );
  }
}

class MyPage extends StatelessWidget {
  const MyPage({
    Key key,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return BarChart();
  }
}

class BarChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return VegaLiteEmbedder(
      viewFactoryId: 'MyBarChart',
      vegaLiteSpecLocation: '/assets/vega_lite_specs/bar_chart.json',
    );
  }
}

example output #

When you run this project you should get an ouput like this.

Example output

Theming #

Vega-embed comes with some basic set of default themes which can be used like for example 'dark', 'ggplot2' etc. A full set of predefined themes can be found here Vage-Themes.

VegaLiteEmbedder widget comes with an option where you can enable this themes. for example following bar chart renders in dark mode.

import 'package:vega_embed_flutter/vega_embed_flutter.dart';

/// A simple bar chart with dark theme.
class BarChart extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return VegaLiteEmbedder(
      viewFactoryId: 'MyBarChart',
      vegaLiteSpecLocation: '/assets/vega_lite_specs/bar_chart.json',
      vegaOptions: VegaEmbedOptions(theme: 'dark'),
    );
  }
}

Here is how the output looks like

demo_dark_bar chart

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  vega_embed_flutter: ^0.5.0+2

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:vega_embed_flutter/vega_embed_flutter.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
26
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
63
Learn more about scoring.

We analyzed this package on May 24, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.1
  • pana: 0.13.8-dev
  • Flutter: 1.17.0

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
flutter 0.0.0
js ^0.6.0 0.6.1+1
Transitive dependencies
collection 1.14.12
meta 1.1.8
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test