Sparkline Usage


This page aims to explain how to use the PHP library to create sparklines, and documents the various options available.

Including the Library


In order for a PHP script to use the Sparkline library, the library must first be included into the script. Exact usage will depend upon the installation location of the library.

To create a line-chart Sparkline like this CSCO3a.png, include the Sparkline_Line.php file:
  • require_once('/sparkline/Sparkline_Line.php');

To include a bar-chart Sparkline like this deficit.png, include the Sparkline_Bar.php file:
  • require_once('/sparkline/Sparkline_Bar.php');

Sparkline Object


The next step is to create a Sparkline Object:
  • $sparkline = new Sparkline_Line();

Adding Data


Before data can be plotted, the x and y values must be added to the Sparkline object via the SetData() method.
  • $sparkline->SetData(0, 15);
  • $sparkline->SetData(1, 18);
  • $sparkline->SetData(2, 9);

When creating bar-chart Sparklines, two additional parameters are available to set the color of the bar and whether an underscore should be placed under the bar, as in this example: yankees.png
  • $sparkline->SetData(0, 15, 'black', false);
  • $sparkline->SetData(1, 18, 'red', true);

Need to look into the series parameter for multiple lines

Rendering the Sparkline


There are two ways to render line-chart Sparklines. Low resolution mode is a simple two-color line drawing. High resolution mode first renders the image at a high resolution and resamples it into a small space. The resampling process incurs a significant performance penalty but improves the quality of the image through anti-aliasing and shading.

The two parameters to the Render() or RenderResampled() methods are the width and heigh of the desired Sparkline:
  • $sparkline->Render(100, 20);
  • $sparkline->RenderResampled(100, 20);

Bar-chart Sparklines can only be rendered in low resolution mode, and only the height of the Sparkline is specified. The width of the Sparkline is automatically determined by the number of bars and the width of each bar.
  • $sparkline->Render(20);

Outputting the PNG Image


The final step in creating a Sparkline is outputting the PNG image from the script. The Output() method will display the graph by sending a Content-type: image/png header then outputting the image data:
  • $sparkline->Output();

Saving to disk


Specify a filename to the Output() method in order to save a Sparkline to a file.
  • $sparkline->Output('path/to/file.png');

Optional Settings


While the above methods will enable the generation of simple Sparklines, several other settings are available to provide finer control over the final output and to assist with troubleshooting.

Debugging


The SetDebugLevel() method can be used to enable various levels of debug output to a named file. Both a list of desired debug levels and a file name must be provided.
  • $sparkline->SetDebugLevel(DEBUG_ERROR | DEBUG_WARNING | DEBUG_STATS, 'log.txt');

Available debug levels which can be ored together are:

DEBUG_NONE
nothing
DEBUG_ERROR
major errors
DEBUG_WARNING
warnings
DEBUG_STATS
dataset, rendering statistics
DEBUG_CALLS
major function calls
DEBUG_SET
all Set methods
DEBUG_DRAW
all Draw methods
DEBUG_ALL
everything

Min and Max Y Values


The Sparkline library automatically calculates the minimum and maximum values for the Y axis. However, these values can also be set manually via the SetYMin() and SetYMax() setter methods. This could be done, for example, to ensure consistency across several related Sparklines.
  • $sparkline->SetYMin(10);
  • $sparkline->SetYMax(50);

Feature Points


Small circular markers called feature points can be added to line-chart Sparklines at specified locations. For example, in this Sparkline CSCO3a.png, three markers (green, red, and blue) have been added to indicate the max, min, and final data point in the line. Feature points can also have optional text.

The parameters for the SetFeaturePoint() method are, in order: x value, y value, color name, circle diameter, text (optional), text location (optional), and font (optional).

  • $sparkline->SetFeaturePoint(1, 17, 'red', 3, 'hello', TEXT_TOP, FONT_1);
  • $sparkline->SetFeaturePoint(23, 5, 'blue', 3);

Available values for the text location are: TEXT_TOP, TEXT_RIGHT, TEXT_BOTTOM, TEXT_LEFT.

Colors


Coming soon...

$sparkline->SetColorHtml('background', '#ddddff');
$sparkline->SetColorBackground('background');
SetBarColorDefault($value)
SetBarColorUnderscoreDefault($value)
SetData($x, $y, $color=null, $underscore=false, ..


Transparency :


Maybe you need a transparent background?
The following steps adds a function to solve this problem :

- open Sparklines.php in your favourite editor.
- add the following code to the end of the file:

function setTransparency () {
$this->colorTransparency = "1";
} function setTransparency

- search the function DrawBackground and replace the whole function with the following code:

function DrawBackground($handle = false) {
$this->Debug("Sparkline :: DrawBackground()", DEBUG_DRAW);
if (!$this->IsError()) {
if ($handle === false) $handle = $this->imageHandle;
$this->DrawRectangleFilled(0,
0,
imagesx($handle) - 1,
imagesy($handle) - 1,
$this->colorBackground,
$handle);
if ($this->colorTransparency == "1") {
imagecolortransparent($handle, $this->colorList[$this->colorBackground]['handle']);
}
}
}
function DrawBackground

- save the file

To add transparency to your sparkline pngs you can use this method:

$sparkline->setTransparency();

Thats all folks, have fun! ;-)