Graph/design/design.txt

eZ component: Graph, Design
~~~~~~~~~~~~~~~~~~~~~~~~~~~
:Author:   Kore Nordmann
:Revision: $Revision$
:Date:     $Date$

Design Description
==================

Purpose of Graph package
------------------------

The Graph package will be used to generate different chart types from a user
defined set of data. There will be 2D and 3D presentations for each chart
type.

Classes
-------

ezcGraph
	Controller for the generated graphs. Offers factory methods for the other
	classes, handles and dispatches the configuration and actions to the other
	classes.

ezcGraphDataset
	Receives the user data, and stores the configuration for the dataset, like
	color, label, etc. How the data is stored depends on the kind of the
	dataset. The dataset will be extended for algorithms like averaging and 
	polynomial interpolation in the dataset.

ezcGraphChart
	Abstract class, which handles the global charts options like background
	colors or images. Aggregates ezcGraphChartElement for configurable sub
	elements.

ezcGraphChartPie
	Extends ezcGraphChart for pie charts. Offers additional options for pie
	charts like tresh hold under which data is combined.

ezcGraphChartLine
	Extends ezcGraphChart for line charts. Additionally contains two objects
	to represent and configure the axes.

ezcGraphChartElement
	Abstract class to define the interface how to access the configuration
	directives of different chart elements like axes and legend.

ezcGraphChartElementLegend
	Offers configuration options for the charts legend like background color,
	position and size.

ezcGraphChartElementAxe
	Offers the axes configuration options like scaling, lines within the
	graph and labeling. Can do automagic scaling of the axes.

ezcGraphRenderer
	Abstract class which transforms the chart elements like pie segments,
	bars, texts and lines to image primitives depending on the renderer.

ezcGraphRenderer2D
	Creates image primitives for the chart elements considered as two
	dimensional.

ezcGraphRenderer3D
	Creates image primitives for the chart elements considered as three
	dimensional.

ezcGraphDriver
	Offers methods to draw image primitives like textboxes, arcs, rectangles,
	polygons and lines. Needs to be extended for each output format.

ezcGraphDriverGD
	Creates PNG images utilizing the GDlib bundled with PHP.

Implementation
==============

ezcGraphManagager
-----------------

Offers factory methods to build up the wanted graph, containing a chart of a
selected type, a renderer and a driver. Once aggregated the manager offers an
unified interface to configure all parts of the graph.

The manager can aggregate a finite count of datasets and forwards the to the
chart. The chart builds the visual chart elements like pie segments, lines or
bars, which are forwarded to the renderer. They are transformed to image 
primitives accoringly to the selected renderer.

The datasets can be configured individually by the user of the package.

API example
-----------

The following example shows how to use the class: ::

	<?php

	$pie = new ezcGraphPieChart();
	$pie->options->backgroundImage = 'background.png';
	$pie->options->border->color = '#ff0000';
	$pie->title = 'Apple Pie';

	$pie->data['humanoids'] = new ezcGraphArrayDataSet(
		array( 'monkey' => 54, 'ape' => 37, 'human' => 9 ) // adds a new data set
	);
	$pie->data['humanoids']->color['monkey'] = 'blueish'; // setting datapoint color
	$pie->data['humanoids']->highlight( 'monkey' );       // chart type dependent


	$line = new ezcGraphLineChart();
	$line->options->backgroundColor = 'pink';

	$line->data['income'] = new ezcGraphArrayDataSet(
		array( 1990 => 5, 5.1, 5.4, 5.3, 6.9 )
	);
	$line->data['income']->color = 'blue';
	$line->data['income']->symbol = ezcGraph::diamond;

	$line->data['incomeWithTax'] = new ezcGraphArrayDataSet( 
		array( 1990 => 4.9, 5.0, 5.2, 5.1, 6.4 ) 
	);
	$line->data['incomeWithTax']->color = 'red';
	$line->data['incomeWithTax']->symbol = ezcGraph::squareWithChupi;

	// Create a new averaging line
	$line->data['averageIncome'] = new ezcGraphAverageDatasSet( $line->data['income'] [, options] );

	$line->renderer = new ezcGraphRenderer2D();
	$line->driver = new ezcGraphGDDriver();

	$line->render( 500, 200, 'file.png' );

	?>



..
   Local Variables:
   mode: rst
   fill-column: 79
   End:
   vim: et syn=rst tw=79