* Add a sparline plugin.

[ikiwiki.git] / doc / plugins / sparkline.mdwn

diff --git a/doc/plugins/sparkline.mdwn b/doc/plugins/sparkline.mdwn
new file mode 100644 (file)
index 0000000..be3c68c
--- /dev/null
+++ b/doc/plugins/sparkline.mdwn
@@ -0,0 +1,78 @@
+[[template id=plugin name=sparkline author="[[Joey]]"]]
+[[tag type/chrome]]
+
+This plugin allows for easily embedding sparklines into wiki pages. A
+sparkline is a small word-size graphic chart, that is designed to be
+inlined alongside text.
+
+# requirements
+
+The plugin uses the [Sparkline PHP Graphing Library](http://sparkline.org/)
+as it has better output than the native perl sparkline library. Therefore,
+to use the plugin, you will need:
+
+* The Sparkline PHP Graphing Library, installed in php's path so that
+  php can find it when `sparkline/Sparkline.php` is required.
+* The GD PHP module used by the Sparkline library.
+* A "php" program in the path, that can run standalone php programs.
+* [[cpan Digest::SHA1]]
+
+On a Debian system, this can be accomplished by installing the
+`libsparkline-php`, `php5-gd`, `php5-cli`, and `libdigest-sha1-perl`
+packages.
+
+# examples
+
+       \[[sparkline 1 3 5 -3 10 0 width=40 height=16
+       featurepoint="4,-3,red,3" featurepoint="5,10,green,3"]]
+
+[[if test="enabled(sparkline)" then="""
+[[sparkline 1 3 5 -3 10 0 width=40 height=16
+featurepoint="4,-3,red,3" featurepoint="5,10,green,3"]]
+"""]]
+
+This creates a simple line graph, graphing several points. It will be drawn
+40 pixels wide and 16 pixels high. The high point in the line has a green
+marker, and the low point has a red marker.
+
+       \[[sparkline 1 -1(red) 1 -1(red) 1 1 1 -1(red) -1(red) style=bar barwidth=2
+       barspacing=1 height=13]]
+
+[[if test="enabled(sparkline)" then="""
+[[sparkline 1 -1(red) 1 -1(red) 1 1 1 -1(red) -1(red) style=bar barwidth=2
+barspacing=1 height=13]]
+"""]]
+
+This more complex example generates a bar graph. The bars are 2 pixels
+wide, and separated by one pixel, and the graph is 13 pixels tall. Width is
+determined automatically for bar graphs. The points with negative values
+are colored red, instead of the default black.
+
+# usage
+
+The form for the data points is "x,y" for line graphs, or just "y" if the x
+values don't matter. Bar graphs can also add "(color)" to specify a color
+for that bar.
+
+The following named parameters are recognised. Most of these are the same
+as those used by the underlying sparkline library, which is documented in
+more detail in [its wiki](http://sparkline.wikispaces.com/usage).
+
+* `style` - Either "line" (the default) or "bar".
+* `width` - Width of the graph in pixels. Only needed for line graphs.
+* `height` - Height of the graph in pixels. Defaults to 16.
+* `barwidth` - Width of bars in a bar graph. Default is 1 pixel.
+* `barspacing` - Spacing between bars in a bar graph, in pixels. Default is
+  1 pixel.
+* `ymin`, `ymax` - Minimum and maximum values for the Y axis. This is
+  normally calculated automatically, but can be explicitly specified to get
+  the same values for multiple related graphs.
+* `featurepoint` - Adds a circular marker to a line graph, with optional
+  text. This can be used to label significant points.
+  
+  The value is a comma-delimited list of parameters specifying the feature
+  point: X value, Y value, color name, circle diameter, text (optional),
+  and text location (optional). Example: `featurepoint="3,5,blue,3"`
+  
+  Available values for the text location are: "top", "right", "bottom", and
+  "left".