Using SVGGraph
Skip to:
The whole point of SVGGraph is to draw a graph on a web page. SVGGraph has different functions for the alternative ways of adding a graph to a page, and this page covers embedding the graph using a script external to the page.
For directly inserting the graph SVG into the code of the page, visit the SVG in HTML page for instructions.
Embedding the SVG in a page
There are several ways to insert SVG graphics into a page. FireFox, Safari, Chrome, Opera and IE 9 all support SVG natively, though Internet Explorer versions up to 8 require the use of a plugin (such as the one supplied by Adobe).
For options 1-3, I'll assume you have a PHP script called "graph.php" which contains the code to generate the SVG graph that you want to embed.
Option 1: <embed>
The embed tag has been around for years, but has only been
included in the HTML standard with HTML5.
<embed src="graph.php" type="image/svg+xml" width="600" height="400"
pluginspage="http://www.adobe.com/svg/viewer/install/" />
This method works in all browsers. The pluginspage attribute
is for telling the browser where to download the relevant plugin from, but
all modern browsers should have SVG support built-in.
Option 2: <iframe>
This method tells the browser to load the SVG as a separate document in a frame inside the main HTML page.
<iframe src="graph.php" type="image/svg+xml" width="600" height="400"></iframe>
This method also works in all browsers, and the iframe tag is
standard in HTML 4.
Option 3: <object>
The object tag is part of the HTML 4 standard, but the
following code doesn't work in versions of IE before version 9.
<object data="graph.php" width="600" height="400" type="image/svg+xml" />
Option 4: <img>
The img tag is obviously supported by all graphical browsers,
but support for displaying SVG documents as images is a recent development.
While it works in every browser I have tried, an SVG embedded using
img will not run any Javascript which means the tooltips and other
interactive options normally supported by SVGGraph will not work.
<img src="graph.php" width="600" height="400" type="image/svg_xml" />
Using an img also makes the right-click browser menu less
useful from the developer's point of view - there is no "View Frame Source" for
images.
Option 5: SVG within HTML
The content of the SVG graph can be included with the HTML of the surrounding page, either by using the SVG namespace in an XHTML document, or more easily by including the SVG in an HTML5 document.
<div>
<?php echo $graph->fetch('BarGraph', false); ?>
</div>
When inserted directly into the page in this way, the elements of the SVG document can be affected by CSS from the page. Something like this could really mess up your graphs:
<style>
rect { opacity: 0 }
</style>
SVG does not share many element names with HTML, so this is not likely to be a problem unless you have non-SVGGraph SVG elements that you want to style.
This method does not work in older versions of Internet Explorer, but it is supported by all modern browsers. For the full details on using this technique, take a look at the SVG in HTML page.
Building the graph
There are only four steps required to build the most basic graph:
- Set up the class autoloader;
- Construct an instance of the SVGGraph class;
- Provide the data values to draw on the graph;
- Render the required graph type.
The following example shows each of these steps, drawing a line graph of a sequence of numbers:
<?php
require 'SVGGraph/autoloader.php';
$graph = new Goat1000\SVGGraph\SVGGraph(500, 400);
$graph->values(1, 4, 8, 9, 16, 25, 27);
$graph->render('LineGraph');
The sections that follow describe each of the four steps, and explain how to build more complex and better-looking graphs.
1. Including or requiring SVGGraph
Note: if you are using Composer to install SVGGraph you can skip this step - the Composer autoloader will load the SVGGraph files.
The library consists of several class files, a svggraph.ini
file, a subdirectory of Javascript templates and a subdirectory of font metrics
files. All of the class files and the .ini file must be present, though
SVGGraph will work without the font metrics. The Javascript templates are only
loaded when required, so if you are not using any of SVGGraph's Javascript
output you can get by without them.
To use SVGGraph you include or require a single PHP file in your code, as all the other files are loaded automatically when they are needed.
SVGGraph 3.x
SVGGraph 3.x uses a PSR-4 autoloader.
// install the autoloader
require_once 'SVGGraph/autoloader.php';
The SVGGraph autoloader script registers a loader function by calling the
spl_autoload_register PHP function. If you want to use your own
autoloader, all the SVGGraph classes to be loaded are in the
Goat1000\SVGGraph\ namespace.
SVGGraph 1.x and 2.x
SVGGraph 1.x-2.x use a custom class loader from the main class file.
// load the main class
require_once 'SVGGraph.php';
2. The SVGGraph class constructor
The SVGGraph class constructor takes three arguments, the width and height of the SVG image in pixels and an optional array of settings to be passed to the rendering class.
Note that the width and height you specify here should
be the same as or smaller than the size you use for the embed,
iframe or object element, otherwise you will end
up with scroll bars. For a graph that scales with its container, use the
auto_fit option.
SVGGraph 3.x
SVGGraph 3.0 puts the classes inside the Goat1000\SVGGraph\
namespace, so you must specify it when calling the constructor.
$graph = new Goat1000\SVGGraph\SVGGraph($width, $height, $settings);SVGGraph 1.x and 2.x
$graph = new SVGGraph($width, $height, $settings);
For more information on what goes in the $settings array,
see the settings page and the pages
for each of the graph types.
3. Assigning data values
For very simple graphs you may set the data to use by passing it into
the values function:
$graph->values(1, 2, 3);
For more control over the data, and to assign labels, pass the values in as an array:
$data = array('first' => 1, 'second' => 2, 'third' => 3);
$graph->values($data);
For graphs that support multiple data sets, pass in an array of value arrays:
$data = array(
array('first' => 1, 'second' => 2, 'third' => 3),
array('first' => 3, 'second' => 5, 'third' => 2, 'fourth' => 4),
array('first' => 2, 'second' => 3, 'third' => 1, 'fifth' => 5),
);
$graph->values($data);
In this example, the second and third value arrays have extra values with
keys 'fourth' and 'fifth'. The graph will be drawn with both of those values
assumed to be NULL for the value arrays where they are not
specified.
Graphs that do not support multiple datasets will use the first value array and ignore any others that are present.
For scatter graphs, the marker positions are given by the array keys and values:
$data = array(5 => 20, 6 => 30, 10 => 90, 20 => 50);
$graph->values($data);
From version 2.4, scatter graphs support passing in pairs of x,y coordinates
when the scatter_2d option is set, to allow several markers to
appear at the same x-coordinate:
$data = array(
array(5,20), array(6,30), array(5,90), array(10,50)
);
$graph->values($data);The scatter_2d format is still supported, but it is now
converted into a simple form of structured data.
Zero and NULL
When used as data values, 0 and NULL behave differently. 0 is
displayed on the graph when supported by the graph type, but NULL
values are not drawn (unless the graph cannot skip data points, then it is
treated as 0). For an example of this, see the
zero and null section on the 3D
bar graphs page.
Structured data
Version 2.11 added a new way to specify the values array called structured data. This allows for configuring the fields in the array as data or metadata.
$data = array(
array(5, 20, 30), array(6, 30, 10),
array(5, 90, 40), array(10, 50, 50),
array(8, 30, 'label' => 'Wow!'),
);
$graph->values($data);The data format is configurable using the structure option.
Adding hyperlinks
The graph bars and markers may be assigned hyperlinks - each value that requires
a link should have a URL assigned to it using the links function:
$graph->links('/page1.html', NULL, '/page3.html');
The NULL is used here to specify that the second bar will not be linked to
anywhere.
As with the values function, the list of links may be passed in as an array:
$links = array('/page1.html', NULL, '/page3.html');
$graphs->links($links);
Using an associative array means that NULL values may be skipped.
$links = array('first' => '/page1.html', 'third' => '/page3.html');
$graphs->links($links);
Links for individual bars, markers and pie slices may also be specified using structured data.
4. Rendering the graph
To generate and display the graph in one go, call the render
function passing in the type of graph to be rendered:
$graph->render('BarGraph');
This will send the correct content type header to the browser and output the SVG graph.
The render function takes two optional parameters in addition
to the graph type:
$graph->render($type, $header, $content_type);
Passing in FALSE for $header will prevent output
of the XML declaration and doctype. Passing in FALSE for
$content_type will prevent the image/svg+xml content
type being set in the response header.
To generate the graph without outputting it to the browser you may use the
fetch function instead:
$output = $graph->fetch('BarGraph');
This function also takes optional $header and $defer_js
parameters:
$output = $graph->fetch($type, $header, $defer_js);
Passing in FALSE as $header will prevent the
returned output from containing the XML declaration and doctype. The
fetch function never outputs the content type to the response
header.
The default for $defer_js is TRUE, which means you
must use the fetchJavascript function to insert the code required
for tooltips, etc. later in the page.