AnnotatedTimeline
=================

AnnotatedTimeline is a Rails plugin that wraps up the for the Annotated Timeline widget from the Google Visualization 
API (http://code.google.com/apis/visualization/documentation/gallery/annotatedtimeline.html)

=== Usage: 

In your controller:

    @data = {
      1.day.ago => { :foo=>123, :bar=>100 },
      2.day.ago => { :foo=>345, :bar=>200 }  
    }

The graph accepts either daily or hourly data. It will attempt to auto detect what type of data it is given by checking 
the time difference between the first two keys.

Your keys should either be Dates or Times, but not a mix of both types.

In the view:

    <%= inline_annotated_timeline @data, width, height, 'div_id_to_create', options %>

OR

    <script type="text/javascript" src="http://www.google.com/jsapi"></script>  
    ...
    <%= annotated_timeline @data, 'div-id', options %>
    ...
    <div id='div-id' style='width: 600px; height: 400px'></div>

  This will create a graph of "foo" & "bar" vs time.  It will be placed in a div with ID 'div-name'.

Using inline_annotated_timeline inserts google javascript include and the graph where you put it, whereas 
annotated_timeline requires you to make the <div> where you want the graph, and include the google javascript somewhere, 
and allows you to manipulate the div more. Note that if you are putting several graphs on a page, it is more efficient 
not to use the inline function, because if you use the inline function several times, it calls the javascript from 
google several times.


=== Annotations

In your controller:

    @data = {
      1.day.ago.to_date => { :foo=>123, :bar=>100 },
      2.day.ago.to_date => { :foo=>345, :bar=>200 }  
    }
    @annotations = {
      :foo => { 1.day.ago.to_date => ["yesterday", "all my troubles seemed so far away"]}
      :bar => { 1.day.ago.to_date => ["last tuesday"], 2.days.ago.to_date => ["last monday"]}
    }

Sending arrays of strings with two elements will render the first element as the title and the second as the text, and 
sending a one element array will render just the title.

Now, in the view, the variable @annotations be passed in as option :annotations, with any other options in the hash. For 
example:

    <%= inline_annotated_timeline @data, 500, 200, 'graph', {:annotations => @annotations, :displayExactValues => true} 
    %>
    
If you use Time values for your keys, make sure that you use the exact same timestamps in the annotations array. You can 
avoid having to do this by using Date values.

  


=== Options

  :allowHtml (boolean) - If set to true, any annotation text that includes HTML tags will be rendered as HTML. Defaults 
  false

  :allValuesSuffix (string) - A suffix to be added to all values in the scales and the legend. Defaults blank (no 
  suffix.)

  :annotations - see above

  :timeZone - (string) An optional timezone which is used when generating Javascript datetimes for hourly timelines. 
  This is useful when your keys are in a timezone different from your UI timezone. For example, your data set can be 
  indexed with UTC datetimes, but the timeline would display EST datetimes. Set this to a timezone string suitable for 
  passing to ActiveSupport::CoreExtensions::Time::Zones#in_time_zone. This requires ActiveSupport 2.1.0 or higher.
  
  :annotationsWidth (number) - If specified, sets the percentage of the width of the display that the annotations column 
  takes up. Defaults to 25, must be between 5 and 80. 

  :colors (array of strings) - The colors to use to override the default google color scheme for the chart lines and 
  labels. Each element is a string in a valid HTML color format. For example 'red' or '#00cc00'. 

  :displayAnnotationsFilter (boolean) - If set true, a search box appears at the top of the annotations column that will 
  filter the annotations according to its contents. Defaults to false.

  :displayExactValues (boolean) - If set to false (the default), value displayed on top may be in a shorter approximated 
  form (56.12k instead of 56123.45). If set to true, values will appear unchanged.

  :displayZoomButtons (boolean) - If false, the zoom buttons in the top left corner are disabled. Defaults true.

  :legendPosition (string) - Whether to put the colored legend on the same row (default) with the zoom buttons and the 
  date ('sameRow'), or on a new row ('newRow'). 

  :min (number) - Use to explicitly set the minimal value to show in the Y axis.

  :scaleColumns (array of numbers) - Specifies which data series are to be used for each of the scales on the chart. The 
  chart can display up to three scales. If only one series is specified, the scale will be displayed to the right of the 
  chart. If two series are specified, the first scale will be displayed to the left, and the second to the right of the 
  chart. If three series are specified, the first to the left, the second to the right, and the third in the middle of 
  the chart. When displaying more than one scale, it is advisable to set scaleType either to 'allfixed' or 
  'allmaximize'. All of the values are optional, and if an empty array is specified the chart will show no scale. If 
  more than three values are specified, the rest are ignored. If this value is not specified at all, only the first data 
  series scale is displayed on the right. scaleColumns parameter is an array of numbers, in which 0 refers to the first 
  data series, 1 to the second, and so on.

  :scaleType (string) - 'fixed', 'maximize', 'allfixed' or 'allmaximize'. If 'maximize' is used, the range of the values 
  axis will span between the minimal and maximal values of the DataTable. If 'fixed' is used, the range of the values 
  axis will span between zero and the maximal values of the DataTable. 'allfixed' and 'allmaximize' do the same, 
  individually for each series. This means that the scale of each series is calculated based on its values only, and not 
  based on all values from all series. When 'allfixed' or 'allmaximize' are used, it makes sense to set the scaleColumns 
  option as well, otherwise some of the series will be displayed in a scale that is not the displayed one.

  :wmode (string) - 'opaque'(default), 'window' or 'transparent'. the Window Mode (wmode) parameter for the Flash chart. 
  

  :zoomStartTime (date) -    If specified, sets the start date of the selected zoom range. 

  :zoomEndTime (date) -  If specified, sets the end date of the selected zoom range.

You may notice that with the exception of annotations and timeZone, all of these options are taken directly from the 
options in Google's API. Any new option implemented by the Google API that takes a string, boolean, number, or array as 
an argument should work implicitly as per examples above.


===License:

* MIT License


(C) Mobile Commons 2008