=========================================
An Introduction to the Graph eZ Component
=========================================

:Author: Kore Nordmann
:Date: Tuesday 09 January 2007 10:57:00 pm

.. contents:: Table of Contents

Among the additions to the latest eZ Components 2006.2 release is the Graph
component, which enables you to create bar, line and pie charts. The output
driver mechanism allows you to create different image file types from each
chart, and the available renderers make the chart output customizable from
simple two-dimensional charts to beautiful three-dimensional data projections.

.. image:: ../../images/articles/2007-01-09-graph-intro-simple_3d_pie_chart_large.png
   :alt: Simple 3D pie chart

The different parts of a graph are separated into independently configurable
chart elements, such as the title, the legend, or an axis. This not only allows
you to use different colors or fonts for each chart element, but to also define
their positions and sizes. The main chart elements are the same for all chart
types. Default, overall graph layouts can be defined by palettes, which specify
element colors, symbols, fonts and spacings.

Chart data is held in ezcGraphDataSets, which typically takes the form of
simple arrays. As you will see, statistical operations can be performed on the
data.

A more in-depth tutorial is available, and is referenced throughout this
article. API documentation is also available.


Chart types
===========

The Graph component supports three chart types: bar, line and pie charts.

Bar charts
----------

At the very least, after calling the Graph component and an existing dataset,
the code to create a bar chart consists of only three lines::

    <?php
     
    require_once '../tutorial_autoload.php';
    $wikidata = include '../tutorial_wikipedia_data.php';
     
    // Create a bar chart
    $graph = new ezcGraphBarChart();
    $graph->data['German articles'] = new ezcGraphArrayDataSet( $wikidata['German'] );
    $graph->render( 400, 150, 'example_02.svg' );
     
    ?>

First, you must create the chart object, which also defines the type of chart.
Referencing the existing dataset, you then assign an array with key-value pairs
containing the data. Finally, you render the chart, specifying its size, to a
file.

Line charts
-----------

Line charts are very similar to bar charts, but use other default axis
renderers (see the tutorial for more information) and another display type for
the dataset. Therefore, in order to create line charts, either use the
ezcGraphLineChart class, or set the display type of the desired dataset to
"LINE" (as is done in the example below)::

    <?php
     
    require_once '../tutorial_autoload.php';
     
    $graph = new ezcGraphBarChart();
    $graph->title = 'Random data with average line.';
    $graph->legend->position = ezcGraph::BOTTOM;
    $graph->palette = new ezcGraphPaletteEzBlue();
     
    $graph->xAxis = new ezcGraphChartElementNumericAxis();
    $graph->xAxis->axisLabelRenderer = new ezcGraphAxisBoxedLabelRenderer();
    $graph->xAxis->majorStep = 1;
     
    $data = array();
    for ( $i = 0; $i <= 10; $i++ )
    {
        $data[$i] = mt_rand( -5, 5 );
    }
     
    // Add data
    $graph->data['random data'] = $dataset = new ezcGraphArrayDataSet( $data );
     
    $average = new ezcGraphDataSetAveragePolynom( $dataset, 3 );
    $graph->data[(string) $average->getPolynom()] = $average;
    $graph->data[(string) $average->getPolynom()]->displayType = ezcGraph::LINE;
    $graph->data[(string) $average->getPolynom()]->symbol = ezcGraph::NO_SYMBOL;
     
    $graph->options->fillLines = 150;
     
    $graph->render( 400, 150, 'example_03.svg' );
     
    ?>

This example is far more complex and shows more of the Graph component's
capabilities. As stated earlier, each chart element can be configured
independently. To show this, we set the position of the legend in line 7 to
display at the bottom of the chart. The title, whose text is assigned in line
6, can also be set to use a different font or to display at the bottom of the
chart.

You can create your own palettes to style your charts to fit your own color
scheme. In this case we use the ezBlue palette (on line 8) to automatically
define the colors for the chart. Otherwise, the default palette would use the
color scheme defined by the Tango Desktop Project.

The axis can be of different types to render data differently. For bar and line
charts the default x axis is the labeled axis, which is intended to render
string labels. Because we only have numeric data in this example we use the
numeric axis (on line 10). There is also a date axis and an axis for
logarithmic-scaled data available.

From line 14 to 21 we generate some random data and create a dataset from that.
From this data we create another type of dataset, which tries to determine an
average polynomial of a certain degree, approximating the given data using the
least squares algorithm. We can switch the display type between line and bar
charts, as is done in line 25.

Each dataset has a symbol that is used in the legend in line charts at each
data point and as the general shape for bars in the 3D renderer. Finally, on
line 28, we set an option to shade underneath the lines, then we render the
chart.

.. image:: ../../images/articles/2007-01-09-graph-intro-combined_bar_line_chart_with_random_data_and_average_polynomial_large.png
   :alt: Combined bar line chart with random data and average polynomial

Pie charts
----------

Aside from the obvious display differences, there is only one functional
difference between line / bar charts and pie charts: pie charts can only accept
one dataset. There are also some special configuration options that are
explored further in the tutorial or in the API documentation. The first image
in this article is an example pie chart rendered with the 3D renderer. The
source code for this example is available.


What can be customized?
=======================

Nearly every aspect of a chart is customizable. For example, the 2D and 3D
renderers can both be used with all chart types. For more information on this,
see the tutorial. You can even create your own renderer by extending the
abstract ezcGraphRenderer class.

Driver
------

The output drivers are used to create different image file formats. Graph
supports rendering bitmaps (jpeg, png) using PHP's GD extension, Flash SWF
files using the ming extension and SVG files using the SVG driver.

To use another output driver, simply assign it to the driver property of your
chart object::

    $graph->driver = new ezcGraphFlashDriver();

Each driver has several unique configuration options, but in most cases the
default options will work. You can read about these options in the tutorial or
the API documentation.

Additional modifications
========================

With the GD and SVG drivers, we support element references so that you can link
parts and elements of your chart. The GD driver gives polygon coordinates that
can be used to create HTML image maps. The SVG driver returns the IDs of the
elements so that you can use standard DOM operations to reference or link to
the elements. You can see this link feature live in action on busimess.org.

Creating custom palettes is described in the tutorial. To explore the available
dataset types, axis types, renderers, axis label renderers, drivers and chart
elements, see the complete API documentation, which is supplied for all eZ
Components.