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.

The actual charts are drawn via JavaScript using morris.js relying on Raphaël and JQuery.

Installation

Step 1: Install and include the gem

Set the constant PATH_TO_JEKYLL_SITE correctly and execute these commands accordingly:

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:

1. Install the plugin by running gem install jekyll_date_chart
2. Add the line require 'jekyll_date_chart' to _plugins/ext.rb

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:

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.

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:

{% stylesheet morris.css %}

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

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

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

<!- JQuery library -!>

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

<!- custom JavaScript -!>

Usage

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

{% 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 %}

Valid Operators

• = sets the balance to the provided value.
• + adds the provided value to the previous balance.
• - subtracts the provided value from the previous balance.

Notes

1. 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.
2. 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.

Restrictions

1. 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).
2. 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.
3. 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.

Further examples

This article shows basic tables with actual charts.

Features

Notes from Planned improvements move here once implemented.

1. A line representing the total (sum) for any date is generated.
2. All tables within a block are considered when calculating the total.
3. Data of multiple tables within a block is merged into one chart.

Planned Improvements

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

Reliability

1. Tables starting with a plus or minus entry should assume a starting value of 0
2. Convert ykeys to lower case strings with only letters, numbers and hyphens (“labels” should still use the unmodified variant)
3. Support advanced Textile markup (by ignoring it)
4. Ensure unique CSS id in generated DIV
5. Extract inline style definition from generated DIV
6. Add warning when the signifacation of a value is assumed
   • Any value without algebraic sign is currently treated as addition.
7. Allow additional date formats (see Restrictions above)
8. Consider both, dots and commas, as decimal marks (see Restrictions above)
9. Accept whitespaces and underscores in numbers (see Restrictions above)

Functionality

1. Make calculation of total optional, but keep it as default
2. Add Textile styling for pretty-formatting values (e.g. align right via |>. foo|)
3. Allow user to select target CSS id for the chart
4. Add visibility setting for the source table
5. 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
6. Put data-entries directly into rendered table element
7. Add support for multiple-currencies within one chart by converting to a specified target currency
   • Optionally use Open Exchange Rates (money-open-exchange-rates, open_exchange_rates)
   • Optionally use historical rate for every date in the timeline
8. Allow creation of a chart summing up all totals of all tables within a page (possibly in pure JavaScript)

License

Jekyll Date Chart is released under the MIT License.