/ 
Chart-ECharts-1.02
/ Chart::ECharts

NAME

Chart::ECharts - Apache ECharts wrapper for Perl

SYNOPSIS

use Chart::ECharts;

my $chart = Chart::ECharts->new( responsive => 1 );

$chart->add_xAxis(
    type => 'category',
    data => ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
);

$chart->add_yAxis(type => 'value');

$chart->add_series(
    name => 'series_name',
    type => 'bar',
    data => [120, 200, 150, 80, 70, 110, 130]
);

# Render in HTML
say $chart->render_html;

# Render chart image (require Node.js)
$chart->render_image(
    output => 'charts/bar.png',
    width  => 800,
    height => 600
);
Bar Chart

DESCRIPTION

Chart::ECharts is a distribution that works as a wrapper for the Apache Echarts js library.

https://echarts.apache.org/

METHODS

$chart = Chart::ECharts->new(%params)

Params

charts_object, Charts object accessible via window object (default ChartEcharts)
class, Chart container CSS class (default chart-container)
container_prefix, Default chart container prefix (default undef)
events, Events (default [])
height, Chart height
id, Chart ID (default chart_ + "random string")
locale, Chart locale (default en)
options, EChart options (https://echarts.apache.org/en/option.html) (default {})
renderer, Default ECharts renrerer (default canvas)
responsive, Enable responsive feature
series, Chart series (https://echarts.apache.org/en/option.html#series)
styles, Default char styles (default ['min-width:auto', 'min-height:300px'])
theme. Chart theme (default white)
vertical, Set the chart in vertical (default 0)
width, Chart width
xAxis, Chart X Axis (https://echarts.apache.org/en/option.html#xAxis)
yAxis, Chart Y Axis (https://echarts.apache.org/en/option.html#yAxis)

Return Chart::ECharts object.

$chart->set_options(%options)

Set Apache EChart options (see Apache ECharts documentations https://echarts.apache.org/en/option.html).

$chart->set_options(
    title => {text => 'My Chart'},
    grid  => {left => 10, bottom => 10, right => 10, containLabel => \1}
);
$chart->set_option(%params)

(DEPRECATED) Alias of set_options

$chart->set_option_item($name, $params)
$chart->get_random_id

Get the random chart ID.

$chart->set_event($event, $callback)

Set a JS event.

$chart->on('click', q{ console.log(params); });
$chart->on($event, $callback)

Alias of set_event.

$chart->add_script($script)

Add custom JS script. All scripts are rendered via render_html and render_script.

$chart->add_script(q{
    console.log('Hello World');
});
$chart->add_xAxis(%axis)

Add single X axis (see Apache ECharts documentations https://echarts.apache.org/en/option.html#xAxis).

$chart->add_xAxis(
    type => 'category',
    data => ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
);
$chart->set_xAxis(%axis)

Set X axis (see Apache ECharts documentations https://echarts.apache.org/en/option.html#xAxis).

$chart->set_xAxis(
    splitLine => {
        lineStyle => {
            type => 'dashed'
        }
    }
);
$chart->add_yAxis(%axis)

Add single Y axis (see Apache ECharts documentations https://echarts.apache.org/en/option.html#yAxis).

$chart->add_yAxis(
    type => 'value'
);
$chart->set_yAxis(%axis)

Set Y axis (see Apache ECharts documentations https://echarts.apache.org/en/option.html#yAxis).

$chart->set_yAxis(
    splitLine => {
        lineStyle => {
            type => 'dashed'
        }
    }
);
$chart->add_series(%series)

Add single series (see Apache ECharts documentations https://echarts.apache.org/en/option.html#series).

$chart->add_series(
    name => 'series_name',
    type => 'bar',
    data => [120, 200, 150, 80, 70, 110, 130]
);
$chart->js($expression)

Embed arbritaty JS code in chart options.

$chart->set_tooltip(
    valueFormatter => $chart->js( q{(value) => '$' + Math.round(value)} )
);

OPTION HELPERS

$chart->set_title(%params)

Set the chart title

$chart->set_toolbox(%params)

Set the chart toolbox

$chart->set_tooltip(%params)

Set the chart tooltip

$chart->set_legend(%params)

Set the chart legend

$chart->set_timeline(%params)

Set the chart timeline

$chart->set_data_zoom(%params)

Set the chart data zoom

$chart->add_data_zoom(%params)

Add the chart data zoom

PROPERIES

$chart->xAxis

Return X axis.

$chart->yAxis

Return Y axis.

$chart->series

Return chart series.

$chart->default_options

Return chart default options.

$chart->options

Return all chart options.

$chart->axies

Return X and Y axies.

RENDERS

$chart->render_script(%params)

Render the chart in JS.

my $script = $chart->render_script;
$chart->render_html(%params)

Render the chart in HTML including the output of render_script with a div container.

$chart->render_image(%params)

Render the chart image file (require Node.js).

Parameters

node_path, Node.js (aka node_modules) path (default: $ENV{NODE_PATH})
node_bin, Node.js binary (optional)
output, Output file (required)
format, Output file format (png or svg, optional)
width, Image width (default: 400)
height, Image height (default: 300)
$chart->TO_JSON

Encode options in JSON.

Embed Chart::ECharts in your web application:

Mojolicious

use Mojolicious::Lite -signatures;

helper render_chart => sub ($c, $chart) {
    Mojo::ByteStream->new($chart->render_html);
};

get '/chart' => sub ($c) {

    my $cool_chart = Chart::ECharts->new;

    # [...]

    $c->render('chart', cool_chart => $cool_chart);

};

app->start;

__DATA__

@@ default.html.ep
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title><%= title %></title>
    <!-- Include the ECharts file you just downloaded -->
    <script src="echarts.js"></script>
  </head>
  <body>
    %= content
  </body>
</html>

@@ chart.html.ep

% layout 'default';
% title 'My cool chart with Chart::ECharts';

<h1>My cool chart with Chart::ECharts</h1>

<p><% render_chart($cool_chart) %></p>

Setup Node.js

Install Apache ECharts >= 5.4 (https://www.npmjs.com/package/echarts) and Canvas >= 2.11 (https://www.npmjs.com/package/canvas):

$ cd your-project-path
$ npm add canvas echarts

You can use the share/package.json in the distribution directory:

$ cd your-project-path
$ cp <Chart-EChart-dist>/share/package.json .
$ npm install

In your Perl script set the node_path options (or set $ENV{NODE_PATH} enviroment), node_bin if Node.js is not in $ENV{PATH} and output image file:

local $ENV{NODE_PATH} = 'your-project-path/node_modules';

$chart->render_image(
    output => 'charts/bar.png',
    width  => 800,
    height => 600
);

Charts object

By default Chart::ECharts expose an object in window.ChartECharts object (use charts_object config to rename).

Properties:

charts, ARRAY of chart IDs

This property contains an ARRAY of all generated graphs (via render_html and render_script). It is useful to allow customization of the graph via JS.

my $chart = Chart::ECharts(id => 'myChart');

# ...

$chart->render_html;

# in your JS

if ('myChart' in window.ChartECharts.charts) {

    let myChart = window.ChartECharts.charts.myChart;

    let newLabels = [];
    let newData   = [];

    // Update chart data
    myChart.setOption({
        xAxis: {
            data: newLabels
        },
        series: [
            {
                data: newData
            }
        ]
    });

}

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/giterlizzi/perl-Chart-ECharts/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/giterlizzi/perl-Chart-ECharts

git clone https://github.com/giterlizzi/perl-Chart-ECharts.git

AUTHOR

  • Giuseppe Di Terlizzi <gdt@cpan.org>

LICENSE AND COPYRIGHT

This software is copyright (c) 2024 by Giuseppe Di Terlizzi.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.