h1. Jekyll Date Chart

This Jekyll plugin renders date-related line charts based on textile-formatted tables.

While the plugin focuses on the presentation of financial data, it may also be used to display other date-related statistics.

!screenshots/jekyll_date_chart.png(Example chart generated via Jekyll Date Chart)!

The actual charts are drawn via JavaScript using "morris.js(morris.js - good-looking charts shouldn't be difficult)":http://www.oesmith.co.uk/morris.js/ relying on "Raphaël(Raphaël - JavaScript library for simplified work with vector graphics)":http://raphaeljs.com/ and "JQuery(JQuery - write less, do more)":http://jquery.com/.

h2. Installation

h3. Step 1: Install and include the gem

Set the constant @PATH_TO_JEKYLL_SITE@ correctly and execute these commands accordingly:

pre. cd $PATH_TO_JEKYLL_SITE echo "gem 'jekyll_date_chart'" >> Gemfile bundle echo "require 'jekyll_date_chart'" >> _plugins/ext.rb

Alternatively you may accomplish the same without @echo@ and @bundle@:

Install the plugin by running @gem install jekyll_date_chart@

Add the line @require 'jekyll_date_chart'@ to _plugins/ext.rb

h3. Step 2: Generate the required JavaScript libraries

For convenience, Jekyll Date Chart ships Raphaël and morris.js.

In order to copy these two libraries, execute the newly available @jekyll_date_chart@ command from within the project directory:

pre. cd $PATH_TO_JEKYLL_SITE jekyll_date_chart generate

Note: As JQuery is commonly used in many projects, it has to be manually installed if currently missing.

h3. Step 3: Include the morris.js CSS in the HTML template

Ensure that the file @morris.css@ is properly loaded by adding the following statement to the head element of the HTML template:

pre. {% stylesheet morris.css %}

Based on your setup you may want to use the minified version morris.min.css instead.

h3. Step 4: Include all required JavaScript libraries in the HTML template

Typically just before your closing HTML body tag (@@), add the according lines:

pre.. <!- JQuery library -!>

<!- Jekyll Date Chart related libraries and JavaScript -!> {% javascript raphael %} {% javascript morris %} {% javascript jekyll_date_chart.js %}

<!- custom JavaScript -!>

h2. Usage

To generate a chart, enclose one or more textile-style tables in a @dchart@ block:

pre.. {% dchart %} | title of first table | Unit of given values | comments on the table as a whole | | 09.09.2013 | =1000 | comment on this specific element | | 10.10.2013 | =+1000 | comment on this specific element | | 11.11.2013 | +1000 | comment on this specific element |

| title of second table | Unit of given values | comments on the table as a whole | | 09.09.2013 | =-2000 | comment on this specific element | | 10.10.2013 | =2000 | comment on this specific element | | 12.12.2013 | -2000 | comment on this specific element | {% enddchart %}

h3. Valid Operators

• @=@ (re)sets the balance to the provided value.
• @+@ adds the provided value to the previous balance.
• @-@ subtracts the provided value from the previous balance.

h3. Notes

Multiple tables within the same block will result in graphs being drawn to the same chart.

** For drawing to different charts, simply use additional blocks. ** If Jekyll Date Chart fails to parse the content of the first column to a date, the beginning of a new table is assumed.

All units within one block have to match in order to have the build succeed.

** This is intended behaviour which serves as basic validation. The case may later be coped with by converting to common units.

h3. Restrictions

Currently only @DD.MM.YYYY@ is accepted as date format.

** Future versions are planned to accept other separators and formats (e.g. @YYYY/DD/MM@).

Any dot @.@ in the second column is currently ignored while commas @,@ act as decimal points.

** Future versions will likely consider both, dots and commas, as decimal marks while allowing spaces and underscores @_@ for digit grouping.

Special Textile-directives in the tables (e.g. @|_. foo|@ are currently unsupported and will most likely crash Jekyll Date Chart or lead to undesired behaviour.

** This will be addressed in future versions.

h3. Further examples

"This article(Groovy Skills International - Bye, Bye Spreadsheet. Hi, Jekyll Date Chart!)":http://groovy-skills.com/jekyll/2013/10/10/bye-bye-spreadsheet-hi-jekyll-date-chart/ shows basic tables with actual charts.

h2. Features

Notes from Planned improvements move here once implemented.

A line representing the total (sum) for any date is generated.

All tables within a block are considered when calculating the total.

Data of multiple tables within a block is merged into one chart.

h2. Planned Improvements

"The following list outlines ideas for improvements in descending order of subjectively perceived importance."

h3. Reliability

Tables starting with a plus or minus entry should assume a starting value of 0

Convert ykeys to lower case strings with only letters, numbers and hyphens ("labels" should still use the unmodified variant)

Support advanced Textile markup (by ignoring it)

Ensure unique CSS id in generated DIV

Extract inline style definition from generated DIV

Add warning when the signifacation of a value is assumed

** Any value without algebraic sign is currently treated as addition.

Allow additional date formats (see Restrictions above)

Consider both, dots and commas, as decimal marks (see Restrictions above)

Accept whitespaces and underscores in numbers (see Restrictions above)

h3. Functionality

Make calculation of total optional, but keep it as default

Add Textile styling for pretty-formatting values (e.g. align right via @|>. foo|@)

Allow user to select target CSS id for the chart

Add visibility setting for the source table

Optionally add last common (or todays) value for each graph in order to terminate at the same point and allow final calculation of total variable

Put data-entries directly into rendered table element

Add support for multiple-currencies within one chart by converting to a specified target currency

** Optionally use Open Exchange Rates ("money-open-exchange-rates":https://rubygems.org/gems/money-open-exchange-rates, "open_exchange_rates":https://rubygems.org/gems/open_exchange_rates) ** Optionally use historical rate for every date in the timeline

Allow creation of a chart summing up all totals of all tables within a page (possibly in pure JavaScript)

h2. License

Jekyll Date Chart is released under the "MIT License":http://www.opensource.org/licenses/MIT.