NAME

SVG::Timeline - Create SVG timeline charts

SYNOPSIS

    use SVG::Timeline;

    my $tl = SVG::Timeline->new;

    $tl->add_event({
      start => 1914,
      end   => 1918,
      text  => 'World War I',
    });

    $tl->add_event({
      start => '1939-09-01', # 1 Sep 1939
      end   => '1945-05-08', # 8 May 1945
      text  => 'World War II',
    });

    print $tl->draw;

DESCRIPTION

This module allows you to easily create SVG documents that represent timelines.

An SVG timeline is a diagram with a list of years across the top and a number of bars below. Each bar represents a period of time.

METHODS

new(\%options)

Creates and returns a new SVG::Timeline object.

Takes an optional hash reference containing configuration options. You probably don't need any of these, but the following options are supported:

• events - a reference to an array containing events. Events are hash references. See add_event below for the format of events.

• width - the width of the output in any format used by SVG. The default is 100%.

• height - the height of the output in any format used by SVG. The default is 100%.

• aspect_ratio - the default is 16/9.

• viewport - a viewport definition (which is a space separated list of four integers. Unless you know what you're doing, it's probably best to leave the class to work this out for you.

• svg - an instance of the SVG class that is used to generate the final SVG output. Unless you're using a subclass of this class for some reason, there is no reason to set this manually.

• default_colour - the colour that is used to fill the timeline blocks. This should be defined in the RGB format used by SVG. For example, red would be 'RGB(255,0,0)'.

• years_per_grid - the number of years between vertical grid lines in the output. The default of 10 should be fine unless your timeline covers a really long timespan.

• bar_height - the height of an individual timeline bar.

• bar_spacing - the height if the vertical space between bars (expresssed as a decimal fraction of the bar height).

• decade_line_colour - the colour of the grid lines.

• bar_outline_colour - the colour that is used for the outline of the timeline bars.

events_in_timeline

The number of events that we need to make space for in the timeline. This is generally just the number of events that we have added to the timeline, but this method is here in case subclasses want t odo something different.

add_event

Takes a hash reference with event details and adds an SVG::Timeline::Event to the timeline. The following details are supported:

• text - the name of the event that is displayed on the bar. This is required.

• start - the start year of the event. It is a string of format YYYY-MM-DD. For example, 2017-07-02 is the 2nd of July 2017. The month and day can be omitted (in which case they are replaced with '01').

• end - the end year of the event, requirements are the same as that of start.

• colour - the colour that is used to fill the timeline block. This should be defined in the RGB format used by SVG. For example, red would be 'RGB(255,0,0)'. This is optional. If not provided, the default_color is used.

calculated_height

The height of the timeline in "calculated units".

calculated_width

The width in "calulated units".

units_per_year

The number of horizontal units that each year should take up.

draw_grid

Method to draw the underlying grid.

draw

Method to draw the timeline.

min_year

Returns the minimum year from all the events in the timeline.

max_year

Returns the maximum year from all the events in the timeline.

years

The number of years that all the events in the timeline span.

AUTHOR

Dave Cross <dave@perlhacks.com>

COPYRIGHT AND LICENCE

Copyright (c) 2017, Magnum Solutions Ltd. All Rights Reserved.

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

cpanm SVG::Timeline

perl -MCPAN -e shell
install SVG::Timeline