Sparklines Plugin

Description

While sparkline plugin uses graphicsbuilder library to draw charts this plugin utilizes jQuery Sparklines library. Most of the information below was taken from the official documentation.

Syntax

Before you start using sparklines you must load all prerequisities by putting

<sparklines:resources />

The common syntax for sparklines is

<sparklines:TYPE id="ID" values="DATA" [style="STYLE"] [options="OPTIONS"] [attrs] />

or

<sparklines:draw id="ID" values="DATA" [style="STYLE"] [options="OPTIONS"] [attrs] />

Generates TYPE charts with the values and options provided. Supported TYPE values are: line (default), bar, pie, tristate, discrete, bullet, box and draw (lets you set the chart type in the options).

• ID - This is the identificator of the corresponding span object that wraps the chart.
• STYLE(Optional) - The CSS style of the span object, containing the chart.
• VALUES - This is the list with the values ordered from left to right, e.g. [1,-2,5,2,1,6,3,1]. (There are also another ways discussed in the end of the 'Line' section)
• OPTIONS(Optional) - It is the map with the keys from the list below, e.g. [type: 'line', width: 350].
• attrs(Optional) - That can be each of the options available for the tag, e.g. type="line" width="100".

Only common options are available for draw tag as attributes.

Common Options (available for all the tags)

• type - line (default), bar, tristate, discrete, bullet, pie or box
• width - Width of the chart - Defaults to 'auto' - May be any valid css width - 1.5em, 20px, etc (using a number without a unit specifier won't do what you want) - This option does nothing for bar and tristate chars (see barWidth)
• height - Height of the chart - Defaults to 'auto' (line height of the containing tag)
• lineColor - Used by line and discrete charts
• fillColor - Set to false to disable fill.
• chartRangeMin - Specify the minimum value to use for the range of the chart - Defaults to the minimum value supplied
• chartRangeMax - Specify the maximum value to use for the range of the chart - Defaults to the maximum value supplied
• composite - If true then don't erase any existing chart attached to the tag, but draw another chart over the top - Note that width and height are ignored if an existing chart is detected.

Line

<sparklines:line id="ID" values="DATA" [style="STYLE"] [options="OPTIONS"] [attrs] />

Generates line chart. It is the default chart type.

Options

• defaultPixelsPerValue - Defaults to 3 pixels of width for each value in the chart
• spotColor - Set to false or an empty string to hide the final value marker
• minSpotColor - Set to false or an empty string to hide the minimum value marker
• maxSpotColor - Set to false or an empty string to hide the maximum value marker
• spotRadius - In pixels (default: 1.5)
• lineWidth - In pixels (default: 1)
• normalRangeMin, normalRangeMax Specify threshold values between which to draw a bar to denote the "normal" or expected range of values. For example the green bar here might denote a normal operating temperature range.
• xvalues - See below
• chartRangeClip - If true then the y values supplied to plot will be clipped to fall between chartRangeMin and chartRangeMax - By default chartRangeMin/Max just ensure that the chart spans at least that range of values, but does not constrain it
• chartRangeMinX - Specifies the minimum value to use for the X value of the charge
• chartRangeMaxX - Specifies the maximum value to use for the X value of the charge

1. Inline: x and y values are separated by a colon: x:y,x:y,x:y - eg. 1:3,2.7:4,4.8:3

You can also specify a value of "null" to omit values from the chart completely.

Bar

<sparklines:bar id="ID" values="DATA" [style="STYLE"] [options="OPTIONS"] [attrs] />

Generates bar charts. Values can be omitted by using the "null" value instead of a number.

Options

• barColor - Colour used for postive values
• negBarColor - Colour used for negative values
• zeroColor - Colour used for values equal to zero
• nullColor - Colour used for values equal to null - By default null values are omitted entirely, but setting this adds a thin marker for the entry - This can be useful if your chart is pretty sparse; perhaps try setting it to a light grey or something equally unobtrusive
• barWidth - Width of each bar, in pixels
• barSpacing - Space between each bar, in pixels
• zeroAxis - Centers the y-axis at zero if true (default is to automatically do the right thing)
• colorMap - Map override colors to certain values - For example if you want all values of -2 to appear yellow, use colorMap: { '-2': '#ff0' }. You may also pass an Array of values here instead of a mapping to specifiy a color for each individual bar. For example if your chart has three values 1,3,1 you can set colorMap=["red", "green", "blue"]

Pie

<sparklines:pie id="ID" values="DATA" [style="STYLE"] [options="OPTIONS"] [attrs] />

Generates pie chart.

Options

• sliceColors - An array of colors to use for pie slices
• offset - Angle in degrees to offset the first slice - Try -90 or +90

Tristate

<sparklines:tristate id="ID" values="DATA" [style="STYLE"] [options="OPTIONS"] [attrs] />

Generates tristate charts.

Options

• posBarColor - Colour for positive (win) values
• negBarColor - Colour for negative (lose) values
• zeroBarColor - Colour for zero (draw) values
• barWidth - Width of each bar, in pixels
• barSpacing - Space between each bar, in pixels
• zeroAxis - Centers the y-axis at zero if true (default is to automatically do the right thing)
• colorMap - Map override colors to certain values - For example if you want all values of -2 to appear yellow, use colorMap: { '-2': '#ff0' }. You may also pass an Array of values here instead of a mapping to specifiy a color for each individual bar. For example if your chart has three values 1,3,1 you can set colorMap=["red", "green", "blue"]

Discrete

<sparklines:discrete id="ID" values="DATA" [style="STYLE"] [options="OPTIONS"] [attrs] />

Generates discrete chart.

Options

• lineHeight - Height of each line in pixels - Defaults to 30% of the graph height
• thesholdValue - Values less than this value will be drawn using thresholdColor instead of lineColor
• thresholdColor - The color to be user if the value is greater or equal to thresholdValue

Bullet

<sparklines:bullet id="ID" values="DATA" [style="STYLE"] [options="OPTIONS"] [attrs] />

Generates bullet chart.

Options

• targetColor - The colour of the vertical target marker
• targetWidth - The width of the target marker in pixels
• performanceColor - The color of the performance measure horizontal bar
• rangeColors - Colors to use for each qualitative range background color

Box

<sparklines:box id="ID" values="DATA" [style="STYLE"] [options="OPTIONS"] [attrs] />

Generates box chart.

Options

• raw - If set to false (default) then the values supplied are used to caculate the box data points for you. If true then you must pre-calculate the points (see below)
• showOutliers - If true (default) then outliers (values > 1.5x the IQR) are marked with circles and the whiskers are placed at Q1 and Q3 instead of the least and greatest value
• outlierIQR - Set the inter-quartile range multipler used to calculate values that qualify as an outlier - Defaults to 1.5x
• boxLineColor - Line colour used to outline the box
• boxFillColor - Fill colour used for the box
• whiskerColor - Colour used to draw the whiskers
• outlierLineColor - Colour used to draw the outlier circles
• outlierFillColor - Colour used to fill the outlier circles
• spotRadius - Radius to draw the outlier circles
• medianColor - Colour used to draw the median line
• target - If set to a value, then a small crosshair is drawn at that point to represent a target value
• targetColor - Colour used to draw the target crosshair, if set
• minValue - If minvalue and maxvalue are set then the scale of the plot is fixed. By default minValue and maxValue are deduced from the values supplied
• maxValue - See minValue

If, on the other hand, you have thousands of values to deal with you may want to pre-compute the points needed for the box plot. In that case, set raw=true and pass in the computed values. If showing outliers, supplied values of: low_outlier, low_whisker, q1, median, q3, high_whisker, high_outlier Omit the outliers and set showOutliers to false to omit outlier display.