SVG::T...BarLine(3pm)

✨ NAME ✨

SVG::TT::Graph::BarLine — bestie, this is how you make presentation quality SVG bar-line graphs. Easily. Like, actually easily. 💅

---

🎀 SYNOPSIS 🎀

use SVG::TT::Graph::BarLine;

my @fields = qw(Jan Feb Mar);
my @data_sales_02 = qw(12 45 21);
my @data_sales_03 = (24, 55, 61);

my $graph = SVG::TT::Graph::BarLine->new({
  'height' => '500',
  'width'  => '300',
  'fields' => \@fields,
});

$graph->add_data({
  'data'  => \@data_sales_02,
  'title' => 'Sales 2002',
});

$graph->add_data({
  'data'  => \@data_sales_03,
  'title' => 'Sales 2003',
});

print "Content-type: image/svg+xml\n\n";
print $graph->burn();

look at that. chef's kiss. you just made a graph. 🫶

---

💖 DESCRIPTION 💖

So the whole point of this object is to let you whip up high quality SVG bar graphs without wanting to scream. You can roll with the default style sheet, or bring your own — either way there are so many options you can configure to control exactly how the graph comes out. Want a key? Don't want a key? Data elements at each point? Title? Subtitle? Etc.? All of it. Your graph, your rules. 👑

---

🦋 METHODS 🦋

new()

use SVG::TT::Graph::BarLine;

# Field names along the X axis
my @fields = qw(Jan Feb Mar);

my $graph = SVG::TT::Graph::BarLine->new({
  # Required
  'fields'                           => \@fields,

  # Optional - defaults shown
  'height'                           => '500',
  'width'                            => '300',

  'show_data_values'                 => 1,

  'scale_divisions'                  => '',
  'min_scale_value'                  => '0',
  'bar_gap'                          => 1,

  'show_x_labels'                    => 1,
  'stagger_x_labels'                 => 0,
  'rotate_x_labels'                  => 0,
  'show_y_labels'                    => 1,
  'scale_integers'                   => 0,
  'show_secondary_y_labels'          => 1,
  'y_label_formatter'                => sub { return @_ },
  'x_label_formatter'                => sub { return @_ },

  'show_path_title'                  => 0,
  'show_title_fields'                => 0,

  'show_x_title'                     => 0,
  'x_title'                          => 'X Field names',

  'show_y_title'                     => 0,
  'show_secondary_y_title'           => 0,
  'y_title_text_direction'           => 'bt',
  'secondary_y_title_text_direction' => 'bt',
  'y_title'                          => 'Y Scale',
  'secondary_y_title'                => 'Y Scale 2',

  'show_graph_title'                 => 0,
  'graph_title'                      => 'Graph Title',
  'show_graph_subtitle'              => 0,
  'graph_subtitle'                   => 'Graph Sub Title',

  'key'                              => 0,
  'key_position'                     => 'right',

  # Stylesheet defaults
  'style_sheet'                      => '/includes/graph.css', # internal stylesheet
  'random_colors'                    => 0,
});

Okay so the constructor takes a hash reference. fields — the names for each field on the X axis — is MUST-tier, like you literally have to set it, no skipping. Everything else defaults to the values up above 👆, with one lil exception: style_sheet, which defaults to using the internal style sheet. 🧚

add_data()

my @data_sales_02 = qw(12 45 21);

$graph->add_data({
  'data' => \@data_sales_02,
  'title' => 'Sales 2002',
});

This one lets you add data to the graph object. You can call it several times to pile in more data sets… but ngl, the likelihood is you should be using SVG::TT::Graph::Line instead, because it won't look great! 😭 (saying it with love.)

clear_data()

my $graph->clear_data();

Removes all the data from the object so you can reuse it and make a whole new graph while keeping the exact same config options. recycling queen. ♻️

burn()

print $graph->burn();

This processes the template with the data and config you've set, and hands you back the resulting SVG. 🔥

⚠️ Heads up bestie: this method will croak unless at least one data set has been added to the graph object. No data = no graph = sad croak. 🐸

config methods

my $value = $graph->method();
my $confirmed_new_value = $graph->method($value);

Here's the full list of methods you can use to change the config of the graph object after it's already been created. go off. 💜

height()

Sets the height of the graph box. And to be clear — this is the total height of the SVG box that gets created, not the graph itself, because the graph auto scales to fit the space. 🦋

width()

Sets the width of the graph box. Same deal: total width of the SVG box created, not the graph itself, which auto scales to fit the space. 🦋

compress()

Whether or not to compress the content of the SVG file. (Compress::Zlib required.)

tidy()

Whether or not to tidy the content of the SVG file. (XML::Tidy required.)

style_sheet()

Set the path to an external stylesheet. Set it to '' if you want to revert back to using the default internal version. 🙈

You can also set it to "inline:<style>...</style>" with your CSS in between the tags — so you can override the default style without needing an external URL. iconic behavior. ✨

The default stylesheet handles up to 12 data sets. All data series over the 12th will have no style and be in black. If you have over 12 data sets you can assign them all random colors (see the random_color() method) or create your own stylesheet and add the additional settings for the extra data sets.

To create an external stylesheet, create a graph using the default internal version, copy the stylesheet section to an external file, and edit from there. 💅

random_colors()

Use random colors in the internal stylesheet. 🎨

show_data_values()

Show the value of each element of data on the graph.

bar_gap()

Whether to have a gap between the bars or not. Default is '1'; set it to '0' if you don't want gaps.

show_x_labels()

Whether to show labels on the X axis or not. Defaults to 1; set to '0' if you want to turn them off.

stagger_x_labels()

This puts the labels at alternative levels so that if they're long field names they won't overlap so easily. Default is '0'; to turn on, set to '1'.

rotate_x_labels()

This turns the X axis labels by 90 degrees. Default is '0'; to turn on, set to '1'.

show_y_labels()

Whether to show labels on the Y axis or not. Defaults to 1; set to '0' if you want to turn them off.

scale_integers()

Ensures only whole numbers are used as the scale divisions. Default is '0'; to turn on, set to '1'. This has no effect if scale divisions are less than 1.

show_secondary_y_labels()

Whether to show labels on the right hand side Y axis or not. Defaults to 1; set to '0' if you want to turn them off.

min_scale_value()

The point at which the Y axis starts. Defaults to '0'; if set to '' it will default to the minimum data value.

scale_divisions()

This defines the gap between markers on the Y axis. Default is a 10th of the max_value — e.g. you'll have 10 markers on the Y axis.

🚨 NOTE: do not set this too low — you are limited to 999 markers, and after that the graph won't generate. no cap.

show_x_title()

Whether to show the title under the X axis labels. Default is 0; set to '1' to show.

x_title()

What the title under the X axis should be, e.g. 'Months'.

show_y_title()

Whether to show the title on the left hand side Y axis. Default is 0; set to '1' to show.

show_secondary_y_title()

Whether to show the title on the right hand side Y axis. Default is 0; set to '1' to show.

y_title_text_direction()

Aligns writing mode for the Y axis label. Defaults to 'bt' (Bottom to Top). Change to 'tb' (Top to Bottom) to reverse. 🔄

secondary_y_title_text_direction()

Aligns writing mode for the right hand Y axis label. Defaults to 'bt' (Bottom to Top). Change to 'tb' (Top to Bottom) to reverse. 🔄

y_title()

What the title under the Y axis should be, e.g. 'Sales in thousands'.

secondary_y_title()

What the title on the right hand side Y axis should be, e.g. 'Number of deals'.

show_graph_title()

Whether to show a title on the graph. Defaults to 0; set to '1' to show.

graph_title()

What the title on the graph should be.

show_graph_subtitle()

Whether to show a subtitle on the graph. Defaults to 0; set to '1' to show.

graph_subtitle()

What the subtitle on the graph should be.

key()

Whether to show a key. Defaults to 0; set to '1' if you want to show it. 🔑

key_position()

Where the key should be positioned. Defaults to 'right'; set to 'bottom' if you want to move it.

x_label_formatter ()

A callback subroutine which will format a label on the x axis. For example:

$graph->x_label_formatter( sub { return '$' . $_[0] } );

y_label_formatter()

A callback subroutine which will format a label on the y axis. For example:

$graph->y_label_formatter( sub { return '$' . $_[0] } );

show_path_title()

Whether to add the title attribute to the data path tags, which will show "tooltips" when hovering over the bar area. 🖱️✨

show_title_fields()

Whether to show field values as title elements in path tag. Defaults to 0; set to '1' to turn on. Suggest on single add_data graphs — for overlapping graphs leave off to see the title value used in the add_data call. 💡

---

🌈 EXAMPLES 🌈

For examples, look at the project home page: http://leo.cuckoo.org/projects/SVG-TT-Graph/

---

🌸 EXPORT 🌸

None by default. (we keep it lowkey. 🙈)

---

⭐ SEE ALSO ⭐

SVG::TT::Graph, SVG::TT::Graph::Line, SVG::TT::Graph::Bar, SVG::TT::Graph::BarHorizontal, SVG::TT::Graph::Pie, SVG::TT::Graph::TimeSeries, SVG::TT::Graph::XY, Compress::Zlib, XML::Tidy

---

and that's the whole page, bestie 💖 this one came from perl v5.36.0, dated 2022-11-19, and it's part of the User Contributed Perl Documentation — so go forth, build your bar-line graphs, and slay. periodt. 👑🦋💅