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

💖 NAME 💖

SVG::TT::Graph::BarHorizontal — bestie, it makes presentation quality SVG horizontal bar graphs easily. Yes the manual page is technically called SVG::T...izontal(3pm) because someone at the terminal was being dramatic with the truncation, but the real one is SVG::TT::Graph::BarHorizontal(3pm) and she's iconic. 🎀

---

✨ SYNOPSIS ✨

Okay so here's the whole vibe in one go:

use SVG::TT::Graph::BarHorizontal;

my @fields = qw(Jan Feb Mar);
my @data_sales_02 = qw(12 45 21);

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

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

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

That's it. That's the whole thing. Slay. 💅

---

🌸 DESCRIPTION 🌸

So the entire point of this object is to let you make high quality SVG horizontal bar graphs without losing your mind. (The original page spells it "horitonzal" and honestly? we're keeping her little typo energy, she's doing her best 🥺.)

You can roll with the default style sheet, or you can hand over your own. Either way there are so many options you can configure — no cap — so you get real control over how the graph comes out. With or without a key. Data elements at each point. Title, subtitle, etc. It's giving ✨customizable✨.

---

👑 METHODS 👑

🌈 new()

use SVG::TT::Graph::BarHorizontal;

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

my $graph = SVG::TT::Graph::BarHorizontal->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,
  'show_y_labels'          => 1,
  'scale_integers'         => 0,
  '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,
  'y_title_text_direction' => 'bt',
  'y_title'                => 'Y Scale',

  '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,
});

The constructor takes a hash reference. And listen — only fields (the names for each field on the X axis) MUST be set. Literally everything else gets defaulted to what you see up there ☝️ — with one tiny exception: style_sheet defaults to using the internal style sheet instead. 🫶

---

🦋 add_data()

my @data_sales_02 = qw(12 45 21);

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

This is how you actually feed data into your graph object. You can call it several times to stack more data sets in there… but fr fr, the likelihood is you should be using SVG::TT::Graph::Line instead, because it won't look great! 😭 Stacking bars on a bar chart? Ma'am. No.

---

🍓 clear_data()

my $graph->clear_data();

Wipes all the data off the object so you can reuse it to build a whole new graph while keeping the exact same config options. Recycle era. ♻️✨

---

💜 burn()

print $graph->burn();

This processes the template with all 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 SVG, no mercy. 💀

---

🎀 config methods 🎀

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

Here's the whole list of methods you can use to change the config of the graph object after it's already been created. Get in, we're customizing. 💅

⭐ height()

Sets the height of the graph box. 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. Don't get it twisted.

⭐ width()

Sets the width of the graph box. Same deal: this is the total width of the SVG box that gets 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.

Set to "inline:<style>...</style>" with your CSS in between the tags. That way you can override the default style without requiring an external URL. Genius tbh.

The default stylesheet handles up to 12 data sets. All data series over the 12th will have no style and be in black. So if you have over 12 data sets you can either 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. Your call, main character. 👑

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

⭐ random_colors()

Use random colors in the internal stylesheet. 🌈 Surprise! Every time!

⭐ show_data_values()

Show the value of each element of data on the graph. Numbers on display, as they should be. ✨

⭐ bar_gap()

Whether to have a gap between the bars or not. Default is '1'; set to '0' if you don't want gaps. Bars touching = chaotic, bars apart = curated. Your choice. 🫶

⭐ 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 instead.

⭐ 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 if they're long field names they won't overlap so easily. Default is '0'; to turn on, set to '1'. The way that long labels just… stop fighting each other? Obsessed. 😌

⭐ 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'. Heads up: this has no effect if scale divisions are less than 1. 🙈

⭐ scale_divisions()

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

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

⭐ 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 under the Y axis labels. Default is 0; set to '1' to show.

⭐ y_title_text_direction()

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

⭐ y_title()

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

⭐ show_graph_title()

Whether to show a title on the graph. Default is 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. Default is 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. Hover girlies, this one's for you. 🖱️✨

⭐ show_title_fields()

Whether to show field values as title elements in the path tag. Defaults to 0; set to '1' to turn on. Suggestion: turn it on for single add_data graphs, and for overlapping graphs leave it off so you can see the title value used in the add_data call. Iykyk. 💅

---

🧚 EXAMPLES 🧚

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

(That's the whole section. Go look. She's got examples. 🦋)

---

🌈 EXPORT 🌈

None by default.

Translation: she gives you nothing for free, bestie. You want it, you call it explicitly. 💀

---

🫶 SEE ALSO 🫶

Go be nosy, there's a whole friend group:

• SVG::TT::Graph
• SVG::TT::Graph::Line
• SVG::TT::Graph::Bar
• SVG::TT::Graph::BarLine
• SVG::TT::Graph::Pie
• SVG::TT::Graph::TimeSeries
• SVG::TT::Graph::XY
• Compress::Zlib
• XML::Tidy

---

Okay that's the whole page, you made it, I'm so proud of you 🥹💜 This was perl v5.36.0, dated 2022-11-19, straight out of the SVG::T...izontal(3pm) era — go make some horizontal bar graphs and absolutely ate. Byeee! ✨🎀💖