GraphDatabaseTiein/docs/tutorial.txt

==================================
eZ Components - GraphDatabaseTieIn
==================================

.. contents:: Table of Contents
   :depth: 2

Introduction
============

The GraphDatabaseTieIn allows you to directly display results from a database
query in a graph using ezcGraph. All data represented in PDOStatements, for
example returned by the database component, can be displayed.

Class overview
==============

This section gives you an overview of the most important classes.

ezcGraphDatabaseDataSet
  Extends the ezcGraphDataSet to read data from a PDOStatement and prepare it
  for the usage as a dataset in the graph component.

Setup
=====

For the examples we expect a simple database setup, so that we are able to
test our examples. For this we create a table with some statistical data to be
used in the graphs.

.. include:: tutorial/tutorial_insert_data.php
   :literal:

We first include the common autoload file to set up the autoload for
eZ Components. Then, in line 5, we connect to a SQLite memory database, we
later fill up with some data representing a random browser statistic. The
usage idescription of PDO__ and the `database component`__ can be found at 
the dedicated documentation pages.

__ http://php.net/PDO
__ ../Database/tutorial.html#introduction

Usage
=====

Default behaviour
-----------------

To create a simple pie chart we just select the data and add a new dataset,
created from the resulting statement, to a new chart.

.. include:: tutorial/tutorial_simple.php
   :literal:

The query builder we use to create the select query in line 8 to 10 is
described in detail in the `database components documentation`__. In this
example all values from the columns hits and browser are selected from the
table browser_hits. The result of the query is available in $statement after
the query was executed. The $statement object is an instance of the
PDOStatement class.

__ ../Database/tutorial.html#introduction

The creation of charts is described in detail in the `graph components
documentation`__. In this example we create a simple pie chart, set a title 
for the chart and add a new dataset. To directly use a PDOStatement as a data
source an instance of ezcGraphDatabaseDataSet is created with the $statement
as the first parameter. By default the first column is used as index and the 
second column as values for the indices. The result is the pie chart we 
expected.

__ Graph/tutorial.html#introduction

.. image:: img/tutorial_simple.svg.png
   :alt:   Simple pie chart example

Single column
-------------

.. include:: tutorial/tutorial_simple.php
   :literal:

When only a single column is returned by the select query the values are
considered as a zero indexed array. This might be useful to display them in
line or bar charts.

The created data set may be used in the same way like all other data sets, 
which can be seen in line 20 in the example above, where a average polynomial 
data set is created from the database data set. More documentation on average
datasets can be found in the `graph tutorial`__.

__ ../Graph/tutorial.html#average-polynomial-dataset

.. image:: img/tutorial_single.svg.png
   :alt:   Line chart example

Multiple columns
----------------

You also may specify which column should be used as a key and which column
should be used as a value in the created dataset. This is particulary useful
when dealing with more then two columns.

.. include:: tutorial/tutorial_multiple.php
   :literal:

In this example all columns from the table are selected using the \*, but the
array starting in line 21 defines which columns are used for keys and values.
There are two array keys, which are constants defined in ezcGraph, referencing
the name of the column to use.

PDO by default lowercases all column names, see `PDO::setAttribute()`__ for
details. If the column names you pass to the dataset definition array are not
lowercase, you either need to change the PDO::ATTR_CASE attribute of your PDO
connection instance, or lowercase the names passed to the definition array.
Otherwise this will throw ezcGraphDatabaseMissingColumnException exceptions.

Starting at line 28 we change the renderer and enhance the output a bit. This
is described in more detail in the `3D renderer section`__ in the graph 
tutorial.

__ http://php.net/manual/en/pdo.setattribute.php
__ ../Graph/tutorial.html#id2

.. image:: img/tutorial_multiple.svg.png
   :alt:   Pie chart from multiple columns

More information
================

For more information, see the GraphDatabaseTieIn API documentation.

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