The graph components enables you to create line, pie and bar charts. The
output driver mechanism allows you to create different image types from each
chart, and the available renderers make the chart output customizeable from
simple two dimensional charts up to beautiful three dimensional data
projections.
ezcGraph separates different parts of the graph in chart elements, which
display one part of a graph, like the title, the legend or one axis, which are
all independently configurable. This design not only allows you to use
different colors or fonts for each chart element, but also define their
position and size. The main chart elements are the same for all chart types.
For easy definition of a overall layout for your graph you can use palettes,
which define colors, symbols, fonts and spacings.
The data is provided through ezcGraphDataSets which are normally create from
simple arrays, but also can perform statistical operations on the data, as you
will see later.
The following graph is a simple example how to create a pie chart using the
default driver, palette and renderer.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->title = 'Access statistics';
7.
8. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
9. 'Mozilla' => 19113,
10. 'Explorer' => 10917,
11. 'Opera' => 1464,
12. 'Safari' => 652,
13. 'Konqueror' => 474,
14. ) );
15. $graph->data['Access statistics']->highlight['Opera'] = true;
16.
17. $graph->render( 400, 150, 'tutorial_example_01.svg' );
18.
19. ?>
You just create a new chart object, optionally set a title for the chart
assign the data and render it. To assign data you access the dataset container
like an array to define an identifier for your new created dataset. The
dataset in this example is created from an array, where the keys are used as
the identifiers for the data points.
Pie charts accept only one dataset, and the data point identifiers are used to
create the legend. To generate the output the default SVG renderer is used
with the default 2D renderer. For the automatic colorization colors are
applied from the default Tango palette, which uses colors defined by the Tango
Desktop Project: http://tango.freedesktop.org/Tango_Desktop_Project
There are several preparations on the data sets and data points which will be
mentioned during this tutorial, one thing you can do is highlighting one special
data set or point. In line 15 the data point Opera is highlighted which means
in case of pie charts, that it is moved out of the centre by a user
configurable value. See the renderer options class ezcGraphRendererOptions for
details.
There are several pie chart specific configuration options available. In the
eZ components options are always accessed via public properties. For a full
list of all available options have a look at the ezcGraphPieChartOption class.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->title = 'Elections 2005 Germany';
7.
8. $graph->data['2005'] = new ezcGraphArrayDataSet( array(
9. 'CDU' => 35.2,
10. 'SPD' => 34.2,
11. 'FDP' => 9.8,
12. 'Die Gruenen' => 8.1,
13. 'PDS' => 8.7,
14. 'NDP' => 1.6,
15. 'REP' => 0.6,
16. ) );
17.
18. $graph->options->label = '%3$.1f%%';
19. $graph->options->sum = 100;
20. $graph->options->percentThreshold = 0.02;
21. $graph->options->summarizeCaption = 'Others';
22.
23. $graph->render( 400, 150, 'tutorial_example_02.svg' );
24.
25. ?>
In line 16 a sprintf format string is set, which defines how the labels are
formatted. Instead of a sprintf format string you could also set a callback
function which takes care of the label formatting.
In this example we set a custom sum to force the pie chart to show the
complete 100%. The percentTreshHold lets the chart collect all data which has
less percent to be aggregated in one data point. We also could define a absolute
threshold, so that all data below a certain value would be aggregated in one
data point, and the summarizeCaption defines the caption for this aggregated
dataset.
Line charts are created the exactly same way as pie charts, only that they
accept more then one dataset. We are using default driver, palette and
renderer again in this example.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. $wikidata = include 'tutorial_wikipedia_data.php';
5.
6. $graph = new ezcGraphLineChart();
7. $graph->title = 'Wikipedia articles';
8.
9. // Add data
10. foreach ( $wikidata as $language => $data )
11. {
12. $graph->data[$language] = new ezcGraphArrayDataSet( $data );
13. }
14.
15. $graph->render( 400, 150, 'tutorial_example_03.svg' );
16.
17. ?>
There are only two differences compared to the last example. In line we
instantiate an ezcGraphLineChart object instead of a PieChart and beginning in
line 10 we assign multiple datasets from an array we included earlier in the
script. The array in the file tutorial_wikipedia_data.php is build like this:
1. <?php
2. return array(
3. 'English' => array(
4. 'Jan 2006' => 965,
5. 'Feb 2006' => 1000,
6. ...
7. ),
8. ...
9. );
10. ?>
The result is the simple default line chart.
Bar charts are very similar to line charts. They accept the same datasets and
only define another default dataset display type and axis label renderer.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. $wikidata = include 'tutorial_wikipedia_data.php';
5.
6. $graph = new ezcGraphBarChart();
7. $graph->title = 'Wikipedia articles';
8.
9. // Add data
10. foreach ( $wikidata as $language => $data )
11. {
12. $graph->data[$language] = new ezcGraphArrayDataSet( $data );
13. }
14.
15. $graph->render( 400, 150, 'tutorial_example_04.svg' );
16.
17. ?>
As you can see in line 6 we only change the chart constructor again, and the
other default values are applied.
The only difference between bar and line charts is the display type of the
dataset and the axis label renderer of the x axis. You can use one of those
constructors and modify you chart to display one or more datasets mack to the
other display type. The axis label renderer are described later in this
tutorial.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. $wikidata = include 'tutorial_wikipedia_data.php';
5.
6. $graph = new ezcGraphBarChart();
7. $graph->title = 'Wikipedia articles';
8.
9. // Add data
10. foreach ( $wikidata as $language => $data )
11. {
12. $graph->data[$language] = new ezcGraphArrayDataSet( $data );
13. }
14. $graph->data['German']->displayType = ezcGraph::LINE;
15.
16. $graph->options->fillLines = 210;
17.
18. $graph->render( 400, 150, 'tutorial_example_05.svg' );
19.
20. ?>
After creating the datasets we modify one of the datasets in line 14 to change
the default display type to ezcGraph::LINE. To be able to recognize the line
we set one graph option in line 16. The options are accessed like public
properties and in this case we set an option for the graph called "fillLines",
which indicates what transparency value is used tu fill up the space between
data lines and the axis.
There are some more options available for line and bar charts, which configure
how the highlighting of data sets is applied to this chart type.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. $wikidata = include 'tutorial_wikipedia_data.php';
5.
6. $graph = new ezcGraphBarChart();
7. $graph->title = 'Wikipedia articles';
8.
9. // Add data
10. foreach ( $wikidata as $language => $data )
11. {
12. $graph->data[$language] = new ezcGraphArrayDataSet( $data );
13. }
14. $graph->data['German']->displayType = ezcGraph::LINE;
15. $graph->data['German']->highlight = true;
16. $graph->data['German']->highlight['Mar 2006'] = false;
17.
18. $graph->options->fillLines = 210;
19.
20. $graph->options->highlightSize = 12;
21.
22. $graph->options->highlightFont->background = '#EEEEEC88';
23. $graph->options->highlightFont->border = '#000000';
24. $graph->options->highlightFont->borderWidth = 1;
25.
26. $graph->render( 400, 150, 'tutorial_example_06.svg' );
27.
28. ?>
In line 20 the size of the highlight boxes is configured and the lines 22 to
24 change the font configuration for the highlight boxes. The highlighting
basically works the same way as for pie charts, but in line and bar charts it
makes sense to highlight a complete data set and not only one single data
point, due to the fact that there usually more then one data set in line and
bar charts.
ezcGraph offers palettes for the graphs which define the style properties of
the charts elements. The style properties are similar to the ones you know
from CSS:
- color
- background color
- border color
- border width
- padding
- margin
- data set symbols
There are several predefined palettes delivered with ezcGraph and you can
easily modify them or create a palette by yourself.
You can assign each class class extending ezcGraphPalette to the palette
property of your graph. You should do this before adding data sets, because the
datasets request there colors from the palette. If you set the palette after
creating the data sets, the data sets will still use the colors from the
default palette.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. $wikidata = include 'tutorial_wikipedia_data.php';
5.
6. $graph = new ezcGraphBarChart();
7. $graph->palette = new ezcGraphPaletteBlack();
8. $graph->title = 'Wikipedia articles';
9.
10. // Add data
11. foreach ( $wikidata as $language => $data )
12. {
13. $graph->data[$language] = new ezcGraphArrayDataSet( $data );
14. }
15. $graph->data['German']->displayType = ezcGraph::LINE;
16.
17. $graph->options->fillLines = 210;
18.
19. $graph->render( 400, 150, 'tutorial_example_07.svg' );
20.
21. ?>
The generated output differs quite a lot from the output using the default
tango palette. The palette of course changes the colors of background, data
sets and fonts. Additionally it sets a color for the major and minor grid, and
defines a border width and color for the charts elements, defaults to a serif
font and increases the margin between the chart elements.
You can find a complete list of the available palettes in the class tree.
In the last example we assigned a palette object to the palette property of
the graph. You can of course create and modify the object before assigning it.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. require_once 'tutorial_custom_palette.php';
5. $wikidata = include 'tutorial_wikipedia_data.php';
6.
7. $graph = new ezcGraphBarChart();
8. $graph->palette = new tutorialCustomPalette();
9. $graph->title = 'Wikipedia articles';
10.
11. // Add data
12. foreach ( $wikidata as $language => $data )
13. {
14. $graph->data[$language] = new ezcGraphArrayDataSet( $data );
15. }
16. $graph->data['German']->displayType = ezcGraph::LINE;
17.
18. $graph->options->fillLines = 210;
19.
20. $graph->render( 400, 150, 'tutorial_example_08.svg' );
21.
22. ?>
The palette object is created in line 6 and we overwrite some of its
properties. An see an overview on all available properties in the class
documentation for the abstract class ezcGraphPalette. In this example we just
set two colors for the automatic colorization of the datasets and three
symbols for data sets.
Since we assign more then two datasets the first assigned color will be reused
for the third data set. You can see the usage of the symbols in the legend and
on the line chart. The line chart displays a symbol for each data point if the
symbol is set to something different then ezcGraph::NO_SYMBOL which was the
default data set symbol in the default palette.
To fit the graphs easily in your corporate identity the easiest way will be
to create your own palette and use it for the graphs you create. To create a
custom palette you can either extend one of the predefined palettes and
overwrite the properties or extend the abstract palette class.
1. <?php
2.
3. class tutorialCustomPalette extends ezcGraphPalette
4. {
5. protected $axisColor = '#000000';
6.
7. protected $majorGridColor = '#000000BB';
8.
9. protected $dataSetColor = array(
10. '#4E9A0688',
11. '#3465A4',
12. '#F57900'
13. );
14.
15. protected $dataSetSymbol = array(
16. ezcGraph::BULLET,
17. );
18.
19. protected $fontName = 'sans-serif';
20.
21. protected $fontColor = '#555753';
22. }
23.
24. ?>
Each color you do not define defaults to a complete transparent white. As you
can see in the example definition you can define a alpha value besides the
normal RGB values for the colors. After creating a custom palette you can use
it like every other palette before.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. require_once 'tutorial_custom_palette.php';
5. $wikidata = include 'tutorial_wikipedia_data.php';
6.
7. $graph = new ezcGraphBarChart();
8. $graph->palette = new tutorialCustomPalette();
9. $graph->title = 'Wikipedia articles';
10.
11. // Add data
12. foreach ( $wikidata as $language => $data )
13. {
14. $graph->data[$language] = new ezcGraphArrayDataSet( $data );
15. }
16. $graph->data['German']->displayType = ezcGraph::LINE;
17.
18. $graph->options->fillLines = 210;
19.
20. $graph->render( 400, 150, 'tutorial_example_09.svg' );
21.
22. ?>
The example now uses your palette to format the output.
Internally each chart consists of several chart elements which all extends
ezcGraphChartElement. Each of this elements can be configured independently
and represents one of the rendered chart elements. A default chart consists of
the following elements:
- title
- background
- legend
- xAxis
- yAxis
The palette defines the default formatting of the elements. But you cannot
only set foreground and background colors for all the elements, but also
define their position in the chart, or prevent them from being rendered at
all.
Regarding the font configuration we try to fulfill two goals. We want to give
a single point where you should be able to configure the fonts used for the
texts in the chart. On the other hand it should be possible to configure the
used fonts independently for each chart element.
The used solution is, that you can modify the global font configuration by
accessing $graph->options->font, and this takes effect on all chart elements
until you intentionally access the font configuration of one chart element.
The following section shows an example for this.
The chart title element will only be rendered if you manually assign a title.
It can be placed on top or at the bottom of the chart.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteEzBlue();
7. $graph->title = 'Access statistics';
8.
9. $graph->options->font->name = 'serif';
10.
11. $graph->title->background = '#EEEEEC';
12. $graph->title->font->name = 'sans-serif';
13.
14. $graph->options->font->maxFontSize = 8;
15.
16. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
17. 'Mozilla' => 19113,
18. 'Explorer' => 10917,
19. 'Opera' => 1464,
20. 'Safari' => 652,
21. 'Konqueror' => 474,
22. ) );
23.
24. $graph->render( 400, 150, 'tutorial_example_10.svg' );
25.
26. ?>
The chart title is simplest element, so that I can show you some more things
here. In line 9 we change the global font configuration to use a serif font.
In the SCG renderer only the font name is relevant, because it is up to the
client to actually render the bitmap from the defined vector definitions.
In line 11 we access the font configuration of the title element and change it
back to use a sans-serif font. From now on no change on the global font
configuration will affect the titles font configuration. In line 14 we set a
maximum font size, which now only affects the legend and the pie chart
captions.
Besides the font configuration we set an option available for all chart
elements in line 11 - the background color of the current element. This
results in a gray background only for the title element.
With all drivers except the ming (flash) driver you can set background images
with the option to repeat them in the same way you know from CSS definitions.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteEzRed();
7. $graph->title = 'Access statistics';
8.
9. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
10. 'Mozilla' => 19113,
11. 'Explorer' => 10917,
12. 'Opera' => 1464,
13. 'Safari' => 652,
14. 'Konqueror' => 474,
15. ) );
16.
17. $graph->background->image = 'ez.png';
18. $graph->background->position = ezcGraph::BOTTOM | ezcGraph::RIGHT;
19. $graph->background->repeat = ezcGraph::NO_REPEAT;
20.
21. $graph->render( 400, 150, 'tutorial_example_11.svg' );
22.
23. ?>
In line 17 we set a background image, and define it's position in line 18. You
can use every combination of bottom / center / top with left / middle / right
here, and it defaults to center | middle. In line 19 you finally set the type
of repetition of the background image. This can be ezcGraph::NO_REPEAT or a
combination of ezcGraph::HORIZONTAL and ezcGraph::VERTICAL. In this case we
just want a logo to be placed at the bottom right corner of the image.
In the SVG driver the image is in lined using a data URL with the base64
encoded content of the binary image file, so that you do not need to worry
about the locations of your referenced images, when you are using the SVG
output driver.
In the GD driver super sampling is not applied to the images, because they
would look blurred, what you certainly do not want for included bitmap
images.
Of course you could also apply settings on background color, borders, margin
and padding on the background element, too.
The legend is shown by default and automatically generated from the assigned
data. If you want to disable the legend you can do this by just setting it to
false (line 9).
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteEzGreen();
7. $graph->title = 'Access statistics';
8.
9. $graph->legend = false;
10.
11. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
12. 'Mozilla' => 19113,
13. 'Explorer' => 10917,
14. 'Opera' => 1464,
15. 'Safari' => 652,
16. 'Konqueror' => 474,
17. ) );
18.
19. $graph->render( 400, 150, 'tutorial_example_12.svg' );
20.
21. ?>
Besides just hiding the legend you have some more configurations options. It
can be placed at the bottom, left or top in the chart, you can assign a title
for the legend and change the symbol sizes, or the legends size.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteEz();
7. $graph->title = 'Access statistics';
8.
9. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
10. 'Mozilla' => 19113,
11. 'Explorer' => 10917,
12. 'Opera' => 1464,
13. 'Safari' => 652,
14. 'Konqueror' => 474,
15. ) );
16.
17. $graph->legend->position = ezcGraph::BOTTOM;
18. $graph->legend->landscapeSize = .3;
19. $graph->legend->title = 'Legend';
20.
21. $graph->render( 400, 150, 'tutorial_example_13.svg' );
22.
23. ?>
To place the legend at another position of the graph you may set the position
property of the legend like in line 17. If the legend is placed on top or
bottom it will automatically use a landscape format. The space consumed by the
legend is configured by the landscapeSize for the legends in landscape format
and and portraitSize otherwise. The assigned value is the percent of space of
the graph size consumed by the legend. The legend only displays a title if you
manually set it like in line 19.
The axis defines the unit scale in line and bar charts. There are always two
axis - the x-axis and the y-axis, which value ranges are automatically
received from the datasets and are automatically scaled to display adequate
values.
There are different types of values to display - for both, the x-axis and the
y-axis. ezcGraph supports different axis types for different data you give the
graph to render. For normal string keys usually the standard labeled axis is
the right choice. The numeric axis is predestined to display numeric data,
and the date time axis for data associated to dates or times. All of the axis
types can be assigned to each axis.
The labeled axis is default for the x-axis in both - bar and line charts. It
is written to display string labels of datasets and uses the centered label
renderer as default. You saw it already in all the earlier examples with bar
and line charts, but of course it can be used for both axis, too.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. $wikidata = include 'tutorial_wikipedia_data.php';
5.
6. $graph = new ezcGraphLineChart();
7. $graph->options->fillLines = 210;
8. $graph->options->font->maxFontSize = 10;
9. $graph->title = 'Error level colors';
10. $graph->legend = false;
11.
12. $graph->yAxis = new ezcGraphChartElementLabeledAxis();
13. $graph->yAxis->axisLabelRenderer->showZeroValue = true;
14.
15. $graph->yAxis->label = 'Color';
16. $graph->xAxis->label = 'Error level';
17.
18. // Add data
19. $graph->data['colors'] = new ezcGraphArrayDataSet(
20. array(
21. 'info' => 'blue',
22. 'notice' => 'green',
23. 'warning' => 'orange',
24. 'error' => 'red',
25. 'fatal' => 'red',
26. )
27. );
28.
29. $graph->render( 400, 150, 'tutorial_example_14.svg' );
30.
31. ?>
You could argue, if such a chart is really useful - but it works. Instead of
using numeric values colors are assigned, when creating the data set. The
labeled axis uses the values in the order they are assigned. In line 11 it is
the first time we actually touch the axis label renderer. The axis label
renderer describe how the labels are placed on the axis - the labeled axis
uses the centered axis label renderer by default, which places the labels
centered next to the steps on the axis. The setting in line 11 forces the
renderer to show the zero value, even though it interferes with the axis.
The numeric axis is the default for the y axis. It was build to display
numeric data and find automatically a good scaling for all values you may
assign. Of course you can configure all scaling parameters manually.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. $wikidata = include 'tutorial_wikipedia_data.php';
5.
6. $graph = new ezcGraphLineChart();
7. $graph->title = 'Some random data';
8. $graph->legend = false;
9.
10. $graph->xAxis = new ezcGraphChartElementNumericAxis();
11.
12. $graph->xAxis->min = -15;
13. $graph->xAxis->max = 15;
14. $graph->xAxis->majorStep = 5;
15.
16. $data = array(
17. array(),
18. array()
19. );
20. for ( $i = -10; $i <= 10; $i++ )
21. {
22. $data[0][$i] = mt_rand( -23, 59 );
23. $data[1][$i] = mt_rand( -23, 59 );
24. }
25.
26. // Add data
27. $graph->data['random blue'] = new ezcGraphArrayDataSet( $data[0] );
28. $graph->data['random green'] = new ezcGraphArrayDataSet( $data[1] );
29.
30. $graph->render( 400, 150, 'tutorial_example_15.svg' );
31.
32. ?>
In this example we force both axis to be a numeric axis in line 10 of the
example. In the lines 12 to 15 we manually set the scaling options for the x
axis. We don't set a minorStep size here, so it will be automatically
calculated from the other values, as all the values are automatically
calculated for the y axis. The we create some random data and create two
datasets from it as usual.
The example shows one advantage of numeric axis over labeled axis for numeric
data. The axis are moved away from the charts border to display the negative
values below / left of the axis.
Earlier in this tutorial we used a labeled axis for date time data on the x
axis in the wikipedia examples. This works fine for evenly distributed
time spans. For other data you should use the date time axis.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphLineChart();
6. $graph->options->fillLines = 210;
7. $graph->title = 'Concurrent requests';
8. $graph->legend = false;
9.
10. $graph->xAxis = new ezcGraphChartElementDateAxis();
11.
12. // Add data
13. $graph->data['Machine 1'] = new ezcGraphArrayDataSet( array(
14. '8:00' => 3241,
15. '8:13' => 934,
16. '8:24' => 1201,
17. '8:27' => 1752,
18. '8:51' => 123,
19. ) );
20. $graph->data['Machine 2'] = new ezcGraphArrayDataSet( array(
21. '8:05' => 623,
22. '8:12' => 2103,
23. '8:33' => 543,
24. '8:43' => 2034,
25. '8:59' => 3410,
26. ) );
27.
28. $graph->data['Machine 1']->symbol = ezcGraph::BULLET;
29. $graph->data['Machine 2']->symbol = ezcGraph::BULLET;
30.
31. $graph->render( 400, 150, 'tutorial_example_16.svg' );
32.
33. ?>
You can use timestamps or date time strings as data set keys. The strings will
be converted using PHPs strtotime() function.
As mentioned earlier in this tutorial the axis label renderer defines where a
label is drawn relatively to the step on the axis. You already saw examples
for all available axis label renderers, but I want to mention them again:
ezcGraphAxisExactLabelRenderer
This is the default renderer for the numeric axis. The labels are drawn
directly below the axis step. This may look strange some times, because it
is of course not possible to always draw all labels of one axis on one side
of the step, because the last or first label would exceed the available
space for the axis, so that it is rendered on the other side.
ezcGraphAxisCenteredLabelRenderer
This renderer is default for the labeled axis in line charts and draws the
label centered next to the step. Therefor this renderer omits the label for
initial step on the axis (0, 0), but this can be forced as shown in example
14. The label is omitted, because it would interfere with the axis or the
labels of the other axis, and probably not really readable.
ezcGraphAxisBoxedLabelRenderer
This is the default renderer for the labeled axis in bar charts. The steps
on the axis and the grid is not drawn at the position of the label, but
between two labels. This helps to recognize which bars belongs together.
The label is rendered centered between two of those steps on the axis.
The data sets receive the data from the user and offer a defined interface for
ezcGraph to access the users data.
The array data set was used for all examples until now, because it is the
simplest way to provide data for ezcGraph.
The average dataset uses an existing dataset with numeric keys and build a
polynomial which interpolates the data points in the given data set using the
least squares algorithm.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphLineChart();
6. $graph->title = 'Some random data';
7. $graph->legend->position = ezcGraph::BOTTOM;
8.
9. $graph->xAxis = new ezcGraphChartElementNumericAxis();
10.
11. $data = array();
12. for ( $i = 0; $i <= 10; $i++ )
13. {
14. $data[$i] = mt_rand( -5, 5 );
15. }
16.
17. // Add data
18. $graph->data['random data'] = $dataset = new ezcGraphArrayDataSet( $data );
19.
20. $average = new ezcGraphDataSetAveragePolynom( $dataset, 3 );
21. $graph->data[(string) $average->getPolynom()] = $average;
22.
23. $graph->render( 400, 150, 'tutorial_example_17.svg' );
24.
25. ?>
We use again two numeric axis, because we only display numeric data in this
example. First we create a normal array dataset from some random generated
data in line 14. We assign this data set to the chart , to see how well the
polynomial fits the random data points.
In line 20 we create a ezcGraphDataSetAveragePolynom from the random data with
a maximum degree of the polynomial of 3 (which is also the default value). You
can directly access the polynomial, what we use to set the name of the data set
to the data sets polynomial, when we add the data set to the graph.
For the computation of the polynomial a equitation has to be solved where the
size of the matrix is equal to the point count of the used dataset. Be
careful with data sets with large point count. Because this could mean that
ezcGraph will consume a lot of memory and processing power.
The renderer transform chart primitives into image primitives, that means that
things like a pie segment including labels, highlight etc. will be transformed
into some text strings, circle sectors and symbols to link the text to the
according circle sector.
ezcGraph comes with the default 2D renderer used in all of the above examples
and a 3D renderer which renders the chart elements in a pseudo 3D isometric
manner.
All examples until now used the default 2D renderer. But there are several
renderer specific options, which were not yet shown.
All the options specially available for bar charts are available for all
current renderers.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. $wikidata = include 'tutorial_wikipedia_data.php';
5.
6. $graph = new ezcGraphBarChart();
7. $graph->title = 'Wikipedia articles';
8.
9. // Add data
10. foreach ( $wikidata as $language => $data )
11. {
12. $graph->data[$language] = new ezcGraphArrayDataSet( $data );
13. }
14. $graph->data['German']->displayType = ezcGraph::LINE;
15. $graph->data['German']->highlight = true;
16. $graph->data['German']->highlight['Mar 2006'] = false;
17.
18. $graph->options->fillLines = 210;
19.
20. $graph->options->highlightSize = 12;
21.
22. $graph->options->highlightFont->background = '#EEEEEC88';
23. $graph->options->highlightFont->border = '#000000';
24. $graph->options->highlightFont->borderWidth = 1;
25.
26. // $graph->renderer = new ezcGraphRenderer2d();
27.
28. $graph->renderer->options->barMargin = .2;
29. $graph->renderer->options->barPadding = .2;
30.
31. $graph->renderer->options->dataBorder = 0;
32.
33. $graph->render( 400, 150, 'tutorial_example_18.svg' );
34.
35. ?>
As the 2d renderer is the default renderer we do not need to force this
renderer. In the lines 28 and 29 we configure the width used fr the bars. The
option barMargin defines the distance between the sets of bars associated to
one value. The barPadding in line 29 defines the distance between bars in one
block.
The option dataBorder in line 31 is available for all chart types in all
renderers and defines the transparency used to draw darkened borders around
bars or pie segments. In this case we do not draw any border.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteEzRed();
7. $graph->title = 'Access statistics';
8. $graph->legend = false;
9.
10. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
11. 'Mozilla' => 19113,
12. 'Explorer' => 10917,
13. 'Opera' => 1464,
14. 'Safari' => 652,
15. 'Konqueror' => 474,
16. ) );
17. $graph->data['Access statistics']->highlight['Explorer'] = true;
18.
19. // $graph->renderer = new ezcGraphRenderer2d();
20.
21. $graph->renderer->options->moveOut = .2;
22.
23. $graph->renderer->options->pieChartOffset = 63;
24.
25. $graph->renderer->options->pieChartGleam = .3;
26. $graph->renderer->options->pieChartGleamColor = '#FFFFFF';
27. $graph->renderer->options->pieChartGleamBorder = 2;
28.
29. $graph->renderer->options->pieChartShadowSize = 5;
30. $graph->renderer->options->pieChartShadowColor = '#BABDB6';
31.
32. $graph->render( 400, 150, 'tutorial_example_19.svg' );
33.
34. ?>
One of the pie chart specific options is moveOut in line 21, which defines how
much space of the pie chart is used to move the pie chart segments out the
center on highlight. The pieChartOffset in line 23 defines the initial angle
for the pie chart segments, which enables you to rotate the pie chart.
In the lines 25 to 27 a gleam on the pie chart is defined, with a transparency
value in line 25, which disables the gleam, when set to 0, a color in line 26
and the distance from the outer border of the pie chart in line 27.
In line 29 and 30 a shadow with custom offset and color is added to the pie
chart.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteBlack();
7. $graph->title = 'Access statistics';
8. $graph->options->label = '%2$d (%3$.1f%%)';
9.
10. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
11. 'Mozilla' => 19113,
12. 'Explorer' => 10917,
13. 'Opera' => 1464,
14. 'Safari' => 652,
15. 'Konqueror' => 474,
16. ) );
17. $graph->data['Access statistics']->highlight['Explorer'] = true;
18.
19. // $graph->renderer = new ezcGraphRenderer2d();
20.
21. $graph->renderer->options->moveOut = .2;
22.
23. $graph->renderer->options->pieChartOffset = 63;
24.
25. $graph->renderer->options->pieChartGleam = .3;
26. $graph->renderer->options->pieChartGleamColor = '#FFFFFF';
27. $graph->renderer->options->pieChartGleamBorder = 2;
28.
29. $graph->renderer->options->pieChartShadowSize = 3;
30. $graph->renderer->options->pieChartShadowColor = '#000000';
31.
32. $graph->renderer->options->legendSymbolGleam = .5;
33. $graph->renderer->options->legendSymbolGleamSize = .9;
34. $graph->renderer->options->legendSymbolGleamColor = '#FFFFFF';
35.
36. $graph->renderer->options->pieChartSymbolColor = '#BABDB688';
37.
38. $graph->render( 400, 150, 'tutorial_example_20.svg' );
39.
40. ?>
Besides the gleam added in the last example, you can additionally define a
gleam for the legend symbols. In line 32 the transparency of the gleam is
defined, and then the size of the gleam. The gleam works for all symbol types
- except the circle, where gleam does not make sense, and the size defines the
percent of size of the gleam compared to the symbol size. In the last step in
line 34 the gleam color is defined.
The three dimensional renderer can renderer all charts renderer with the 2d
renderer, and use all the drivers used with the 2d renderer. The only
difference is that it generates isometric three dimensional views on the data
instead of simple two dimensional views.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->title = 'Access statistics';
7.
8. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
9. 'Mozilla' => 19113,
10. 'Explorer' => 10917,
11. 'Opera' => 1464,
12. 'Safari' => 652,
13. 'Konqueror' => 474,
14. ) );
15. $graph->data['Access statistics']->highlight['Opera'] = true;
16.
17. $graph->renderer = new ezcGraphRenderer3d();
18.
19. $graph->render( 400, 150, 'tutorial_example_21.svg' );
20.
21. ?>
This examples uses the same code like the first example with only one
modification, the changed renderer in line 17. You can use the 3d renderer
with all the above examples by adding this single line.
The options in the 2d renderer example still work, so that we reuse the above
example, using the 3d renderer and extend it with some more 3d renderer
specific options.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteEzRed();
7. $graph->title = 'Access statistics';
8. $graph->options->label = '%2$d (%3$.1f%%)';
9.
10. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
11. 'Mozilla' => 19113,
12. 'Explorer' => 10917,
13. 'Opera' => 1464,
14. 'Safari' => 652,
15. 'Konqueror' => 474,
16. ) );
17. $graph->data['Access statistics']->highlight['Explorer'] = true;
18.
19. $graph->renderer = new ezcGraphRenderer3d();
20.
21. $graph->renderer->options->moveOut = .2;
22.
23. $graph->renderer->options->pieChartOffset = 63;
24.
25. $graph->renderer->options->pieChartGleam = .3;
26. $graph->renderer->options->pieChartGleamColor = '#FFFFFF';
27.
28. $graph->renderer->options->pieChartShadowSize = 5;
29. $graph->renderer->options->pieChartShadowColor = '#000000';
30.
31. $graph->renderer->options->legendSymbolGleam = .5;
32. $graph->renderer->options->legendSymbolGleamSize = .9;
33. $graph->renderer->options->legendSymbolGleamColor = '#FFFFFF';
34.
35. $graph->renderer->options->pieChartSymbolColor = '#55575388';
36.
37. $graph->renderer->options->pieChartHeight = 5;
38. $graph->renderer->options->pieChartRotation = .8;
39.
40. $graph->render( 400, 150, 'tutorial_example_22.svg' );
41.
42. ?>
The pieChartGleamBorder option was removed, because it looks a bt strange on
3d pie charts, but it of course works, too. In the lines 37 and 38 there are
two new options, which configure the 3d effect of the pie chart. The first one
defines the height of the pie and the second one defines the percent of
shrinkage compared to the maximum possible vertical size of a pie chart.
3d bar charts use the symbol of the dataset as the basic shape for the
rendered bar, so that you can renderer cylinders or cuboids in your charts
with ezcGraph.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4. $wikidata = include 'tutorial_wikipedia_data.php';
5.
6. $graph = new ezcGraphBarChart();
7. $graph->palette = new ezcGraphPaletteEz();
8. $graph->title = 'Wikipedia articles';
9.
10. // Add data
11. foreach ( $wikidata as $language => $data )
12. {
13. $graph->data[$language] = new ezcGraphArrayDataSet( $data );
14. }
15. $graph->data['English']->symbol = ezcGraph::NO_SYMBOL;
16. $graph->data['German']->symbol = ezcGraph::BULLET;
17. $graph->data['Norwegian']->symbol = ezcGraph::DIAMOND;
18.
19. $graph->renderer = new ezcGraphRenderer3d();
20.
21. $graph->renderer->options->legendSymbolGleam = .5;
22. $graph->renderer->options->barChartGleam = .5;
23.
24. $graph->render( 400, 150, 'tutorial_example_23.svg' );
25.
26. ?>
The symbols for this examples are set as described earlier in this tutorial.
Two single options are set to improve the displayed image. The
legendSybolGleam is activated with the default color, and barChartGleam is
activated to get more beautiful bars. You could also set the factor the top
and sides of the bars are darkened, using the options barDarkenSide and
barDarkenTop, but leaving them as the default value is just fine.
The line chart example with 3d renderer is again quite simple. It reuses the
example with the statistical data and the approximation polygon.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphLineChart();
6. $graph->title = 'Some random data';
7. $graph->legend->position = ezcGraph::BOTTOM;
8. $graph->options->fillLines = 210;
9.
10. $graph->xAxis = new ezcGraphChartElementNumericAxis();
11.
12. $data = array();
13. for ( $i = 0; $i <= 10; $i++ )
14. {
15. $data[$i] = mt_rand( -5, 5 );
16. }
17.
18. // Add data
19. $graph->data['random data'] = $dataset = new ezcGraphArrayDataSet( $data );
20.
21. $average = new ezcGraphDataSetAveragePolynom( $dataset, 3 );
22. $graph->data[(string) $average->getPolynom()] = $average;
23.
24. $graph->renderer = new ezcGraphRenderer3d();
25.
26. $graph->render( 400, 150, 'tutorial_example_24.svg' );
27.
28. ?>
Again the only thing which is changed compared to the example above is the use
of the 3D renderer, and the fillLines options, which simply shows, that this
options works here, too.
The driver gets the image primitives from the renderer and creates the final
image from the image primitives. Different drivers can be used depending on
the available extensions and the wanted output format.
There are some driver specific options, you can learn about in the API
documentation of each driver, and which are described in this section of the
tutorial.
The default driver generates SVG images, a standardized XML vector graphic
format, which most of the modern browsers can display natively, except the
Internet Explorer. But even for the Internet Explorer there are several
plugins available, from Corel , or Adobe , which enable the browser to
render SVGs. There are several advantages using the SVG driver. The XML
documents can easily be modified later, and compressed effectively. The driver
is very fast, and all shapes are displayed exactly and anti aliased. You may
define templates, an existing SVG document, where the generated chart is
added into a dedicated group, and configure all rendering options of the SVG
document. The example below shows such a template created with Inkscape and a
simple pie chart rendered into this template.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->background->color = '#FFFFFFFF';
7. $graph->title = 'Access statistics';
8. $graph->legend = false;
9.
10. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
11. 'Mozilla' => 19113,
12. 'Explorer' => 10917,
13. 'Opera' => 1464,
14. 'Safari' => 652,
15. 'Konqueror' => 474,
16. ) );
17.
18. $graph->renderer = new ezcGraphRenderer3d();
19. $graph->renderer->options->pieChartShadowSize = 10;
20. $graph->renderer->options->pieChartGleam = .5;
21. $graph->renderer->options->dataBorder = false;
22. $graph->renderer->options->pieChartHeight = 16;
23. $graph->renderer->options->legendSymbolGleam = .5;
24.
25. $graph->driver->options->templateDocument = 'template.svg';
26. $graph->driver->options->graphOffset = new ezcGraphCoordinate( 25, 40 );
27. $graph->driver->options->insertIntoGroup = 'ezcGraph';
28.
29. $graph->render( 400, 200, 'tutorial_example_24.svg' );
30.
31. ?>
The only drawback of SVG is, that it is impossible to determine or define the
exact width of text strings, so that the driver can only estimate the size of
text in the resulting image, which will sometimes fail slightly.
The GD driver is for now the choice to generate bitmap images. It does support
different font types, if available on your PHP installation, like True Type
Fonts, using the FreeType 2 library or the native TTF support, and PostScript
Type 1 fonts. We use super sampling to enable basic anti aliasing in the gd
driver, what means, that the image is rendered twice as big with default
settings and resized later back to requested size. This is used for all image
primitives except texts and images.
But there are some drawbacks in the GD library we cannot work around with
reasonable effort:
- Transparent pie segments look very strange with GD
- There is no native support for gradients in GD
- Font anti aliasing depends on the used font extension. Use the FreeType 2
library if available, what also is the default behavior.
There are some special configuration options for the GD driver. You can
specify the super sampling rate used, and use different output formats if
available with your bundled GD extension, like in the lines 13 to 15 in the
following example.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteEzGreen();
7. $graph->title = 'Access statistics';
8. $graph->legend = false;
9.
10. $graph->driver = new ezcGraphGdDriver();
11. $graph->options->font = 'tutorial_font.ttf';
12.
13. $graph->driver->options->supersampling = 1;
14. $graph->driver->options->jpegQuality = 100;
15. $graph->driver->options->imageFormat = IMG_JPEG;
16.
17. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
18. 'Mozilla' => 19113,
19. 'Explorer' => 10917,
20. 'Opera' => 1464,
21. 'Safari' => 652,
22. 'Konqueror' => 474,
23. ) );
24.
25. $graph->render( 400, 200, 'tutorial_example_25.jpg' );
26.
27. ?>
ezcGraph can use ext/ming to generate flash swf files. This driver only
supports Palm Format Fonts (.fdb) and can only handle a very small subset of
JPEGs as images for the chart background. On the other hand Flash is a vector
graphic format too, so that the images are pretty small and can be compressed
effectively. The font size estimation is exact and it support gradients and
all types of used shapes. Since ming only supports flash in version 4, it is
not possible to use transparent backgrounds.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->title = 'Access statistics';
7. $graph->legend = false;
8.
9. $graph->driver = new ezcGraphFlashDriver();
10. $graph->options->font = 'tutorial_font.fdb';
11.
12. $graph->driver->options->compression = 7;
13.
14. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
15. 'Mozilla' => 19113,
16. 'Explorer' => 10917,
17. 'Opera' => 1464,
18. 'Safari' => 652,
19. 'Konqueror' => 474,
20. ) );
21.
22. $graph->renderer = new ezcGraphRenderer3d();
23. $graph->renderer->options->pieChartShadowSize = 10;
24. $graph->renderer->options->pieChartGleam = .5;
25. $graph->renderer->options->dataBorder = false;
26. $graph->renderer->options->pieChartHeight = 16;
27. $graph->renderer->options->legendSymbolGleam = .5;
28.
29. $graph->render( 400, 200, 'tutorial_example_27.swf' );
30.
31. ?>
The ming driver does not have a lot of available options. You need to take
care of a valid font file, like you can see in line 10, and you can set the
compression rate used by the ming driver to compress the resulting swf. As a
result you get a beautiful flash image.
Element references describe a mechanism to later modify and reference certain
chart elements to add links, menus or other interactive features in your
application. The type of the references depend on the driver you use to render
chart. The GD driver will return points describing polygons, so that you can
generate image maps from the data, while the SVG driver will return the IDs of
the according XML elements.
The element references are created in the renderer, where the renderer known
about the context of the chart element and the driver returns the data the
renderer should reference. This way it is also possible to reference legend
symbols and text, data labels and of course the actual data elements.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteEz();
7. $graph->title = 'Access statistics';
8.
9. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
10. 'Mozilla' => 19113,
11. 'Explorer' => 10917,
12. 'Opera' => 1464,
13. 'Safari' => 652,
14. 'Konqueror' => 474,
15. ) );
16.
17. $graph->render( 400, 200, 'tutorial_example_28.svg' );
18.
19. // Get element references from renderer
20. $elements = $graph->renderer->getElementReferences();
21.
22. // Add links to charts
23. $dom = new DOMDocument();
24. $dom->load( 'tutorial_example_28.svg' );
25. $xpath = new DomXPath( $dom );
26.
27. // Link chart elements
28. foreach( $elements['data']['Access statistics'] as $objectName => $ids )
29. {
30. foreach ( $ids as $id )
31. {
32. echo "Link: $id\n";
33. $element = $xpath->query( '//*[@id = \'' . $id . '\']' )->item( 0 );
34.
35. $element->setAttribute( 'style', $element->getAttribute( 'style' ) . ' cursor: pointer;' );
36. $element->setAttribute( 'onclick', 'top.location = \'/detailedData.php?browser=' . $objectName . '\'' );
37. }
38. }
39.
40. // Link legend elements
41. foreach( $elements['legend'] as $objectName => $ids )
42. {
43. foreach ( $ids as $id )
44. {
45. echo "Link: $id\n";
46. $element = $xpath->query( '//*[@id = \'' . $id . '\']' )->item( 0 );
47.
48. $element->setAttribute( 'style', $element->getAttribute( 'style' ) . ' cursor: pointer;' );
49. $element->setAttribute( 'onclick', 'top.location = \'/detailedData.php?browser=' . $objectName . '\'' );
50. }
51. }
52.
53. $dom->save( 'tutorial_example_28.svg' );
54.
55. ?>
After creating a very simple chart like in the first example we start
modifying the document using PHPs DOM extension. First we load the document
and create a XPath query object on it.
The array returned by ezcGraphRenderer::getElementReferences() contains two
arrays, one for the legend elements and one for the datasets. The data array
itself contains all datasets with all data points, which contain all valid
references depending on driver and chart type. In a svg document with a 2d
renderer you will receive one ezcGraphCircleSector_[0-9]+ and one
ezcGraphTextBox_[0-9]+ element, but this may change with other rendering
options.
In the loop we now receive the element for the id using XPath, to modify its
attributes. $dom->getElementByID() does not work here, because these elements
are not indexed by default for non HTML documents. We only modify the style
attribute a bit, to change the cursor to a pointer, like expected for links
and add a JavaScript onclick event handler to link to specified address. You
get a resulting SVG image where you can click on the chart and legend
elements.
In the case of GD we want to generate an image map instead of modifying the
generated image. The driver returns polygons described by their edge
coordinates, which you can use to generate an image map.
1. <?php
2.
3. require_once 'tutorial_autoload.php';
4.
5. $graph = new ezcGraphPieChart();
6. $graph->palette = new ezcGraphPaletteEzGreen();
7. $graph->title = 'Access statistics';
8.
9. $graph->driver = new ezcGraphGdDriver();
10. $graph->options->font = 'tutorial_font.ttf';
11.
12. $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
13. 'Mozilla' => 19113,
14. 'Explorer' => 10917,
15. 'Opera' => 1464,
16. 'Safari' => 652,
17. 'Konqueror' => 474,
18. ) );
19.
20. $graph->render( 400, 200, 'tutorial_example_29.png' );
21.
22. $elements = $graph->renderer->getElementReferences();
23.
24. ?>
25. <html>
26. <head><title>Image map example</title></head>
27. <body>
28. <map
29. name="ezcGraphPieChartMap">
30. <?php
31. foreach ( $elements['legend'] as $objectName => $polygones )
32. {
33. foreach ( $polygones as $shape => $polygone )
34. {
35. $coordinateString = '';
36. foreach ( $polygone as $coordinate )
37. {
38. $coordinateString .= sprintf( '%d,%d,', $coordinate->x, $coordinate->y );
39. }
40.
41. printf( "<area shape=\"poly\" coords=\"%s\" href=\"/detailedData.php?browser=%s\" alt=\"%s: %s\" title=\"%s: %s\" />\n",
42. substr( $coordinateString, 0, -1 ),
43. $objectName,
44. $shape, $objectName,
45. $shape, $objectName
46. );
47. }
48. }
49. ?>
50. </map>
51. <img
52. src="tutorial_example_29.png"
53. width="400" height="200"
54. usemap="#ezcGraphPieChartMap"
55. </body>
56. </html>
57. <?php
58. ?>
59.
For the sake of a short example we only link the legend elements here. After
generating the basic image, we request the element references from the
renderer and use the to create the image map starting in line 30. we just
iterate over the legend elements, which all may contain more then one
polygon. In this case we receive one polygon for the symbol in the legend and
another one for the legend text.
In the lines 35 to 39 we build the coordinate string image map expects from
the coordinate pairs we receive from the gd driver. The coordinate array
consists of ezcGraphCoordinate objects, which are a simple structure containing
two public properties, the x and the y coordinate as float values. We use this
coordinate string create the polygon area elements in line 41.
After assigning the image map to the image you got a linked legend in your
generated bitmap.
