doc/plugins/sparkline.mdwn

   1 [[template id=plugin name=sparkline author="[[Joey]]"]]
   2 [[tag type/chrome]]
   3
   4 This plugin allows for easily embedding sparklines into wiki pages. A
   5 sparkline is a small word-size graphic chart, that is designed to be
   6 inlined alongside text.
   7
   8 # requirements
   9
  10 The plugin uses the [Sparkline PHP Graphing Library](http://sparkline.org/)
  11 as it has better output than the native perl sparkline library. Therefore,
  12 to use the plugin, you will need:
  13
  14 * The Sparkline PHP Graphing Library, installed in php's path so that
  15   php can find it when `sparkline/Sparkline.php` is required.
  16 * The GD PHP module used by the Sparkline library.
  17 * A "php" program in the path, that can run standalone php programs.
  18 * [[cpan Digest::SHA1]]
  19
  20 On a Debian system, this can be accomplished by installing the
  21 `libsparkline-php`, `php5-gd`, `php5-cli`, and `libdigest-sha1-perl`
  22 packages.
  23
  24 # examples
  25
  26         \[[sparkline 1 3 5 -3 10 0 width=40 height=16
  27         featurepoint="4,-3,red,3" featurepoint="5,10,green,3"]]
  28
  29 [[if test="enabled(sparkline)" then="""
  30 [[sparkline 1 3 5 -3 10 0 width=40 height=16
  31 featurepoint="4,-3,red,3" featurepoint="5,10,green,3"]]
  32 """]]
  33
  34 This creates a simple line graph, graphing several points. It will be drawn
  35 40 pixels wide and 16 pixels high. The high point in the line has a green
  36 marker, and the low point has a red marker.
  37
  38         \[[sparkline 1 -1(red) 1 -1(red) 1 1 1 -1(red) -1(red) style=bar barwidth=2
  39         barspacing=1 height=13]]
  40
  41 [[if test="enabled(sparkline)" then="""
  42 [[sparkline 1 -1(red) 1 -1(red) 1 1 1 -1(red) -1(red)
  43 style=bar barwidth=2 barspacing=1 height=13]]
  44 """]]
  45
  46 This more complex example generates a bar graph. The bars are 2 pixels
  47 wide, and separated by one pixel, and the graph is 13 pixels tall. Width is
  48 determined automatically for bar graphs. The points with negative values
  49 are colored red, instead of the default black.
  50
  51 # usage
  52
  53 The form for the data points is "x,y" for line graphs, or just "y" if the x
  54 values don't matter. Bar graphs can also add "(color)" to specify a color
  55 for that bar.
  56
  57 The following named parameters are recognised. Most of these are the same
  58 as those used by the underlying sparkline library, which is documented in
  59 more detail in [its wiki](http://sparkline.wikispaces.com/usage).
  60
  61 * `style` - Either "line" (the default) or "bar".
  62 * `width` - Width of the graph in pixels. Only needed for line graphs.
  63 * `height` - Height of the graph in pixels. Defaults to 16.
  64 * `barwidth` - Width of bars in a bar graph. Default is 1 pixel.
  65 * `barspacing` - Spacing between bars in a bar graph, in pixels. Default is
  66   1 pixel.
  67 * `ymin`, `ymax` - Minimum and maximum values for the Y axis. This is
  68   normally calculated automatically, but can be explicitly specified to get
  69   the same values for multiple related graphs.
  70 * `featurepoint` - Adds a circular marker to a line graph, with optional
  71   text. This can be used to label significant points.
  72
  73   The value is a comma-delimited list of parameters specifying the feature
  74   point: X value, Y value, color name, circle diameter, text (optional),
  75   and text location (optional). Example: `featurepoint="3,5,blue,3"`
  76
  77   Available values for the text location are: "top", "right", "bottom", and
  78   "left".