In this part of the tutorial, we will continue from where we left off in Build a Donation Manager Part I. You will learn how to use phpChart, an easy-to-use charting and graphing component, that will seamlessly integrates with phpGrid to create professional-looking, interactive reports for your Donation Manager application.

Before we start, we need to install phpChart. To fully benefit from this tutorial, I recommend you obtain the full version of phpChart since the free version – phpChart Lite – supports only the line chart.

Setup phpChart

It is very important that phpGrid and phpChart be kept in its separate folders. Below is the recommended folder hierarchy.

That’s it.

Report Design

Our report consists of a bar chart and a pie chart followed by a campaign summary datagrid. The datagrid provides the data used to plot the two charts.

phpGrid phpChart Integration

First of all, include both conf.php files (phpGrid and phpChart) at the beginning of the code.

Bar Chart

The first chart we will create is the bar chart. Below is the complete code to create an EMPTY bar chart. We first must create an empty chart is because the campaign data used to plot the chart is not available at the time when the chart is initialized.

Let’s break this baby apart. For the sake of simplicity, we will only cover high level implementation and skip over details where the code is actually self-explanatory.

The first line is the constructor. We pass an empty array, array(null), as the series data because we don’t wish to have any data displayed in the bar chart when it is first rendered. We also give our graph an unique name, BarGraph.

Next, we use the add_plugins() function to include some additional new elements to our bar chart. For this tutorial, we will include the canvasTextRenderer, canvasAxisTickRenderer, and pointLabels plugins. A list of supported plugins can be found here.

In the series default function, be sure to set the renderer type to BarRenderer. We can also set the rendererOptions and pointLabels properties here.

A bar chart has two sets of data – one set for the x axis and another for the y. In this example, the x axis shows the total amount donated to a given campaign and the y axis displays the name of the campaign. We can set the properties for both x and y in one statement by using the set_axes() function. Notice how label, renderer, and ticks properties are used.

Complete documentation for phpChart methods and properties documentation can be found online.

Finally, the last line reserves space for a chart that is 600px high and 400px wide.

Pie Chart

Now let’s move on to the second chart in our report. Below is the entire code to create an EMPTY pie chart.

Let’s do a quick review of the above script.

The first line is the phpChart constructor. Again, the first parameter is an empty array, array(null), as the series data will be loaded later from the Campaign Summary datagrid.

We then set the renderer to PieRenderer and set the its properties using the series default function.

We also want to display the legend to the west, or left, of the chart.

Lastly, we draws the pie chart.

You should now have two blank charts on the page.

Campaign Summary Datagrid

The Campaign datagrid used in this report is the same as what was used to create the Campaign page in Part 1. We just need to add one more thing – an event handler.

In phpGrid, we can add an event handler with the add_event() function. add_event() binds an event handler, which is essentially a JavaScript function, for a specific phpGrid event. A list of possible events can be found here.

Since we must wait for the datagrid to finish loading before sending its data needed to plot the charts, we use the event jqGridLoadComplete.

phpGrid 101 – jqGridLoadComplete Event

jqGridLoadComplete is the last event that occurs once the whole datagrid body has finished loading. Note that the grid body will be reloaded if the user changes the sorting of a column or sets a filter.

Send Data Using Javascript

The following is the Javascript event handler for jqGridLoadComplete.

The Javascript function is the bread and butter that makes our report come alive. It requires a certain level of knowledge of basic Javascript.

Right off the bat, we declare two empty arrays to store x and y axis data points. Since we are now using JavaScript, the syntax will be different from that used in PHP.

The following two lines return data from the datagrid column TotalDonation and CampaignName:

The for loop iterates each column and then stores the results in the x and y axis arrays.

Next, we assign the barData from the datagrid to the bar chart object. Lastly always call jqPlot replot function to load the chart.

phpChart 101 – JavaScript Chart Object Name

The JavaScript chart object name is the same as the name used in the phpChart constructor, e.g. BarChart, prefixed with the underscore character “_”.

We have just completed our bar chart.

Next, we move on to the pie chart. The JavaScript code for this is similar to what we used for the bar chart except that a pie chart does not have x and y axes. Instead, it uses a two-dimensional array.

That’s all there is to it!

Conclusion

Hopefully, after finishing this tutorial, you have become a true campaign master yourself – one who is capable of developing a fully functional donation manager system from start to finish.

* Included in Ultimate edition.