SVGGraph Shapes

« Return to SVGGraph page

Skip to:

Sometimes you might want to add some extra things to the graph to highlight certain areas or display target ranges. You could always add your elements into the SVG using an XML parser or string replacement, but the shape options should make things a bit easier.

Supported shapes

Here is a LineGraph showing some examples of the shapes available:


Different shapes

All shapes drawn on the graph are configured using the shape option, like this configuration used for the example above:

$settings = array(
  'shape' => array(
    array('circle',
      'cx' => 'g1', 'cy' => 'g900', 'r' => 10,
      'stroke-width' => 2, 'fill' => '#66f'),
    array('ellipse',
      'cx' => 'g1', 'cy' => 'g750', 'rx' => 20, 'ry' => 10,
      'stroke-width' => 2, 'fill' => '#6f6'),
    array('rect',
      'x' => 'g2', 'y' => 'g950', 'width' => 'u2', 'height' => 'u100',
      'stroke-width' => 2, 'fill' => '#ff6'),
    array('line',
      'x1' => 'g2', 'y1' => 'g800', 'x2' => 'g4', 'y2' => 'g700',
      'stroke-width' => 3, 'stroke' => '#f0f'),
    array('polyline',
      'points' => array('g0.5', 'g650', 'g1.5', 'g600', 'g1', 'g575', 'g0.5', 'g600'),
      'stroke-width' => 3, 'stroke' => '#0c9'),
    array('polygon',
      'points' => array('g0.5', 'g500', 'g1.5', 'g450', 'g1', 'g425', 'g0.5', 'g450'),
      'stroke-width' => 3, 'stroke' => '#f66'),
    array('polygon',
      'points' => array('g4.5', 'g600', 'g11', 'g1200', 'g12', 'g600', 'g5', 'g300'),
      'fill' => array('#f00', '#fcc'), 'fill-opacity' => 0.9, 'stroke' => '#00f',
      'stroke-width' => 2, 'stroke-dasharray' => '3,2', 'clip_to_grid' => true
    )
  )
);

Most of the config should be easy enough to understand. The coordinates might look a bit strange, but they are described in detail below.

Shape format

The shape option is always an array - either a single array containing the details of a single shape, or an array of different shapes, each defined by an array of options. The shapes are drawn is the order that they appear in the array (except when given a depth, described below).

The first element in the array (with index 0) is always the type of shape. This is followed by the named attributes that define the shape, options for SVGGraph to use and any other attributes that are passed straight through to the SVG element. Here's an example with all the attribute types:

$settings['shape'] = array(
  'circle',
  'cx' => 'g10', 'cy' => 'g200', 'r' => 'u1x',
  'fill' => array('#f00', 'pattern' => 'polkadot'),
  'depth' => 'above',
  'href' => '/circles/',
  'fill-opacity' => 0.75,
  'stroke-width' => 2
);

This is the shape option for a circle, its location and size defined by the required fields cx, cy and r. The example is using grid-relative values, so it will not work on pie-type graphs.

The fill option is a red polka dot pattern, the depth specifies that the circle will be drawn on top of the bars or lines, and the href links the circle to a relative URL.

Finally, the fill-opacity and stroke-width fields are passed through into the SVG circle element without any modification. Here is what the full shape option produces when drawn on the example graph at the top of the page:

<a xlink:href="/circles/" target="_blank"><circle stroke="#000" fill="url(#e3)" 
 cx="539.17" cy="308.8" r="49.917" fill-opacity="0.75" stroke-width="2px"/></a>

Coordinates

Normal SVG coordinates are in pixels, measured from the top-left of the document, going towards the right and downwards. You can use these in any of the shapes and on any graph type by simply using the numeric values. For grid-based graphs, positioning shapes on the grid or specifying a size in grid units is more useful, so SVGGraph adds some modifiers and abbreviations to make this easier.

All of the modifiers and abbreviations are case-insensitive. Here are the modifiers:

g prefix
Grid-based coordinate. A pair of coordinates using this prefix will be positioned on the grid in the correct place. Version 2.24 adds support for using associative data keys as the X value, for example “gPeter” is the grid point where the data item with the key “Peter” is drawn.
u prefix
Grid units. A distance in grid units without the padding or any offsets, useful for rectangle width and height, circle radius, etc.
x, y suffixes
These override the axis that SVGGraph would normally use for grid coordinates or units. For example, a circle radius would normally be 10 Y-axis units when given a value of “u10”, so using “u10x” means 10 X-axis will be used instead.
y0, y1 suffixes
If you are using a dual-Y axis graph, you can specify which of the two axes to use by appending the axis number after the “y”: “g10y0” is grid position 10 on the left-hand Y axis and “u20y1” is 20 units on the right-hand Y axis.

If you don't supply the “x” or “y” suffix, SVGGraph will guess which you mean based on the context, e.g. a circle's cx and cy would be assumed to be on the X and Y axes, respectively.

The abbreviations are for positioning relative to the edges of the graph or grid, and are used without any numbers:

l, r, t, b
Left, right, top and bottom of SVG document.
w, h
Width and height of SVG document.
gl, gr, gt, gb
Left, right, top and bottom of grid area.
gw, gh
Width and height of grid area.
c, cx, cy
Centre of graph document
gc, gcx, gcy
Centre of grid area

Note: don't forget to enclose your dimensions in single or double quote marks, or PHP will complain about syntax errors.

Options

These are attributes that are purely for use by SVGGraph, or are preprocessed before being inserted into the SVG element.

depth
This specifies where in the SVG output that the shape will be included. At the moment the options are “above” to display the shape on top of the graph, or “below” to draw the shape before the bars, pie slices, etc. are drawn.
href
xlink:href
target
This wraps the shape inside an <a> element, using the link you provide. xlink:href is the actual attribute used by SVG, but SVGGraph will accept either. The target for the link defaults to “_blank“ if you do not set it.
clip_to_grid
This boolean option adds a clip-path attribute to the shape, cropping the shape at the edge of the grid area. The default is false.

SVG attributes

I'm not going to attempt to list all the attributes available here, so you should refer to the W3C recommendation document for help with anything specific. All the multi-word SVG attributes are separated by minus signs, but SVGGraph will convert underscores to minus signs for you (so stroke_width will become stroke-width in the SVG document).

Here are some of the attributes you are likely to need:

stroke
This is the colour of the lines that make up the shape. If you don't set stroke, SVGGraph will set it to black (actually “#000”) for you. If you don't want to draw the outline of your shape, set stroke to “none“.
fill
This is the colour that the shape is filled with. By default, SVGGraph will set it to “none”, so your shape will be empty. The fill and stroke attributes both accept SVGGraph gradient and pattern options, though for stroke only the initial colour is used.
stroke-width
The thickness of the line stroke, in pixels. The default is 1.
opacity
fill-opacity
stroke-opacity
The opacity of the whole shape, the filled area, or the stroked line. The value should be in the range 0-1. The default is 1, for a fully opaque shape, and a value of 0 will be completely invisible.
stroke-dasharray
The dash pattern for the line. I've described how this works on the line graphs page.

The shapes

All the shapes supported by SVGGraph are basic SVG shapes. For complete details, refer to the W3C recommendation document.

The attributes listed here are required to draw each of the shapes - SVGGraph will display an error message if they are not present.

circle

To draw a circle, provide the position of the centre and the radius.

cx
X-axis coordinate of centre of circle
cy
Y-axis coordinate of centre of circle
r
Radius of circle
$settings['shape'] = array('circle', 'cx' => 100, 'cy' => 200, 'r' => 10);

ellipse

The ellipse is similar to the circle, but you must provide separate radius values for the horizontal and vertical dimensions.

cx
X-axis coordinate of centre of ellipse
cy
Y-axis coordinate of centre of ellipse
rx
X-axis radius of ellipse
ry
Y-axis radius of ellipse
$settings['shape'] = array('ellipse', 'cx' => 100, 'cy' => 200, 'rx' => 10, 'ry' => 20);

rect

A rectangle is drawn from the top-left corner using a width and height.

x
X-axis coordinate of top-left of rectangle
y
Y-axis coordinate of top-left of rectangle
width
Width of rectangle
height
Height of rectangle
$settings['shape'] = array('rect', 'x' => 100, 'y' => 200, 'width' => 100, 'height' => 50);

line

The line element draws a straight line between two points.

x1
X-axis coordinate of first point
y1
Y-axis coordinate of first point
x2
X-axis coordinate of second point
y2
Y-axis coordinate of second point
$settings['shape'] = array('line', 'x1' => 100, 'y1' => 200, 'x2' => 200, 'y2' => 400);

polyline and polygon

Both of these draw a line between pairs of points. polyline ends the line with your last point, polygon closes the shape by drawing a line from the last point back to the first point.

points
An array of pairs of X and Y coordinates
$settings['shape'] = array('polygon', 'points' => array(
  100, 200,
  200, 200,
  200, 300,
  150, 250,
  100, 300
));

« Back to top of page Custom labels »