php-RGraph Reference

What is RGraph?

It's a JavaScript charts library that produces the charts dynamically with JavaScript and the HTML5 canvas tag. It can generate lots of different kinds of visualisations from Bar charts and Line charts through to Meters and Pie charts.

RGraph is quick, attractive, easy to use and free for commercial use. Built on the widely supported canvas element desktop and mobile support is excellent and that allows you to create charts and dashboards that you can use on a wide range of devices. Owing to the fast rendering of the canvas tag, your charts can be up to 10x faster than Flash or SVG based libraries. This means you can create good looking and informative charts and dashboards.

What is php-RGraph?

php-RGraph is an implementation to use RGraph via php-interface. Not only for php-developers it eases the use of RGraph and extends RGraph with all the features php can offer. The interfaces even allows writing pure php-code to create attractive charts without the need having skills for javascript programming.

Main purpose of charts is visualization of data. With php-RGraph you get all the functions to retrieve and use data from mySql-databases, from local files, data from remote or local server, from csv-files and even from Google's sheets. To visualize this data right now php-RGraph "knows" about 580 different chart properties for all charts RGraph has offered and uses this knowledge to build a stable interface to RGraph's javascript libraries. The current (this) version of php-RGraph is based on RGraph's version 523.

php_RGraph Howto Guide

How to use php-RGraph

This guide is should help to understand the structure of php-RGraph and give you some advice howto use php-RGraph on your website.

This Guide has three sections

structure of php-RGraph charts
Using templates
Using php-RGraph on your website

With RGraph you build charts by writing javascript code where as with php-Graph you code your chart objects purely with php. We will now go step by step showing what to do to make php-RGraph run on your site.

structure of php-RGraph charts

Installation of php-RGraph

Installation is straight forward. Once you have downloaded installation file "php-rgraph.zip", unzip it and upload all folders and files to your website into an accessible directory (or if you are using XAMPP, copy the folders and files into accessible directory). "Accessible" means that you may access all files via webserver (e.g. Apache) and browser. Please keep directory structure and naming of php-RGraph (do not rename any folders).

Then check if you can access php-RGraph's documentation using url: "http://your-host/your-install-directory/RGraph/index.html". If this is OK, you may read RGraph's reference and try out the provided samples.

Structure of php-RGraph chart scripts

To give you an idea how all works, you should check some of the provided samples. (please use url "http://your-host/your-install-directory/RGraph/doc/samples.html"). The samples page gives you the option to display a sample and see the php-code for creating the sample. This code illustrates the structur of php-RGraph. A php chart script always has this components:

Define environment
Define chart layout
Define chart's data
Define RGraph chart properties
Build json object for RGraph
Use template for rendering the chart (html creation)

Define environment

Every chart script must know, where resources for charts are located. This is done with embedding (including) script "environment.php". If this script does not work correctly charts cannot be created. See the layout of "environment.php", which shows what information is needed:

<?php
// php-Rgraph root directory
$rgraph_root = "/your-install-directory/RGraph";

// php-Rgraph library
$lib = $_SERVER['DOCUMENT_ROOT'] . $rgraph_root . "/lib/rgraph_chart.php";
if (!file_exists($lib))
 die ("Error: $lib not found");
require_once ($lib);

// directory for templates
$templates =  $_SERVER['DOCUMENT_ROOT'] . $rgraph_root . "/templates/";
if (!file_exists($templates))
    die ("Error: $templates not found");

// directory for RGraphs's javascript library
$rgraph_libraries = $rgraph_root . "/libraries/";

// (optional) directory for Utilities
$utility =   $_SERVER['DOCUMENT_ROOT'] . $rgraph_root . '/lib/util.php';

Note: Variable naming is important for using templates.

Define chart layout

With four lines of code you define major layout of you chart:

$template = "default.php";
$draw_option = "draw();";
$width = "500";
$height = "350";

You define width ("$width") and ("height") of the canvas and what method RGraph should use to draw the chart ("$draw_option"). And you must specify what template is used for rendering the chart.

Define chart's data

You may define chart's data coming from various sources:

define an array of numerical data direcly within your chart script
retrieve data from file
retrieve data from local or remote server
retrieve data from MySql database
retrieve data from csv file
retrieve data from Google sheets
generate data via math formula

php-class rgraph_chart has various methods to support you in providing data for your chart. For more information see the reference guide or have a look at the samples.

Define RGraph chart properties

First step is to define a rgraph_chart object:

$chart = new rgraph_chart($id, $data, $chart_type);

"$id" is required and will define the canvas id (e.g. "cvs").
"$data" defines the data to be used for charts
"$chart_type" sets the desired chart type (e.g. "Pie")
valid types are:
- Bar
- HBar
- Bipolar
- Line
- Pie
- Fuel
- Funnel
- Gauge
- Gantt
- Meter
- Odometer
- Radar
- Rose
- RScatter
- Scatter
- Waterfall

Once you have created a rgraph_chart object you may create a rgraph_options object and define chart properties.

 $options = new rgraph_options($ini-file);
 $options->set_option("title", "My first chart);
  ...

With optional parameter "$ini_file" you may specify an ini-file with pre-defined properties (e.g. font-sizes, colors, font-families, ...etc).

php-RGraph "knows" about 450 different chart properties for almost all charts RGraph has offered. php-class rgraph_options has various methods to support you in providing chart properties, for more information see the reference guide, have a look at the samples or or visit the home of RGraph.

Build json object for RGraph

Once you have created the chart object and its properties you first define the properties ($options object) to the chart object and then create a json object to be used with RGraph:

$chart->set_options($options);
$rgraph_json = $chart->toPrettyString();

Use template for rendering the chart

This is an easy task as the template's directory has been defined with "environment.php" and the template name has been defined already. So your code looks like:

 include_once ($templates . $template);

Using templates

Using Templates

A php-RGraph template is a pre-designed skeleton to build the html code (mainly the script tag) for displaying your chart on your website. It takes variables built by your chart script and "renders" them into html-code. Templates are php files and are stuctured this way:

template header file
template body file

The template header file contains pure php code. This code is used for checking and setting of needed variables. Template header files are mostly common in their functionality and may be used in most of the template body files.

<?php
// check settings
if (! isset($chart))
  die ("Error: rgraph_chart object not defined");
if (! isset($rgraph_json))
      die ("Error: json object is not defined");
$id = $chart->get_id();
$chart_type = $chart->get_chartType();
$script= '<script src="' . $rgraph_libraries . $chart->getScript($chart_type) . '">';
echo $script;

// check for defined values
if (! isset($width))
    $width = 400;
if (! isset($height))
    $height = 250;
if (! isset($draw_option))
    $draw_option = "draw();";
if (! isset($canvas_style))
    $canvas_style = "";
if (! isset($canvas_class))
    $canvas_class = "";
if (! isset($chart_name))
    $chart_name = "chart";
if (! isset($event_script))
    $event_script = "";
if (! isset($chart_script))
    $chart_script = "";

Template body files contain html and php code. This code is used to fill neccessary values for script- and html-tags. Have a look at "default.php", which is used in most of the samples I've created.

<?php

<?php include_once "default_header.php"; ?>

<canvas id="<?php echo $id; ?>" width="<?php echo $width; ?>" height="<?php echo $height; ?>" 
 style=" <?php echo $canvas_style; ?>" class="<?php echo $canvas_class; ?>">
    [No canvas support]>
</canvas>
<script>
jQuery(document).ready(function() {
 
  <?php echo $event_script; ?>
   
  RGraph.reset('<?php echo $id; ?>');  
   
  var <?php echo $chart_name; ?> = new RGraph.<?php echo $chart_type; ?> (
   <?php echo $rgraph_json; ?>).<?php echo $draw_option; ?>

   <?php echo $chart_script; ?>
});
</script>

I've marked all php code in green color - you may have detected that most of all variables have been defined by your chart script.

The red color marked include of "default_header.php" has been used to has setup defaults for missing variables (e.g. for "$chart_name", "event_script" or "canvas_style").

Using php-RGraph on your website

Prepare your webpage

php-RGraph uses for displaying charts the javascript framework jQuery. If you do not use it already you will have to add the javascript library for it. The php-RGraph package has stored this library in directory "../RGraph/js".
In addition to this you must add suitable RGraph javascript libraries for the type and properties of your chart. If you do not know what libraries you need, you may add "RGraph.common.lib.js" which contains all common libraries to be used with charts. So your code to be added may looks like:

<script src="/../js/jquery.min.js" type="text/javascript">
<script src="/../libraries/RGraph.common.lib.js" type="text/javascript">

how it works

php-RGraph uses for displaying charts the javascript framework jQuery. It uses two components for every chart:

the jQuery.load function
a div element for placement of chart

jQuery.load is an Ajax-implementation done by jQuery. With Ajax, web applications can send data to and retrieve from a server asynchronously (in the background) without interfering with the display and behavior of the existing page. To use jQuery.load, you have to code is only a few lines of javascript code:

<script type="text/javascript">
jQuery(document).ready(function() { 
     var url = "../samples/logo.php";  
     jQuery("#show-sample").load( url, function() {
    }); 
});
</script>

jQuery.load loads the url "../samples/logo.php", which is a chart script from my samples. For it you need to add a div element with id "show-sample" which will be then used for displaying the chart:

<div id="show-sample" style="float:right"></div>

You can see the result of this implementation with bar chart displayed on this page. Chart is loaded and displayed, when the page has been loaded (when event "document.ready" triggers).

But you may also display charts interactively using jQuery.load. If you click following link you will cause a display of a meter chart. The original bar-chart will then be replaced by this (meter) chart. How did I do that? I just added these little pieces of code: With the html a-tag for the link, I added an "onlick" attribute to trigger script "show_chart()". This script has been added to the script-tag:

 function show_chart() {
    var url = "../samples/meter.php";  
    jQuery("#show-sample" ).load( url, function() {
   });
}

As it uses the same div-id as for the bar chart it replaces the bar chart.

Using php-RGraph with Joomla!

There is no special consideration with Joomla. You add charts using jQuery.load. Once you have created your chart scripts, you only have to add script-tags for jQuery.load function and div-elements into your article's content. do not forget to add suitable RGraph javascript libraries for the type and properties of your chart. You may add php-RGraph's customized library "RGraph.common.lib.js" - e.g.:

<script src="/../libraries/RGraph.common.libs.js" type="text/javascript">

The easiest way to use php-RGraph is to install and use php-rgraph for Joomla. This is a content plugin, which is based on php-RGraph and lets you create charts without need to do any coding in HTML or php.

If you have installed Joomla extension "jumi" you may add your php-RGraph srcript code into an article using jumi's plugin feature, e.g.:

{jumi [RGraph/samples_jumi/bar_simple.php]}

Note: If you are using ini-files for rgraph_options with jumi, you must provide the file location of ini-files in your environment.php so that you can refer to it in your chart script.

rgraph classes

php-RGraph interfaces to RGraph charts are built with two php classes. Class "rgraph_chart" mainly supports providing data for charts and building json objects for RGraph. Class "rgraph_options" is used to define properties for charts.

rgraph_chart methods
rgraph_options methods

rgraph_chart methods

php-RGraph - class rgraph_chart methods reference

methods of class "rgraph_chart" provided by php-RGraph

"rgraph_chart" offers these main purposes for creating charts based on "RGraph":

support data creation and provisioning for RGraph charts
provide setter and getter methods for rgraph_chart objects
deliver data in json format to be used with RGraph

To get more information besides references shown here, have a look at my samples or visit the home of RGraph.

select a method, then click button to see a short description

Select rgraph_chart method

rgraph_options methods

php-RGraph - class rgraph_options methods reference

methods of class "rgraph_options" provided by php-RGraph

"rgraph_options" offers these main purposes for creating charts based on "RGraph":

support creation and settings of properties for RGraph charts
provide setter and getter methods for rgraph_options objects

Once you have created a rgraph_chart object you may create a rgraph_options object and define chart properties.

 $options = new rgraph_options();
 $options->set_option("property-name", property-value);
 ...

Then you set (define) the chart properties to the rgraph_chart object:

 $chart->set_options($options);

To get more information besides references shown here, have a look at my samples or visit the home of RGraph.

select a method, then click button to see a short description

Select rgraph_options method

rgraph_options reference

php-RGraph - Properties Reference for supported Charts

Select a Chart Type and Property, then click Button to see a short description

Select Chart Type

Properties of all charts implemented by php-RGraph

The javacript framework of RGraph has lots of configuration options for its various chart types. php-RGraph has implemented 580 single properties right now. Fortunately most of the defaults of those 580 properties are so meaningful that one can live with them and should not be deterred by their sheer number.

To get more information besides references shown here, have a look at my samples or visit the home of RGraph.

php_RGraph Utilities

Provided Functions delivered with php-RGraph Package

php-RGraph provides two php functions in addition to the rgraph_chart and rgraph_options classes. These two functions are used to generate data for line or scatter charts.

getDataviaFormula
calculate_Regression

calculate_Regression
getDataviaFormula

calculate_Regression

Description

function does a basic regression analysis. It provides three builtin calculations (all based on the linear regression model) which are described by following functions:

f(x) = ax + b (linear regression)
f(x) = ab^x (exponential regression)
f(x) = ax^b (exponential regression)

Function Call

calculate_Regression($x_values, $y_values, $user_formula=null, $number_format="en", $precision=2)

Parameter

$x_values and $y_values are arrays of numerical values
$user_formula - you may provide own regression formula which then will be used
$number_format - defines the number format of calculated output formula
$precision - defines the decimal scale of calculated output formula

Return Value

an array containing arrays of x/y pairs and a calculated regression formula

Example

$result = calculate_Regression($x_values, $y_values);
$data = $result['values'];
$formula = $result['formula'];

getDataviaFormula

Description

function generates data based on a provided math formula

Function Call

getDataviaFormula($formula, $x_interval=1, $x_min=0, $x_max=5, $max_iterations = 500)

Parameter

$formula - Notation of your formula is derived by script-language "PHP". Pls. read following related information:

You may specify formula with or without equal sign e. g. "y = x * e^x" or "x * e^x"
Independent variable must be set to "x"
Creation of data is controlled by four parameters:
1. "$x_min" - x-value for start of calculation
2. "$x_max" - x-value for end of calculation
3. "$x_interval" - x-increment for calculation
4. "$max_iterations" maximum of calculation steps
5. Calculation stops if either x_max or $max_iterations are reached.
Constants:

Pi (π): "pi"
Euler's number (e): "e"

Operators:

Add: "+"
Subtract: "-"
Multiply: "*"
Divide: "/"
Power: "^"

Functions

sin
sinh
arcsin
asin
arcsinh
asinh
cos
cosh
arccos
acos
arccosh
acosh
tan
tanh
arctan
atan
arctanh
atanh
sqrt
abs
ln
log10
log

Return Value

an associative array with keys "x_values", "y_values" or in case of an error "error". Then "error" has error-infos stored and x_values and y_values are empty (not set).

Example

$data = getDataviaFormula("y=2*e^-(0.2 * x)*sin(x * 2*pi)", 0.1, 0, 20);
$x_values = $data['x_values'];
$y_values = $data['y_values'];
$error = $data['error'];

Download php-RGraph Package

php-RGraph is free software - however you have to adhere to the GPL-license conditions to use it. Please learn more about GPL and free software at GNU Org.

To download php-RGraph please click the download button:

Version 2.0.0 (Build Level 2.0.0.2 - June 9^th 2020)

php-RGraph Package

Acknowledgements

Without the excellent work done by the developers of RGraph my development of php-RGraph would not have been possible. Therefore many thanks to the RGraph development team! - they have produced an outstanding piece of work.