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 V6.18.
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- structure of php-RGraph charts
- Using templates
- Using php-RGraph on your website
- 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.
Installation of php-RGraph
Installation is straight forward. Once you have downloaded installation file "php-RGraph-V2.1.19.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 link to php-RGraph Examples). 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.Note that php chart scripts always has these components:
-
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';
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";
-
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
-
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
- SemiCircularProgress
- Scatter
- Waterfall
$options = new rgraph_options($ini-file); $options->set_option("title", "My first chart); ...
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
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").
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
<script type="text/javascript"> jQuery(document).ready(function() { var url = "../samples/logo.php"; jQuery("#show-sample").load( url, function() { }); }); </script>
<div id="show-sample" style="float:right"></div>
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() { }); }
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 my Joomla System Plugin jphpx you may add your php-RGraph srcript code into an article using jphpx's plugin feature, e.g.:{jphpx [RGraph/samples_jphpx/bar_simple.php]}
php-RGraph - class rgraph_chart methods
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 methodphp-RGraph - class "rgraph_options": methods
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
$options = new rgraph_options(); $options->set_option("name", 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 methodphp-RGraph - Properties Reference for supported Charts
Select a Chart Type and Property, then click Button to see a short description
Select Chart TypeProperties 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.
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.
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) = abx (exponential regression)
- 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'];
- 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:
- "$x_min" - x-value for start of calculation
- "$x_max" - x-value for end of calculation
- "$x_interval" - x-increment for calculation
- "$max_iterations" maximum of calculation steps
- 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.1.20 (Build Level 2.1.20.1 - June 30, 2024)