3D Thermometer Class Documentation

We said the Black Locust Thermometer is easy to use. Let me show you some sample code and explain it.

System Requirements

  • PHP 4 or 5
  • gd library

Samples

In this page:
<img src="/Components/thermometer.sample2.php" width="10px" height="40px">
In the sample2 file:
<?php 
//thermometer image
require_once('thermometer.class.php');


$T = new BlackLocustGoalThermometer();
$T->Height = 200; //image height in pixels. Width is automatically set between 41 and 280 depending on options selected.
$T->ShowText = false; //Show text of titles & amounts for data & amounts.  Adds 139 pixels to the width.
$T->ShowKey = false; //Show the legend/key.  Adds 100 pixels to the width.
$T->ReportTitle = ""; //Title at the top
$T->TransparentBG=true; //if false, BG is White

$datavals = array(
    array("color"=>"green", "value"=>"57000", "title"=>"Collected", "format"=>"currency"),
    array("color"=>"blue", "value"=>"139000", "title"=>"PostDates", "format"=>"currency")
);

$T->DataArray = $datavals;

$goals = array(
    array("value"=>"129000", "title"=>"Office Goal", "format"=>"currency"),
    array("value"=>"169000", "title"=>"Bonus Goal", "format"=>"currency")
);

$T->GoalArray = $goals;

$T->RenderThermometer();
?>
In this page:
<img src="/Components/thermometer.sample1.php" >
In the sample1 file:
<?php 
//thermometer image
require_once('thermometer.class.php');


$T = new BlackLocustGoalThermometer();
$T->Height = 500; //image height in pixels. Width is automatically set between 41 and 280 depending on options selected.
$T->ShowText = true; //Show text of titles & amounts for data & amounts.  Adds 139 pixels to the width.
$T->ShowKey = false; //Show the legend/key.  Adds 100 pixels to the width.
$T->ReportTitle = "Black Locust"; //Title at the top
$T->TransparentBG=true; //if false, BG is White

$datavals = array(
    array("color"=>"green", "value"=>"17000", "title"=>"Monday", "format"=>"currency"),
    array("color"=>"blue", "value"=>"39000", "title"=>"Tuesday", "format"=>"currency"),
    array("color"=>"yellow", "value"=>"79000", "title"=>"Wednesday", "format"=>"currency"),
    array("color"=>"red", "value"=>"98000", "title"=>"Thursday", "format"=>"currency"),
    array("color"=>"purple", "value"=>"117000", "title"=>"Friday", "format"=>"currency"),
    array("color"=>"teal", "value"=>"153000", "title"=>"Saturday", "format"=>"currency")
);

$T->DataArray = $datavals;

$goals = array(
    array("value"=>"129000", "title"=>"Office Goal", "format"=>"currency"),
    array("value"=>"169000", "title"=>"Bonus Goal", "format"=>"currency")
);

$T->GoalArray = $goals;

$T->RenderThermometer();
?>
In the sample3 file:
<?php 
require_once('thermometer.class.php');


$T = new BlackLocustGoalThermometer();
$T->Height = 500; 
$T->ShowText = true; 
$T->ShowKey = true; //Show the legend/key.  Adds 100 pixels to the width.
$T->ShowBorder=true;
$T->ReportTitle = "Bake Sale Proceeds"; //Title at the top
$T->TransparentBG=true; //if false, BG is White
$T->AlternateText = false; // all text on left side

$datavals = array(
    array("color"=>"green", "value"=>"17000", "title"=>"Monday", "format"=>"currency"),
    array("color"=>"blue", "value"=>"39000", "title"=>"Tuesday", "format"=>"currency"),
    array("color"=>"yellow", "value"=>"79000", "title"=>"Wednesday", "format"=>"currency"),
    array("color"=>"red", "value"=>"98000", "title"=>"Thursday", "format"=>"currency"),
    array("color"=>"purple", "value"=>"117000", "title"=>"Friday", "format"=>"currency"),
    array("color"=>"teal", "value"=>"153000", "title"=>"Saturday", "format"=>"currency")
);

$T->DataArray = $datavals;

$goals = array(
    array("value"=>"129000", "title"=>"Office Goal", "format"=>"currency"),
    array("value"=>"169000", "title"=>"Bonus Goal", "format"=>"currency")
);

$T->GoalArray = $goals;

$T->RenderThermometer();
?>
Sample4 demonstrates the AutoScale method:
<?php 
require_once('thermometer.class.php');


$T = new BlackLocustGoalThermometer();
$T->Height = 500; 
$T->ShowText = true; 
$T->ReportTitle = "AutoScale Sample"; //Title at the top
$T->TransparentBG=true; //if false, BG is White

$datavals = array(
    array("color"=>"green", "value"=>"19000", "title"=>"PC's", "format"=>"currency"),
    array("color"=>"blue", "value"=>"36000", "title"=>"Laptops", "format"=>"currency"),
    array("color"=>"yellow", "value"=>"53545.72", "title"=>"Routers", "format"=>"currency"),
    array("color"=>"red", "value"=>"79986.68", "title"=>"Software", "format"=>"currency"),
    array("color"=>"purple", "value"=>"101897.57", "title"=>"Parts", "format"=>"currency"),
    array("color"=>"teal", "value"=>"127698.35", "title"=>"Consulting", "format"=>"currency")
);

$T->DataArray = $datavals;

$T->AutoScale("sales", "currency",2,false,true);  //generate the scale automatically, rather than statically.

$T->RenderThermometer();
?>

Properties

  • AlternateText - Boolean. Make text alternate left & right to avoid collissions. Default to true
  • DataArray - Array of data points, usually loaded from a database. Overwritten if you call AutoScale. Details below.
  • GoalArray - Required. Array of goal marks. Details are also below.
  • Height - Required. Image height in pixels. Width is automatically set between 41 and 280 depending on options selected.
  • ReportTitle - Title at the top. Truncates if too long for the image's width.
  • ShowBorder - Boolean. Draws sides to the thermometer. Defaults to false
  • ShowText - Boolean. Show text of titles & amounts for data & amounts. Adds 139 pixels to the width.
  • ShowKey - Boolean. Show the legend/key. Adds 100 pixels to the width.
  • TransparentBG - Boolean. Image renders as a PNG, so transparency is an option ... allowing you to overlay this on a gradient background, for example. If false, BG is White.
  • TitleFontSize - Font size of title at top. Valid values are between 1 and 5 (per gd library). Defaults to 5.
  • LabelFontSize - Font size of data and goal titles / labels. Valid values are between 1 and 5 (per gd library). Defaults to 3.
  • ValueFontSize - Font size of numeric values. Valid values are between 1 and 5 (per gd library). Defaults to 2.

Methods

  • RenderThermometer() -- draw the image!
  • AutoScale($label="", $format="", $decimals=2, $hidevalues=false, $hidelabels=false) -- automatically generate a scale to replace the Goals array.

Array Components

  • title - text associated with the goal or data point.
  • value - the numeric value of the goal or data point.
  • format - instruction on display of this data point. Valid values are:
    • usd - display with a $ sign. If value >= 100,000 display only dollars. If < 100,000, display 2 decimal places.
    • currency - same as usd.
    • percent - show percentage with no decimal places, followed by % sign. e.g. 0.85 displays as 85%
    • integer - format to 0 decimal places.
    • decimal - format to decimals places.
  • color - data array only - color of thermometer fill. Valid values are:
    • red
    • green
    • blue
    • yellow
    • purple
    • teal
  • decimals - valid only with format="decimal" - number of decimals to format.
  • hidevalue - Boolean. If true, this numeric value is hidden even though ShowText is true. Useful for limiting the amount of text shown on the thermometer graph.
  • hidelabel - Boolean. If true, this data or goal title/label is hidden even though ShowText is true. Useful for limiting the amount of text shown on the thermometer graph.