SVGGraph Shapes and Figures
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
options should make things a bit easier.
For more complex shapes or for repeating the same shape in different places you can define figures. Figures can also be used as markers.
Here is a
LineGraph showing some examples of the shapes
All the shapes drawn on the graph above were added using the
option, using the configuration shown below. The three red boxes with a shaded
part are examples of a
figure, the star is a
and the notepad icon is an
$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 ), array( 'figure', 'x' => 'g6', 'y' => 'g200', 'name' => 'complex' ), array( 'figure', 'x' => 'g7', 'y' => 'g180', 'name' => 'complex' ), array( 'figure', 'x' => 'g8', 'y' => 'g220', 'name' => 'complex' ), array( 'marker', 'x' => 'g9', 'y' => 'g300', 'type' => 'star', 'size' => 20 ), array( 'image', 'x' => 'g9.5', 'y' => 'g300', 'src' => '../images/64x64/icon-05.png' ), ) );
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 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 in 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 style it and any other attributes that are passed straight through to the SVG element. Here's an example with all of these attribute types:
$settings['shape'] = array( // type of shape 'circle', // shape attributes 'cx' => 'g10', 'cy' => 'g200', 'r' => 'u1x', // styling 'fill' => array('#f00', 'pattern' => 'polkadot'), 'depth' => 'above', 'href' => '/circles/', // SVG attributes 'fill-opacity' => 0.75, 'stroke-width' => 2 );
This is the shape option for a
circle, its location and size
defined by the required fields
r. The example is using grid-relative values, so it will not work
on pie-type graphs.
fill option is a red polka dot pattern, the
specifies that the circle will be drawn on top of the bars or lines, and the
href links the circle to a relative URL.
are passed through into the SVG circle element without any modification. Here is
the SVG fragment that SVGGraph produces from the shape option 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>
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
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.
These are attributes that are purely for use by SVGGraph, or are preprocessed before being inserted into the SVG element.
- 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.
- This wraps the shape inside an
<a>element, using the link you provide.
xlink:hrefis the actual attribute used by SVG, but SVGGraph will accept either. The
targetfor the link defaults to “_blank“ if you do not set it.
- This boolean option adds a
clip-pathattribute to the shape, cropping the shape at the edge of the grid area. The default is
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:
- 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
- This is the colour that the shape is filled with. By default, SVGGraph
will set it to “none”, so your shape will be empty.
strokeattributes both accept SVGGraph gradient and pattern options, though for
strokeonly the initial colour is used.
- The thickness of the line stroke, in pixels. The default is 1.
- 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.
- The dash pattern for the line. I've described how this works on the line graphs page.
All the shapes supported by SVGGraph are basic SVG shapes. For complete details, refer to the W3C recommendation document.
Most of the attributes listed here are required to draw each of the shapes - SVGGraph will display an error message if they are not present. Some of the shapes have optional attributes that change how they behave.
To draw a circle, provide the position of the centre and the radius.
- X-axis coordinate of centre of circle.
- Y-axis coordinate of centre of circle.
- Radius of circle.
$settings['shape'] = array( 'circle', 'cx' => 100, 'cy' => 200, 'r' => 10 );
The ellipse is similar to the circle, but you must provide separate radius values for the horizontal and vertical dimensions.
- X-axis coordinate of centre of ellipse.
- Y-axis coordinate of centre of ellipse.
- X-axis radius of ellipse.
- Y-axis radius of ellipse.
$settings['shape'] = array( 'ellipse', 'cx' => 100, 'cy' => 200, 'rx' => 10, 'ry' => 20 );
A rectangle is drawn from the top-left corner using a width and height.
- X-axis coordinate of top-left of rectangle.
- Y-axis coordinate of top-left of rectangle.
- Width of rectangle.
- Height of rectangle.
$settings['shape'] = array( 'rect', 'x' => 100, 'y' => 200, 'width' => 100, 'height' => 50 );
line element draws a straight line between two points.
- X-axis coordinate of first point.
- Y-axis coordinate of first point.
- X-axis coordinate of second point.
- 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.
the line with your last point,
polygon closes the shape by drawing
a line from the last point back to the first point.
- 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 ) );
image shape adds an
<image> element to the
document. This is similar to the HTML
<img> element, except
you must provide the
y coordinates for where
the image should appear.
- X-axis coordinate for upper-left of image bounding box.
- Y-axis coordinate for upper-left of image bounding box.
- Path of image to be displayed (relative to SVG document or absolute).
- Width of image bounding box (optional).
- Height of image bounding box (optional).
- If set to
true, the image is stretched to fill the whole of the bounding box specified using
height- otherwise, the image is scaled proportionately to fit inside the box. This attribute is optional, and defaults to
$settings['shape'] = array( 'image', 'x' => 'g9.5', 'y' => 'g300', 'src' => '../images/64x64/icon-05.png' );
marker shape allows you to position any of the standard
markers on your graph, even on graph types
that would not normally support them (pie graphs being the most obvious example
- X-axis coordinate for marker.
- Y-axis coordinate for marker.
- Type of marker to display.
- Size of marker (optional, defaults to 10).
$settings['shape'] = array( 'marker', 'x' => 'g9', 'y' => 'g300', 'type' => 'star', 'size' => 20 );
figure shape draws a user-defined shape or group of shapes on
the graph. The attributes specify where the figure should go and the name of
the figure to use. The creation of figures is described in the next section.
- X-axis coordinate for figure.
- Y-axis coordinate for figure.
- Name of figure to display.
$settings['shape'] = array( 'figure', 'x' => 'g6', 'y' => 'g200', 'name' => 'complex' );
Figures are named collections of shapes that can be used multiple times at
different locations using the
shape option, or as graph markers
by setting the
marker_type to “figure:” followed by the
name of the figure.
The figure option should be an array of separate figures. Each individual figure is another array, starting with a name that you will use to refer back to it - this is just a string, and SVGGraph doesn't do anything special with it.
After the name you can add as many shapes as you want in your figure, each one of which will be in its own array. Figures can contain other figures as long as they were defined earlier in the list. You can position your shapes anywhere, but when the figure is used the point (0,0) in the figure shapes will be translated to the new position of the figure.
Note: all styling of figure shapes must be done in the
option. You cannot change the colour, stroke width and other attributes of a
figure from the
shape option that references it.
Here is the configuration for the square figures in the example graph at the top of the page:
$settings = array( 'figure' => array( array( 'complex', array( 'rect', 'x' => -20, 'y' => -20, 'width' => 40, 'height' => 40, 'fill' => 'red' ), array( 'rect', 'x' => -10, 'y' => -15, 'width' => 20, 'height' => 30, 'fill' => 'white', 'transform' => 'rotate(45)' ), array( 'rect', 'x' => -10, 'y' => -15, 'width' => 20, 'height' => 30, 'fill' => array('red', 'white'), 'transform' => 'rotate(135)' ), ), ), );
figure array contains a single entry - another array that
defines a single figure. The array for this individual figure contains the name I
chose for it, “complex”, followed by three more arrays. Each of
these arrays contains the details of a shape, three rectangles in this case.The
shapes are all positioned so that their centre point is at (0,0) - this is so
that when the figure is used its position on the graph will be where the middle
of the figure occurs.