The Brief Tutorial

This tutorial will tell you how to use GChart to draw the data charts. Before you start, be sure you have installed the following software:

  • Apache HTTP Server (or any other web server supporting PHP)
  • PHP5

GChart uses some object-oriented features that PHP4 doesn’t support. So you need to use PHP5 or above. The database, such as MySQL, is not necessary. But most of PHP scripts need database and you can also retrieve data from the database and generate the charts.

Using GChart to Draw Your First Chart

First, you need to download it from Sourceforge.net. Then unpack it to a directory. For example, your web server’s document root is D:\Web. You can unpack it to it. Then you will see the “D:\Web\gchart-[version]“. [version] means the version number of the GChart. For convenience, I recommend you to change “gchart-[version]” into “gchart”.

Next, In the directory “D:\Web”, create a PHP file called “test.php”, which contains the following contents:

<html>
<body>
<?php
define ('GChart_DIR',dirname(__FILE__).'/gchart/');
require_once (GChart_DIR.'GChart.php');
 
$pie2d=new GChart_Pie2D(200,100);
$pie2d->add(50,'China');
$pie2d->add(25,'Canada');
$pie2d->add(6,'US');
 
$pie2d->set_background('EFEFEF');
?>
<img src="<?php echo $pie2d->get_image_string(); ?>" />
</body>
</html>

Open your browser and visit “http://localhost/test.php”. You will see the image like this:

Notice: the definition ‘GChart_DIR’ can not be omitted. GChart library will use its value to find its classes and functions.

Now let me explain the code above briefly. GChart provides many classes, each class is used to generate one kind of charts. e.g. GChart_Pie2D means 2-dimension pie charts and GChart_Line means line charts, etc. When you create an image object, you need to set its width and height in the constructor. The size cannot be omitted.

You can use “add” method to add the data into a pie chart. The example above shows how to add a single item into a pie chart object. For pie chart, the “add” method needs one argument at least that indicates the value. Also, you can use add($value, $label, $color) to set the label and the color. $color is a 6-characters string. It uses the format “RRGGBB” to set color. The last two arguments are optional.

“$pie2d->set_background(’EFEFEF’);” sets the background color to light gray. Most of charts have “set_background” method, but there are a few differences between the different charts. For example, some charts can use “linear gradient” color as their background while others not.

The last code, <img src=”<?php echo $pie2d->get_image_string(); ?>” />, generates the image. All chart classes have “get_image_string” to generate the image’s URL. It put all the attributes and data in the URL to tell Google how to render the image. So you will see the chart.

Multiple Data Series

For line charts, bar charts and radar chart, you can add more than one data series. GChart uses “GChart_DataSeries” to implement this function. For example, a line chart may contains several lines, and each line contains several numbers. The code below demonstrate how to use multiply data series.

<?php
$l=new GChart_Line(240,150);
$s1=new GChart_DataSeries();
$s1->set_items(array(38,25,94,21,76),'First','0EDA98');
$s2=new GChart_DataSeries(array(19,63,69,21,78),'Second','F9E687');
$l->add($s1);
$l->add($s2);
?>
<img src="<?php echo $l->get_image_string(); ?>" />

Here is the result:

The Axis

You can add x-axis and y-axis to line charts, radar charts, bar charts and scatter plot charts. Adding an axis is very simple. Now let’s add two axises. Add the following lines after “$l->add($s2);”

$x_axis=new GChart_Axis(GChart_BOTTOM_X_AXIS);
$y_axis=new GChart_Axis(GChart_LEFT_Y_AXIS);
$l->add_axis($x_axis);
$l->add_axis($y_axis);

Normally, you should get a GChart_Axis object and then add it to the chart. However, for convenience, GChart provides a easier way to do it:

$l->add_axis(GChart_BOTTOM_X_AXIS); // or $l->add_axis('x');
$l->add_axis(GChart_LEFT_Y_AXIS); // or $l->add_axis('y');

Let’s see what it looks like:

If you want to set the labels on the axises, use GChart_Axis::set_labels(array $a).

$x_axis->set_labels(array('Jan','Feb','Mar','Apr','May'));
$y_axis->set_labels(array(0,25,50,75,100));
$l->add_axis($x_axis);
$l->add_axis($y_axis);

Or just pass the label array to “add_axis” function:

$l->add_axis(GChart_BOTTOM_X_AXIS,null,array('Jan','Feb','Mar','Apr','May'));
$l->add_axis(GChart_LEFT_Y_AXIS,null,array(0,25,50,75,100));

The second argument of “add_axis” is the axis’ name. It is a unique string for the axis. In this example, the name is useless, so I set it to “null”.

A Problem

If there is a number which is greater than 100, the default axis labels are incorrect. There are two methods to solve the problem.

1. Use GChart_Axis::set_boundry($low, $high) to set the start point (usually, 0) and the end point (the maximum value) of an axis.

$l->add_axis(GChart_BOTTOM_X_AXIS,null,array('Jan','Feb','Mar','Apr','May'));
$y_axis=new GChart_Axis('y');
$y_axis->set_boundry(0,325); // The max value is 325.
$l->add_axis($y_axis);

You should set the low boundry of the axis to 0. Otherwise, the chart will be incorrect.

Now the chart becomes:

2. Using “text encoding with data scaling” and the set_boundry() function.
If you just use “set_boundry()” method, you must set the low boundry to 0. If you want to let the low boundry of the axis be another value, you should set the data encoding to TEXT_ENCODING_SCALING. Look at the code below.

$l=new GChart_Line(240,150);
$s1=new GChart_DataSeries();
$s1->set_items(array(243,195,325,213,176),'First','0EDA98');
 
// Set the data encoding.
$l->set_encoding(TEXT_ENCODING_SCALING);
 
// The arguments means all the numbers are between 150 and 330.
$s1->set_scaling(150,330);
$l->add($s1);
$l->add_axis(GChart_BOTTOM_X_AXIS,null,array('Jan','Feb','Mar','Apr','May'));
$y_axis=new GChart_Axis('y');
 
// The two arguments must be same as the ones of "set_scaling()".
$y_axis->set_boundry(150,330);
$l->add_axis($y_axis);

Now the chart looks better: