====== Sparkline Plugin ======

---- plugin ----
description: Enables display of sparkline graphs
author     : Riny Heijdendael
email      : riny@bk.ru
type       : syntax
lastupdate : 2005-08-04
compatible : 
depends    : 
conflicts  : 
similar    : 
tags       : media, images, diagram, chart
----

===== Description =====

With this [[plugins|plugin]] the [[:syntax]] of [[:DokuWiki]] is extended to allow the creation of sparklines of comma separated values. 

Sparklines are tiny images appearing in texts, expressing trends. To see more examples take a look at http://sparkline.org ...could generate: [[http://www.sparkline.org/images/deficit.png]]

The syntax to use this plugin is:

  {{spark>value1,value2,value3}}

Optionally, you can specify a title:

  {{spark>value1,value2,value3|title}}

You can have the generated image left, center or right aligned:

  * ''%%{{spark>value1,value2,value3 }}%%'' -> left aligned
  * ''%%{{spark> value1,value2,value3 }}%%'' -> centered
  * ''%%{{spark> value1,value2,value3}}%%'' -> right aligned

===== Plugin =====

The plugin uses some classes from http://www.sparkline.org.

To install the plugin create the directory ''/lib/plugins/sparkline/'' in your DokuWiki directory.

Put the following PHP file in ''/lib/plugins/sparkline/syntax.php''.

<code php>
<?php
/**
 * Sparkline Plugin: enables sparklines with syntax {{spark>text}}
 * 
 * Uses the Sparkline PHP Graphing Library http://sparkline.org
 * Copyright 2004 James Byers <jbyers@users.sf.net>
 * Plugin code based on gravatar plugin of Esther Brunner <esther@kaffeehaus@ch>
 * 
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Riny Heijdendael
 */
 
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_sparkline extends DokuWiki_Syntax_Plugin {
 
    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Riny Heijdendael',
            'email'  => '?',
            'date'   => '2005-08-04',
            'name'   => 'Sparkline Plugin',
            'desc'   => 'Creates sparkline from numeric data separated by ,',
            'url'    => 'http://www.dokuwiki.org/plugin:sparkline',
        );
    }
 
    /**
     * What kind of syntax are we?
     */
    function getType(){
        return 'substition';
    }
 
    /**
     * Where to sort in?
     */
    function getSort(){
        return 316;
    }
     
    /**
     * Connect pattern to lexer
     */
    function connectTo($mode) {
      $this->Lexer->addSpecialPattern("{{spark>.+?}}",$mode,'plugin_sparkline');
    }
 
    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
        $match = substr($match,8,-2);          // Strip markup
        $match = preg_split('/\|/u',$match,2); // Split title from URL
 
        // Check alignment
        $ralign = (bool)preg_match('/^ /',$match[0]);
        $lalign = (bool)preg_match('/ $/',$match[0]);
        if ($lalign & $ralign) $align = 'center';
        else if ($ralign)      $align = 'right';
        else if ($lalign)      $align = 'left';
        else                   $align = NULL;
 
        return array(trim($match[0]),trim($match[1]),$align);
    }            
 
    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
        if($mode == 'xhtml'){
            $spark_url = DOKU_BASE.'lib/plugins/sparkline/spark.php?data='.urlencode($data[0]);
            $title = ($data[1] ? $renderer->_xmlEntities($data[1]) : '');
            
            $renderer->doc .= '<img src="'.$spark_url.'" class="media'.$data[2].'"'.
                ' title="'.$title.'" alt="'.$title.'"'.
                ' width="'.$size.'" height="'.$size.'" />';
            return true;
        }
        return false;
    }
     
}
?></code>

===== External required libraries: ===== 


Download the [[http://sourceforge.net/project/showfiles.php?group_id=122936|Sparkline PHP Graphing Library]] and put the following files in the plugin directory:

  * Object.php
  * Sparkline.php
  * Sparkline_Bar.php
  * LICENSE

then create the file:

''spark.php''

with the following content:

<code php>
<?php
/**
 * Spark.php : creates sparkline from GET data
 *
 * example : <img src="spark.php?data=43,27,19,17,47,-38,-67,26"></img>
 * 
 * Uses the Sparkline PHP Graphing Library http://sparkline.org
 * Copyright 2004 James Byers <jbyers@users.sf.net>
 * code is similar to sample
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 */

$data = $_GET[data]; //probably needs more checking
$data = explode(",",$data); 
require_once('Sparkline_Bar.php');
$sparkline = new Sparkline_Bar();
$sparkline->SetDebugLevel(DEBUG_NONE);
$sparkline->SetBarWidth(2);
$sparkline->SetBarSpacing(1);
while (list($k, $v) = each($data)) {
  $color = 'black';
  if ($v < 0) {
    $color = 'red';
  }
  $sparkline->SetData($k, $v, $color);
}
$sparkline->Render(16); // height in pix
$sparkline->Output();
?>
</code>

===== Discussion =====

> [[esther@kaffeehaus.ch|Esther Brunner]] wrote: ''I would recommend you to take the Gravatar plugin [[http://www.dokuwiki.org/plugin:gravatar]] as a base for your plugin since  that's very similar in its nature. You can even reuse the left /  center / right alignment. How about the following markup tag: %%{{spark>25,12,25,35,36,200,325,25,-58,-25,25}}%% That way it closely resembles other external file or image content.''

>> Thanks for the suggestion, but this was already on my disc so this is just code repository here. I agree that %%{{spark }}%% is a more preferred syntax. Please feel free to mock up / change anything that complies more to the DokuWiki standards.

> I am totally aware that there are numerous extensions possible to this script.

>>> I made a few changes to the script and also added support for titles, alignment and caching. It is untested as I don't have the time to install it at the moment. I hope it works. The sparkline feature is for sure another great extension of DokuWiki. --- //[[esther@kaffeehaus.ch|Esther Brunner]] 2005-08-04 21:29//

>>>> Esther thou art kewl

> Andrzej: Unfortunately it doesn’t work 

>> Andrzej, It works, what is wrong with it at your place?

>> It should work now, at least it does on [[http://www.qwik.ch/playground|my server]]. The URL wasn't constructed correctly. --- //[[esther@kaffeehaus.ch|Esther Brunner]] 2005-08-18 19:54//

>>> Andrzej: Still null (also at your site).

> Has anyone extended this to load a text file from the media are for the data values?

> I finally made this wonderful plugin work, but I wasn't able to paste the code here. So if you want a solution, send me a mail (or show me how to paste code here ;-) ) Must have to do with some unfinished tag here in this section?.  --- //[[taffit@gmail.com|David Siller]] 2006-04-27 14:55//

>> David, have a look at [[http://www.dokuwiki.org/wiki:syntax#syntax_highlighting]] on how to put code here (not embedding code but merely showing nonparsed code)

>>> Oh, I know the syntax of DokuWiki, it just didn't work. Even now: I've pasted the code here (clicking the edit-button of the discussion) and the whole page was discarded on clicking on 'Save' (previewing it first), except the last discussion-entries (and my new entry). I restored the page but don't want to delete anything else again. So you can find the code in the older review of this page, maybe you can enter it here.--- //[[taffit@gmail.com|David Siller]] 2006-06-16 08:35//

((Yes there was some weird tag mess up here... It would be nice to have a geshi syntax colouring to find out what went wrong here.. Anyway, after removing some tags from Andrzej and adding some at your place I hope its fixed.. //riny//))

**Here comes David's code..**

<code php>
$data = $_GET[data]; //probably needs more checking
$data = explode(",",$data); 
require_once('Sparkline_Bar.php');
$sparkline = new Sparkline_Bar();
$sparkline->SetDebugLevel(DEBUG_NONE);
$sparkline->SetBarWidth(2);
$sparkline->SetBarSpacing(1);
while (list($k, $v) = each($data)) {
</code>
> (the code above produced an error or warning on my wiki about constant ''data'') with
<code php>
$daten = $_GET['data']; //probably needs more checking
$daten = explode(",",$daten); 
require_once('Sparkline_Bar.php');
$sparkline = new Sparkline_Bar();
$sparkline->SetDebugLevel(DEBUG_NONE);
$sparkline->SetBarWidth(2);
$sparkline->SetBarSpacing(1);
while (list($k, $v) = each($daten)) {
</code>
and the following code in the ''render''-function of the ''syntax.php''
<code php>
$renderer->doc .= '<img src="'.$spark_url.'" class="media'.$data[2].'"'.
                ' title="'.$title.'" alt="'.$title.'"'.
                ' width="'.$size.'" height="'.$size.'" />';
</code>
with the following code:
<code php>
$renderer->doc .= '<img src="'.$spark_url.'" class="media'.$data[2].'"'.
                ' title="'.$title.'" alt="'.$title.'" />';
</code>
This way it works (at least on my installation). IMHO the alignment should be removed to have the graphics appear in the text (as sparklines are intended).\\ Oh, and remove my comments if you have implemented the above changes in this wonderful plugin ;-).  --- //[[taffit@gmail.com|David Siller]] 2006-04-27 14:42//

>Hi, this works nicely for me in Firefox but the PNG is invisible in IE (IE6 windows). I can see the PNG sparklines >on places like sparkline.org. A mystery to me. I use some 'fix IE5 PNG transparency' JavaScript on some other site >so I tried that on my DokuWiki pages, but no joy. Any ideas welcome.  --- //[[robinsend@gmail.com|Brad L]] 2006-08-01//

If you add the last change on this page, which removes $size and $height the png will be visible in IE. At least it fixed my problem. --- //markus 2006-09-15