Using SVGGraph

« Return to SVGGraph page

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:

  1. Set up the class autoloader;
  2. Construct an instance of the SVGGraph class;
  3. Provide the data values to draw on the graph;
  4. 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, 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. 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.

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.

« Back to top of page Function reference »