WS Charts 1

WS Charts 1.0

User’s Manual

Introduction

I wanted to create a flexible, graphically appealing and easy to use extension to assist in building and embedding custom charts in web applications based on customer’s needs.

Requirements:

Al least PHP 5 with GD library must be installed on your server for the basic functionality while for the most graphically appealing use PHP 5.3.0 with GD-Library is required.

Usage

The best way to present our application is by using examples thus, in this paper, I’ll give you some simple and clear examples on how to use it.

Very important! Please read carefully!

The graph (chart) is only created once on the server (only when the image is created) to prevent server resources from being wasted (or as a means of optimization) and the image is reused when needed.

If, when generating the chart, we specify a folder location, then the image will automatically be created in that folder.

Please refrain from using the force_no_save (default is false) attribute since this forces the creation of the image (output) each time the application is run. However, this option is useful when testing or arranging the layout (force_no_save set to true).

When first using the library a file will be created in the system’s temporary folder, which helps display the chart. If the file is deleted it will be created again. It is very likely that some writing privileges in the respective folder are required, with either CHMOD 755 on some configurations on CHMOD 777 on other (please keep in mind that CHMOD777 is unsafe).

Examples (creation and design):

Let’s presume we have created a PHP file with the following lines:

<?php

include_once "ws_charts.php"; //the ws charts file, needed

$test=new CHART("tmp/"); //will create a standard graphic file in the /tmp folder (from the current path) with the standard size of 600x400 px (pixels).

// add some values to represent something

$test->values="Kids=10,40,30"; // we have created the Kids category and added some values.

//let’s display the chart.

$test->show('line');

The result:

Figure 1. A basic chart.

Let’s presume we want to create a chart, with dimensions different from the default.

<?php

include_once "ws_charts.php"; /*the ws charts file, needed */

$test=new CHART("tmp/",300,200); //will create a standard graphic file in the /tmp folder (from the current path) with the standard size of 300x200 px (pixels). If a file name is specified then it will be used when creating the chart, else the name of the chart will be created from its signature.

// add some values to represent something

$test->values="Kids=10,40,30";

$test->show('line');

The result:

Let’s change the chart background. This can be done in several ways, by adding one of the lines below somewhere above the display line, as follows:

$test->background=”darkblue”; /* we have set a darkblue color background */

$test->background=”white-darkblue”; /* we have set a gradient fill from top to bottom, from white to darkblue */

$test->background=”orange-white-white-red-white-green-cyan-indianred”; /*we have set a background using a more complex gradient fill. The rule is to start from top to bottom. */

$test->background=”puppy.jpg”; /* use an image as a background */

At the end of this paper you’ll find a table that contains the list of the properties that can be used to create custom charts.

Examples (values):

In order to set the values of the chart two methods are available. The first one is by adding them directly.

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",300,200);

$test->values="Kids=10,40,30;Children=-30,40,-20,50

$test->show('line');

The second method (OOP):

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",300,200);

$test->add_value(10,"Kids");

$test->add_value(40,"Kids");

$test->add_value(30,"Kids");

$test->add_value(-30,"Children");

$test->add_value(40,"Children");

$test->add_value(-20,"Children");

$test->add_value(50,"Children");

$test->show('line');

The result:

Figure 2. Output.

In order to delete the values use:

$test->values=””;

For the line, surface and bar type charts the values will be represented by using a two dimensional reference system.

For instance:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",300,200);

$test->add_value(0,0,"Kids");

$test->add_value(10,10,"Kids");

$test->add_value(20,20,"Kids");

$test->add_value(-30,-10,"Children");

$test->add_value(-20,-50,"Children");

$test->add_value(0,0,"Children");

$test->show('line');

This is equivalent to:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",300,200);

$test->values="Kids=0*0,10*10,20*20;Children=-30*-10,-20*-50,0*0";

$test->show('line');

And will generate:

Figure 3. Two dimensional chart.

If we want to display the same values by using the surface chart we only need to modify the last line, from this:

$test->show('line'); //show a line chart

To:

$test->show('surface'); //show a surface chart

Figure 4. Surface chart.

We can also make it a bar chart

$test->show('bar');

Figure 5. Bar chart.

If we want to add a title and some text to the chart this is how to do it:

$test->title=”Here is the title!”; /* this is how to set the title*/

$test->text=”Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.”; /* this is how to add text */

It is recommended to add custom text only when the size of the chart is larger than 400x300 px since, at small sizes, the text will be difficult cu read.

Figure 6. Example of a bar chart with 600x400 px containing a title and some text.

If you want to only show the chart, without any extra information you can. For instance:

$this->showpanel=false; /* will not show the legend */

If no text or title is set, the chart will be expanded within the image.

Examples:

Now that we got to know the basic parameters of the library let’s se some practical examples. As you will see our library contains a set of predefined themes for various types of charts and uses. For example:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",600,400);

$test->add_value(0,9,"Kids");

$test->add_value(10,10,"Kids");

$test->add_value(20,20,"Kids");

$test->add_value(-30,-10,"Children");

$test->add_value(-20,-50,"Children");

$test->add_value(0,5,"Children");

$test->set_theme("enhanced bar");

$test->show('bar');

Output:

Figure 7. Theme usage for an enhanced bar using two axes.

As you can notice in the previous chart one column is in front of another. This is because we used two axes of reference. If one axis is used, like in:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",600,400);

$test->add_value(9,"Kids");

$test->add_value(10,"Kids");

$test->add_value(20,"Kids");

$test->add_value(-10,"Children");

$test->add_value(-50,"Children");

$test->add_value(5,"Children");

$test->set_theme("enhanced bar");

$test->show('bar');

The output will become:

Figure 8. Theme usage for an enhanced bar using one axis.

As you may notice, in the chart above the columns overlay each other. We can also change a series of parameters with this view (like width, transparency, axis width) like in the following example:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",600,400);

$test->values="Kids=30,15,20,25,40;Women=10,40,3,30,10;Children=20,10,30,5,45;Men=15,5,20,10,40"; //some values

$test->background="orange-white-white-white-white-white-white-plum"; // background

$test->add_filter(IMG_FILTER_BRIGHTNESS,5); //luminosity

$test->colors="blue,red,yellow,green"; //color list

$test->linealpha=45; //transparency

$test->show('surface'); //show a surface graph

The result:

Figure 9. Surface chart with transparency

Another example:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",600,400);

$test->values="Kids=30,15,20,25,40;Women=10,40,3,30,10;Children=20,10,30,5,45;Men=15,5,17,10,36"; //values

$test->background="indianred-white-white-white-white-white-white-plum"; // background

$test->set_theme("standard bar"); // chart theme

$test->shaddow_alpha=110; //shadow transparency

$test->shaddow_x=50; // shadow horizontal distance

$test->shaddow_y=-40; // shadow vertical distance

$test->showcoords=true; // show coordinates

$test->show('bar'); // show a bar-type chart

Figure 10. Bar-type chart with shadows.

Another example:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",600,400);

$test->values="Kids=30,15,20,25,40;Women=10,40,3,30,10;Children=20,10,30,5,45;Men=15,5,17,10,36"; // values

$test->background="cyan-white-white-plum";

$test->set_theme("enhanced bar"); // theme

$test->force_no_save=true;

$test->shaddow_alpha=110;

$test->shaddow_x=50;

$test->shaddow_y=-40;

$test->showcoords=true;

$test->show('bar');

The result is:

Figure 11. Bar-type chart with shadows (2).

By changing the width and the height of the bas, as in the example below:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",600,400);

$test->values="Kids=30,15,20,25,40;Women=10,40,3,30,10;Children=20,10,30,5,45;Men=15,5,17,10,36";

$test->background="cyan-white-white-plum";

$test->set_theme("enhanced bar");

$test->linewidth=4; // column width

$test->bar_width_report= 1; // 1 for no distance, 1/2 for one half distange and so on

$test->force_no_save=true;

$test->shaddow_alpha=110;

$test->shaddow_x=15;

$test->shaddow_y=-14;

$test->showcoords=true;

$test->show('bar');

We will get the following chart:

Figure 12. Bar-type chart with high-width columns.

By using the following script:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",600,400);

$test->values="Kids=30;Women=10;Children=20;Men=15";

$test->background="blue-white-white-cyan";

$test->set_theme("enhanced bar");

$test->title_color="white";

$test->shaddow_alpha=110;

$test->emphasize="Men,Women,Kids"; // here we’ve set the categories we wish to emphasize

$test->show('pie'); // pie chart

The result is:

Figure 13. Pie chart.

For the following script:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",600,400);

$test->values="Kids=30,15,20,25,40;Women=10,40,3,30,10;Children=20,10,30,5,45;Men=15,5,17,10,36";

$test->background="pink-white-white-cyan"; // background

$test->set_theme("enhanced line");

$test->shaddow_alpha=110;

$test->shaddow_x=50;

$test->shaddow_y=-40;

$test->showcoords=true; // show coordinates on chart

$test->show('line'); // generate a line chart

Figure 14. Line chart.

If we don’t want to show information about the coordinates or the grid we can use something like

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",600,400);

$test->values="Kids=30,15,20,25,40;Women=10,40,3,30,10;Children=20,10,30,5,45;Men=15,5,17,10,36";

$test->background="pink-white-white-cyan";

$test->set_theme("enhanced line"); // default line chart theme

$test->shaddow_alpha=110;

$test->showcoords=false; //this is where we hide the coordinates

$test->showgrid=false; //this is where we hide the grid

$test->show('line');

Which will generate:

Figure 15. Line chart without information.

The following settings are recommended for charts with more than 100 values.

You can see the next example with 20.000 values.

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",400,200);

for ($i=0;$i<20000;$i++) $test->add_value(rand(0,98),"Kids"); /*aici adaug 20.000 de valori aleatoare pozitive. */

$test->background="pink-white-white-cyan"; /* aici am setat fundalul */

$test->set_theme("server line"); /* aici am setat tema standard pentru tipul de grafic cu bare */

$test->show('line'); /* aici afisiam graficul sub forma de suprafete */

For this script we will get:

Figure 15. Line chart with many values.

For surface charts:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",400,200);

for ($i=0;$i<20000;$i++) $test->add_value(rand(0,98),"Kids"); //we add some random, positive values to populate the chart, for testing

$test->background="pink-white-white-cyan";

$test->set_theme("server line");

$test->show('surface');

We will get:

Figure 16. Graph chart with many values.

We can also apply a slight gradient fill for the surface, like:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",400,200);

for ($i=0;$i<20000;$i++) $test->add_value(rand(0,98),"Kids");

$test->background="pink-white-white-cyan"; // gradient fill background

$test->set_theme("server line"); // the “server line” theme

$test->colors="cyan-blue";

$test->show('surface');

And we will get:

Figure 17. Graph chart with many values and gradient fill.

For any number of parameters we can force the creation of a chart with less parameters. For the “server line” (theme) settings the maximum number of them is equal to the width (in pixels) of the chart. In the following example you can see hot to force the number of values.

!Important

By forcing the number of values we do not ignore any of them. Rather, by using a set algorithm, we will calculate the average (if and where needed). All the values given by the user will be considered.

In the next example you will see how 50.000 values will be shown using 10 coordinates.

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",400,200);

for ($i=0;$i<50000;$i++) $test->add_value(rand(0,98),"Kids"); // here we add 50.000 random, positive values, for testing

$test->background="pink-white-white-cyan";

$test->set_theme("server line"); // the “server line” theme

$test->maxcount=10; //here we’ve set the maximum number of coordinates to be shown

$test->colors="cyan-blue";

$test->show('surface');

The result is:

Figure 18. 50.000 values in 10 coordinates.

In the following example you will see the maxcount property usage..

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",400,200);

$test->values="Kids=30,25,20,6,-10,7,20,46,60,65,80";

$test->background="pink-white-white-cyan";

$test->set_theme("server line");

$test->colors="cyan-blue";

$test->show('surface');

The result:

Figure 19. Without maxcount example.

If we reduce the maxcount value we will get a chart that will use less coordinates.

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",400,200);

$test->values="Kids=30,25,20,6,-10,7,20,46,60,65,80";

$test->background="pink-white-white-cyan";

$test->set_theme("server line");

$test->colors="cyan-blue";

$test->maxcount=6; // a small value

$test->show('surface');

Figure 20. Maxcount example (2).

The chart has been tested for up to 60.000 values. Based on the server’s resources one can theoretically add millions of values.

Furthermore, we can also extract data directly from the database, like in the following example:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",500,300);

$test->connect("host","database","user","password"); // database connection

$test->add_query("select Kids,Men,Women from coord limit 6"); //SQL syntax

$test->background="pink-white-white-white-tan";

$test->set_theme("standard line");

$test->show('line');

The result:

Figure 21. Line chart (with database acces).

Or you can just save the image and use it later:

<?php

include_once "ws_charts.php";

$test=new CHART("tmp/",400,300);

$test->values="Kids=30,25,20,6,-10;Men=7,20,46,60,65,80";

$test->background="pink-white-white-cyan";

$test->set_theme("standard surface");

$image1=$test->save('line');

$image2=$test->save('bar');

$image3=$test->save('surface');

$image4=$test->save('pie');

Image 1

Image 2

Image 3

Image 4

The result is:

Image 1

Image 2

Image 3

Image 4

Property list

values - chart values list;

categories - categories list;

width (def 600) - chart width in pixels;;

height (def 400)- chart height in pixels;;

rx - maximum horizontal distance between the pie chart slices;

ry - maximum vertical distance between the pie chart slices;

title - chart title;

showpanel – hide/ show chart legend;

showshaddow – hide/ show shadow;

linealpha – transparency level of the chart elements (except for the gradient of the surface charts);

showgrid – hide/show coordinates grid;

isgradient - activate surface gradients;

luminosity – brightness (when using images);

background – chart background;

angle - rotate the chart pie by some degrees;

count –indicates the number of elements within the chart;

shaddow_x – horizontal shadow movement;

shaddow_y - vertical shadow movement;

shaddow_alpha– shadow transparency;

linewidth – line width (in pixels);

bar_width_report– 1 means no space between bars, 0.5 means half of the bar width and so forth, when using bar-type charts;

xaxiswidth – X axis width;

yaxiswidth – Y axis width;

pieheight - pie chart width;

fontsize – chart font size;

emphasize – this is used to emphasize a slice of the pie chart;

text – the text to include within the chart;

maxcount – this reduces the number of values to the value specified by the user, without ignoring any;

force_no_save – this atribute allows the creation of the chart each time the application is run. To be used only for testing purposes or be avoided.

panel_background- pie chart legend panel backgroud;

title_color – chart title color;

text_color – chart text color;

showcoords – hide/ show coordinates;

showlinecoords- hide/ show partial grid;

connection - database connection parameters;

font – the font file to be used within the chart;

In order to see the predefined color palette you can look at the allcolors variable (array) where you can add your own custom colors using the RGB (Red-Green-Blue) palette.

This paper and this class has been created by Raul Molnar.

For more information or inquiries please e-mail me at molnarraul@yahoo.com