All data visualized in a chart is stored in a DataTable, which is the PHP representation of the DataTable used by Google's JavaScript API. The DataTable can be seen as a table having a header-row and one or more data-rows. The header-row defines which data-types can be inserted in each column and the columns' IDs, names and properties. The data is then inserted into the data-rows.
Google Chart Tools defines different formats of the DataTable, depending on the chart it is used for. For example if the DataTable is used for a cartesian-chart (like area-, line-, scatter-charts), the DataTable has to have at least two columns, where the data in the first column is used for the data-point's x-values and the data in the other columns as y-values (whereas the data-points are grouped together by the y-values-column).
Please visit Google's Chart Gallery for the actual format of the DataTable for your desired chart-type.
In this API, all classes needed to prepare the charts data and to generate/fill the DataTable are located in the googlecharttools\model package.
After you have instantiated the DataTable, you have to define each column. To do so, create a definition column by calling the constructor of the Column class and pass the created instance to the DataTable's addColumn()-method. The Columns constructor requires at least one $type-parameter, through which the data-type that will be inserted into this column by the data-rows is set. Mostly the charts accept only a few data-types in a column (e. g. in cartesian-chart, the y-values typically have to be numbers or dates/datetimes).
Now that the columns are defined, the actual data can be added to the DataTable. This is done by the DataTable's addRow()-method. The addRow()-method accepts an instance of the Row-class, that represents a single data-row. To each Row, Cells are added which stores the Row's data and (optional) options and properties. The mapping between Columns and Cells is done by the order they are added to the DataTable and Row, respectively (so the first Cell added to the Row has to have the type defined by the first Column added to the DataTable and so on).
Assume we want to create the chart shown on the pie chart's gallery-page. To do so, we need a DataTable having the following format and content:
| Name: Task
Type: string
| Name: Hours per Day Type: Number | |
|---|---|
| Work | 11 |
| Eat | 2 |
| Commute | 2 |
| Watch TV | 2 |
| Sleep | 7 |
Our DataTable has two columns: The first (named "Task") stores string-data, the second (named "Hours per Day") stores number-data:
$activitiesData = new DataTable();
$activitiesData->addColumn(new Column(Column::TYPE_STRING, "t", "Task"));
$activitiesData->addColumn(new Column(Column::TYPE_NUMBER, "h", "Hours per Day"));
After the columns have been defined, the data can be added:
$rowWork = new Row();
$rowWork->addCell(new Cell("Work"))->addCell(new Cell(11));;
$activitiesData->addRow($rowWork);
$rowEat = new Row();
$rowEat->addCell(new Cell("Eat"))->addCell(new Cell(2));
$activitiesData->addRow($rowEat);
$rowCommute = new Row();
$rowCommute->addCell(new Cell("Commute"))->addCell(new Cell(2));
$activitiesData->addRow($rowCommute);
$rowWatch = new Row();
$rowWatch->addCell(new Cell("Watch TV"))->addCell(new Cell(2));
$activitiesData->addRow($rowWatch);
$rowSleep = new Row();
$rowSleep->addCell(new Cell("Sleep"))->addCell(new Cell(7));
$activitiesData->addRow($rowSleep);
As you might have seen, the addCell()-methods can be concatenated, as this method will always return a reference to the Row-object it belongs to.
(I have omitted the PHP-use-statements to keep the example short).
After the data has been added to a DataTable, the chart can be created. GoogleChartTools-PHP provides a separate class for each chart introduced at Google's Chart Gallery. All these chart-classes are located in the googlecharttools\view package and extends the abstract class "Chart".
To instantiate a object of the desired chart-type, you have to pass a identifier to the chart class' constructor. This identifier will be used later in the generated JavaScript-code as part of several identifiers. Therefore, every ID passed to a chart-object has to be a valid JavaScript identifier. That is, no white-spaces are allowed and the ID's first character has to be a letter. I recommend to use the characters A-Z and a-z only to avoid running into problems.
Before the JavaScript-code can be generated, the data (the DataTable) has to be passed to the chart (if this is not done, a CodeGenerationException will be thrown when you try to generate the JavaScript code). This can be done through the Charts constructor's second parameter or via the setData()-method.
All charts come with various set-methods through which the chart's appearance and behaviour can be customized (like setting a title with setTitle()). You will find more information about the supported options for the specific chart in the API-documentation or at the chart's subpage at Google's Chart Gallery.
To continue with our pie chart-example from the gallery, we now want to create the chart itself for our prepared DataTable.
$pieChart = new PieChart("activitiesPie", $activitiesData);
$pieChart->setTitle("My Daily Activities");
As you can see, the chart's ID is "activitiesPie" and a title has been assigned to it.
(I have omitted the PHP-use-statement again to keep the example short).
The last step to do in order to get our chart displayed, is to add it to the PHP-scripts HTML-output. To do this, Google Chart Tools requires two things: First of all, the external JavaScript-API has to be included into the page's header-element and the charts have to be prepared in the header (in a JavaScript script-element), too. Afterwards a div-container has to be added inside the pages-body where the chart will be displayed in.
All code that has to be inserted into the HTML-header is generated by the ChartManager. To do so, the ChartManager has to know each chart that should be displayed on the page. Thus, every chart that will be displayed later on has to be added to the ChartManager through the addChart()-method.
After all charts have been added to the ChartManager, all required code for the HTML-header is generated by calling the ChartManagers getHtmlHeaderCode()-method.
There is nothing more you have to do inside the page's header-element. The last thing to do is to insert the div-container in the HTML-body where you want the chart to be displayed. For this purpose, all charts have the method getHtmlContainer() that returnes this container (with the ID and size set to the chart's properties).
After we have prepared our pie chart's data and the chart itself in the sections above, it can now be inserted into the HTML output:
<html>
<head>
<title>Page with some charts</title>
<!-- Add the generated JavaScript to the page-header -->
<?php echo $manager->getHtmlHeaderCode(); ?>
</head>
<body>
<h1>My page with some charts</h1>
<!-- Add the div-container the chart will be displayed in -->
<?php echo $pieChart->getHtmlContainer(); ?>
</body>
</html>