What is RGraph?

rgraph logo 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 V5.28.

 

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 four sections
  1. structure of php-RGraph charts
  2. Using templates
  3. Using php-RGraph on your website
  4. Using php-RGraph with Joomla!

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-V2.1.3.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:
  1. Define environment
  2. Define chart layout
  3. Define chart's data
  4. Define RGraph chart properties
  5. Build json object for RGraph
  6. 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: Nameing of variables is important for using templates.

Since version 2.1.1 of php-RGraph, all classes are integrated in namespaces, so it is necessary to define the namespaced classes in addition to include file "environment.php" with "use" instructions:
include_once "environment.php";
use phpRGraph\rgraph_chart;
use phpRGraph\rgraph_options;

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:
  1. template header file
  2. 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").

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.

php-RGraph and 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">

[No canvas support]>

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

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":
  1. support data creation and provisioning for RGraph charts
  2. provide setter and getter methods for rgraph_chart objects
  3. 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.

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":
  1. support creation and settings of properties for RGraph charts
  2. 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.

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

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

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:
  1. f(x) = ax + b (linear regression)
  2. f(x) = abx (exponential regression)
  3. f(x) = axb (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

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:
  1. You may specify formula with or without equal sign e. g. "y = x * e^x" or "x * e^x"
  2. Independent variable must be set to "x"
  3. 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.

  4. Constants:
    • Pi (π): "pi"
    • Euler's number (e): "e"
  5. Operators:
    • Add: "+"
    • Subtract: "-"
    • Multiply: "*"
    • Divide: "/"
    • Power: "^"
  6. 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.1.4 (Build Level 2.1.4.0 - March 4, 2021)

 download 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.