/ 
Graph-Timeline-1.3
River stage zero No dependents
/ Graph::Timeline

NAME

Graph::Timeline - Render timeline data

VERSION

This document refers to verion 1.3 of Graph::Timeline, released June 17, 2007

SYNOPSIS

This class takes a list of events and processes them so that they can be rendered in various graphical formats by subclasses of this class.

DESCRIPTION

Overview

The purpose of this class is to organise the data that will be used to render a timeline. Events fall into two types. Intervals, which has a start and an end. For example Albert Einstein was born on 1879/03/14 and died on 1955/04/18, this would be stored as an interval. His works were publicly burned by the Nazi's on 1933/05/10 for being 'of un-German spirit', I guess being Jewish didn't help either. So this event would be marked as a point.

You feed events into the class using add_interval( ) and add_point( ), then use window( ) to select which events you want to render and then call data( ) to get the relevant events. This last bit will be done in the subclass.

Constructors and initialisation

new( )

The constructor takes no arguments and just initialises a few basic variables.

Public methods

add_interval( HASH )

Inserts an event that has a start and an end point into the list at the corrct position. The hash contains the following keys, some of which are required.

start [ REQUIRED ]

The start date for the interval in the for 'YYYY/MM/DD' or the word 'present' which will be converted into todays date. Dates in the format YYYY will be taken to span YYYY/01/01 until YYYY/12/31 and dates of the format YYYY/MM will span YYYY/MM/01 until YYYY/MM/xx where xx is the last day of MM in YYYY.

end [ REQUIRED ]

The start end for the interval in the for 'YYYY/MM/DD' or the word 'present' which will be converted into todays date. Dates in the format YYYY will be taken to span YYYY/01/01 until YYYY/12/31 and dates of the format YYYY/MM will span YYYY/MM/01 until YYYY/MM/xx where xx is the last day of MM in YYYY.

label [ REQUIRED ]

The text string that will be displayed when the event is rendered

id [ OPTIONAL ]

A unique id for the render, Graph::Timeline does not validate this field for uniqueness

group [ OPTIONAL ]

A string is used to group related events together, Graph::Timeline does not validate this field

add_point( HASH )

The same as add_interval( ) except that the event occurs on just one day and therefore does not require an end date. Interval and point events are rendered differently.

window( HASH )

Set up the data to be selected from the event pool. To reset the defaults just call without any parameters.

start

Select only record that start on or after this date. Takes a valid date or the word 'present' which is translated to the current date.

end

Select only record that end on or before this date. Takes a valid date or the word 'present' which is translated to the current date.

start_in

If end is set then include records that start before the end date but ends after the end date.

end_in

If start is set then include records that start before the start date but end after the start date.

span

If start and end are both set then additionally report events that start before the start date and end after the end date.

callback

A code reference to provide additionaly custom filtering. The callback will be passed a hash reference with the following keys: start, end, label, group, id and type ('interval' and 'point').

data( )

This returns a list of the events from the pool that got passed the parameters from the window( ) method.

Private methods

_add_to_pool

Used to add the event into the pool which is sorted by start date

_valid_keys

Validate that the keys supplied in the hash are valid

_date_valid

Validate a date

_required_keys

Check that the required keys have been supplied in the hash

_lowercase_keys

Lowercase the keys in a hash

_today

Return todays date for use with the 'present' word

_set_range

Set the xxx_start and xxx_end values from the xxx data

ENVIRONMENT

None

DIAGNOSTICS

Timeline->new() takes no arguments

When the constructor is initialised it requires no arguments. This message is given if some arguments were supplied.

Timeline->add_interval() expected HASH as parameter

The parameter is a hash describing an event

Timeline->add_point() expected HASH as parameter

The parameter is a hash describing an event

Timeline->window() 'span' can only be defined with a 'start' and 'end'

To define 'span' then you must also define 'start' and 'end'

Timeline->window() 'callback' can only be a CODE reference

You must pass a code reference for the callback

Timeline->data() takes no arguments

When the method is called it requires no arguments. This message is given if some arguments were supplied.

Timeline->add_interval() invalid key '...' passed as data

The only valid keys are 'start', 'end', 'label', 'group' and 'id'. Something else was supplied.

Timeline->add_interval() invalid date for '...'

The date supplied for '...' is invalid

Timeline->add_interval() 'start' and 'end' are in the wrong order

The values for 'start' and 'end' are in the wrong order

Timeline->add_interval() missing key '...'

A required key was not supplied. Required keys are 'start', 'end' and 'label'

Timeline->add_point() invalid key '...' passed as data

The only valid keys are 'start', 'label', 'group' and 'id'. Something else was supplied.

Timeline->add_point() invalid date for '...'

The date supplied for '...' is invalid

Timeline->add_point() missing key '...'

A required key was not supplied. Required keys are 'start' and 'label'

Timeline->window() invalid key '...' passed as data

The only valid keys are 'start', 'end', 'start_in', 'end_in', 'span' and 'callback'. Something else was supplied.

Timeline->window() invalid date for '...'

The date supplied for '...' is invalid

Timeline->window() 'start' and 'end' are in the wrong order

The values for 'start' and 'end' are in the wrong order

BUGS

None

FILES

See the Timeline.t file in the test directory

SEE ALSO

Graph::Timeline::GD - Use GD to render the timeline

AUTHORS

Peter Hickman (peterhi@ntlworld.com)

COPYRIGHT

Copyright (c) 2003, Peter Hickman. All rights reserved.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.