SVG::T...ph::Pie(3pm)

💖 SVG::TT::Graph::Pie — manual page, bestie edition 💖

okay so the actual official title up top is SVG::T...ph::Pie(3pm) and it lives under User Contributed Perl Documentation, but we're not reading that boring line together, we're diving straight in 🫶

---

✨ NAME ✨

SVG::TT::Graph::Pie — bestie, it creates presentation quality SVG pie graphs, easily. That's the whole vibe. 🥧

---

🎀 SYNOPSIS 🎀

use SVG::TT::Graph::Pie;

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

my $graph = SVG::TT::Graph::Pie->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();

look at that flow. setup, data, burn, done. 💅

---

🌈 DESCRIPTION 🌈

This object exists so you can easily create high quality SVG pie graphs, no cap. You can either use the default style sheet or supply your own — either way there are so many options you can configure to get control over how the graph is generated, with or without a key, display percent on the pie chart, title, subtitle, etc. it's giving ✨ customisation ✨

---

💅 METHODS 💅

new()

use SVG::TT::Graph::Pie;

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

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

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

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

  'show_shadow'             => 1,
  'shadow_size'             => 1,
  'shadow_offset'           => 15,

  'key_placement'           => 'R',

  # data by pie chart wedges:
  'show_data_labels'        => 0,
  'show_actual_values'      => 0,
  'show_percent'            => 1,
  'rollover_values'         => 0,
  'show_path_title'         => 0,
  'show_title_fields'       => 0,

  # data on key:
  'show_key_data_labels'    => 1,
  'show_key_actual_values'  => 1,
  'show_key_percent'        => 0,

  'expanded'                => 0,
  'expand_greatest'         => 0,

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

});

The constructor takes a hash reference. fields (the name for each slice on the pie) MUST be set, everything else defaults to those values above — except style_sheet, which defaults to using the internal style sheet. got it? 🫡

add_data()

my @data_sales_02 = qw(12 45 21);

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

This method lets you add data to the graph object. heads up bestie: only the first data set added will be used! 👀

clear_data()

my $graph->clear_data();

This removes all data from the object so you can reuse it to create a new graph, but with the same config options. recycle era ♻️

burn()

print $graph->burn();

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

⚠️ This method will croak unless at least one data set has been added to the graph object. so like, add your data first fr fr.

config methods

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

Here's the full list of methods available to change the config of the graph object after it's been created. no skipping, we're doing all of them 💖

height()

Set the height of the graph box. this is the total height of the SVG box created — not the graph itself, which auto scales to fix the space. 🦋

width()

Set the width of the graph box. this is the total width of the SVG box created — not the graph itself, which auto scales to fix 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. iconic tbh.

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 and copy the stylesheet section to an external file and edit from there. DIY queen 👑

random_colors()

Use random colors in the internal stylesheet. chaos but make it pretty 🌈

style_sheet_field_names()

If you use the style_sheet_field_names() option then you can use the field names within your stylesheet. This allows consistent use of styles. The names should be:

<field>_dataPoint
<field>_key

show_graph_title()

Whether to show a title on the graph, default is '0'.

graph_title()

What the title on the graph should be.

show_graph_subtitle()

Whether to show a subtitle on the graph, default is '0'.

graph_subtitle()

What the subtitle on the graph should be.

show_shadow()

Turn the shadow on and off, defaults to '1', set to '0' if you don't want it. It is automatically turned off if you extract one section of the pie. spooky auto-behaviour, noted 📝

shadow_size()

Size of the shadow if shown, measured as percentage of pie chart radius, default of 1 being the same size as the pie.

shadow_offset()

Offset (in pixels) of shadow to bottom-right in relation to the center of the pie chart.

key()

Whether to show a key, defaults to 0, set to '1' if you want to show it.

key_placement()

Defaults to 'R' — right, can be 'R', 'L', 'T' or 'B'.

show_data_labels()

Show label on pie chart, defaults to '0', can be set to '1'.

show_actual_values()

Show values on pie chart, defaults to '0', can be set to '1'.

show_percent()

Show percent (rounded) on the pie chart, defaults to '1', can be set to '0'.

rollover_values()

Shows data field and value when the mouse is over a piechart wedge. hover girlies rise 🙌

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.

show_key_data_labels()

Show label on the key, defaults to '1', can be set to '0'.

show_key_actual_values()

Show value on the key, defaults to '1', can be set to '0'.

show_key_percent()

Show percent (rounded) on the key, defaults to '0', can be set to '1'.

expanded()

All slices of pie are exploded out, defaults to '0'. Do not set to '1' if you are going to use expanded_greatest(). pick a lane bestie 🚫

expand_greatest()

The largest slice of pie is exploded out from the pie, defaults to '0'. Useful if you are only showing the percentages (which are rounded) but still want to visually show which slice was largest. main character slice energy 👑

Do not set to '1' if you are going to use expanded().

---

🌸 EXAMPLES 🌸

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

go peek, it's worth it 💖

---

🦋 EXPORT 🦋

None by default. yeah, nothing. empty. as intended 😌

---

⭐ SEE ALSO ⭐

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

the whole graph fam 🫶

---

and that's a wrap bestie!! 🎀 this page was served to you by perl v5.36.0, dated 2022-11-19, under the title SVG::T...ph::Pie(3pm). go forth and make gorgeous pie charts, you absolute legend 💅✨