# NAME
HTML::D3 - A simple Perl module for generating charts using D3.js.
# VERSION
Version 0.15
# SYNOPSIS
use HTML::D3;
my $chart = HTML::D3->new(
width => 1024,
height => 768,
title => 'Sample Bar Chart'
);
my $data = [
['Category 1', 10],
['Category 2', 20],
['Category 3', 30]
];
my $html = $chart->render_bar_chart($data);
print $html;
$chart = HTML::D3->new(title => 'Sales Data');
$data = [
['Product A', 100],
['Product B', 150],
['Product C', 200]
];
$html = $chart->render_line_chart($data);
print $html;
# DESCRIPTION
HTML::D3 is a Perl module that provides functionality to create simple charts using D3.js.
The module generates HTML and JavaScript code to render the chart in a web browser.
# METHODS
The `=head3 API SPECIFICATION` subsections use [Params::Validate::Strict](https://metacpan.org/pod/Params%3A%3AValidate%3A%3AStrict)
schema syntax (`type => 'arrayref'` etc.) as a documentation convention.
The module is also used at runtime in `new()` to validate constructor
arguments; it is therefore a required runtime dependency. The schemas describe
the parameter contract in machine-readable notation and can be plumbed into a
WAF or test generator if desired.
## new
my $chart = HTML::D3->new(%args);
Creates a new HTML::D3 object.
Accepts the following optional arguments:
- `width` - The width of the chart (default: 800).
- `height` - The height of the chart (default: 600).
- `title` - The title of the chart (default: 'Chart').
## render\_bar\_chart
my $html = $chart->render_bar_chart($data);
Generates HTML and JavaScript code to render a bar chart. Accepts the following arguments:
- `$data` - An array reference containing data points. Each data point should
be an array reference with two elements: the label (string) and the value (numeric).
Returns a string containing the HTML and JavaScript code for the chart.
### Errors
- Throws `Data is not optional` when `$data` is `undef`.
- Throws `Data must be an array of arrays` when `$data` is not an ARRAY reference.
### Side Effects
None.
### API SPECIFICATION
#### Input
{
data => {
type => 'arrayref',
element_type => [ 'string', 'number' ]
}
}
Each element of C<$data> is C<[ Str, Num ]>; passing C or a
non-arrayref dies.
#### Output
Str -- complete HTML5 document starting with C<< >>;
D3.js loaded from CDN; bar chart rendered with C.
## render\_animated\_bar\_chart
my $html = $chart->render_animated_bar_chart($data);
Generates HTML and JavaScript code to render a bar chart where each bar grows
upward from the baseline on page load. Bars are staggered so they rise
one-after-another from left to right.
Accepts the following arguments:
- `$data` - An array reference of data points. Each data point is an
array reference with two elements: the label (string) and the value (numeric).
Returns a string containing the complete HTML5 document.
### Errors
- Throws `Data is not optional` when `$data` is `undef`.
- Throws `Data must be an array of arrays` when `$data` is not an ARRAY reference.
### Side Effects
None.
### API SPECIFICATION
#### Input
{
data => { type => 'arrayref' },
}
Each element of C<$data> is C<[ Str, Num ]>; passing C or a
non-arrayref dies.
#### Output
Str -- complete HTML5 document; each bar animates from height=0 upward
using C with a staggered per-bar delay.
## render\_line\_chart
my $html = $chart->render_line_chart($data);
Generates HTML and JavaScript code to render a line chart. Accepts the following arguments:
- `$data` - An array reference containing data points. Each data point should
be an array reference with two elements: the label (string) and the value (numeric).
Returns a string containing the HTML and JavaScript code for the chart.
### Errors
- Throws `Data must be an array of arrays` when `$data` is not an ARRAY reference.
### Side Effects
None.
### API SPECIFICATION
#### Input
{
data => { type => 'arrayref' },
}
Each element of C<$data> is C<[ Str, Num ]>; passing C or a
non-arrayref dies.
#### Output
Str -- complete HTML5 document; line chart with C and C.
## render\_animated\_line\_chart
my $html = $chart->render_animated_line_chart($data);
Generates HTML and JavaScript code to render a line chart where the line
draws itself from left to right on page load, followed by each data-point
circle fading in once the line is complete.
Accepts the following arguments:
- `$data` - An array reference of data points. Each data point is an
array reference with two elements: the label (string) and the value (numeric).
Returns a string containing the complete HTML5 document.
### Errors
- Throws `Data must be an array of arrays` when `$data` is not an ARRAY reference.
### Side Effects
None.
### API SPECIFICATION
#### Input
{
data => { type => 'arrayref' },
}
Each element of C<$data> is C<[ Str, Num ]>; passing C or a
non-arrayref dies.
#### Output
Str -- complete HTML5 document; the line path animates via
C with C; data-point circles
fade in with C after the line transition completes.
## render\_pie\_chart
my $html = $chart->render_pie_chart($data);
my $html = $chart->render_pie_chart($data, { separator => ':' });
Generates HTML and JavaScript code to render a pie chart.
Each slice is coloured with `d3.schemeCategory10`; percentage labels appear
inside each slice and a colour legend is shown to the right of the pie.
Accepts the following arguments:
- `$data` - An array reference of data points. Each data point is an
array reference with two elements: the label (string) and the value (numeric).
- `%opts` - Optional hashref of options.
- `separator` (string, default `'/'`) - Character shown between the
label and value in the SVG legend.
Returns a string containing the complete HTML5 document.
### Errors
- Throws `Data is not optional` when `$data` is `undef`.
- Throws `Data must be an array of arrays` when `$data` is not an ARRAY reference.
### Side Effects
None.
### API SPECIFICATION
#### Input
{
data => {
type => 'arrayref',
element_type => [ 'string', 'number' ]
},
opts => { type => 'hashref', optional => 1, default => {} },
}
Each element of C<$data> is C<[ Str, Num ]>; passing C or a
non-arrayref dies.
Recognised C key: C (string, default C<'/'>)
- character shown between label and value in the SVG legend.
#### Output
Str -- complete HTML5 document; pie rendered with C and
C; slices coloured with C;
percentage label inside each slice; legend to the right.
## render\_animated\_pie\_chart
my $html = $chart->render_animated_pie_chart($data);
my $html = $chart->render_animated_pie_chart($data, { separator => ':' });
Generates HTML and JavaScript code to render an animated pie chart where each
slice fans out from zero angle on page load using `attrTween` and
`d3.interpolate`. Percentage labels fade in once all slices are drawn.
Accepts the following arguments:
- `$data` - An array reference of data points. Each data point is an
array reference with two elements: the label (string) and the value (numeric).
- `%opts` - Optional hashref of options.
- `separator` (string, default `'/'`) - Character shown between the
label and value in the SVG legend.
Returns a string containing the complete HTML5 document.
### Errors
- Throws `Data is not optional` when `$data` is `undef`.
- Throws `Data must be an array of arrays` when `$data` is not an ARRAY reference.
### Side Effects
None.
### API SPECIFICATION
#### Input
{
data => {
type => 'arrayref',
element_type => [ 'string', 'number' ]
},
opts => { type => 'hashref', optional => 1, default => {} },
}
Each element of C<$data> is C<[ Str, Num ]>; passing C or a
non-arrayref dies.
Recognised C key: C (string, default C<'/'>)
- character shown between label and value in the SVG legend.
#### Output
Str -- complete HTML5 document; slices animate via C with
C (1000 ms); percentage labels fade in afterwards.
## render\_pie\_chart\_snippet
my $fragment = $chart->render_pie_chart_snippet(\@slices);
my $fragment = $chart->render_pie_chart_snippet(\@slices, \%opts);
# $fragment->{svg_id} - always 'pie_chart'
# $fragment->{html} - embeddable fragment; caller must load D3 v7
Generates an embeddable pie or donut chart fragment for use in existing HTML
layouts. Returns `{ svg_id => 'pie_chart', html => Str }`. The
caller is responsible for loading D3 v7 before embedding the fragment.
### Data format
Each element of `\@slices` is `[$label, $value]` or `[$label, $value, \%extra]`.
Negative values are silently converted to their absolute value. Zero-value
slices are silently omitted. `\%extra` key/value pairs are shown as
additional rows in the hover tooltip.
### Options (`\%opts`)
- `animated` (bool, default 0) - fan slices in from arc-length 0 on
first render using `attrTween` / `d3.easeBackOut` (800 ms, staggered).
Respects `prefers-reduced-motion`.
- `donut` (bool, default 0) - render as a donut chart (inner radius
38% of outer radius); the total sum appears in the centre hole.
- `sort_slices` (string, default `'none'`) - `'value'` for
largest-first, `'label'` for alphabetical, `'none'` for input order.
- `max_slices` (int, default 0) - when > 0, only the top N-1
slices are shown individually; the rest are collapsed into an `"Other"` slice.
- `legend` (bool, default 1) - render an HTML legend panel beside the chart.
- `color_scheme` (string, default `'tableau10'`) - D3 categorical
colour scheme. Supported: `tableau10`, `category10`, `set2`, `set3`,
`paired`.
- `separator` (string, default `'/'`) - Character shown between the
label and value in each legend entry (e.g. `'/'` produces
`Label / 12.34 (42.0%)`, `':'` produces `Label : 12.34 (42.0%)`).
### Errors
- Throws `Data must be an array of arrays` when `\@slices` is not an ARRAY reference.
### Side Effects
None.
### API SPECIFICATION
#### Input
{
data => { type => 'arrayref' },
opts => { type => 'hashref', optional => 1, default => {} },
}
Each element of C<$data> is C<[ Str, Num ]> or C<[ Str, Num, HashRef ]>;
passing C or a non-arrayref dies.
Recognised C keys: C (boolean, default C<0>),
C (boolean, default C<0>), C (string: C<'value'>,
C<'label'>, or C<'none'>; default C<'none'>), C (integer,
default C<0>), C