SVGGraph legends

« Return to SVGGraph page

Legends were added in version 2.6 of SVGGraph by popular request, along with the titles and axis labels. I had resisted adding them up until this point, thinking that they would be more easily created in the HTML surrounding a graph. With plain bar graphs that is probably still true, but for dashed line graphs with different coloured and differently shaped markers, it would be a lot more tricky.

Using graph legends

The legend is the small box that describes what each of the entries in the graph represents. By default, SVGGraph will not draw one because it doesn't know what each of the entries means. To set the entries in the legend, use an array of strings as the legend_entries option:

// more code before this...
$settings['legend_entries'] = array(
  'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'
);
$graph = new Goat1000\SVGGraph\SVGGraph(300, 200, $settings);

$graph->values($values);
$graph->render('BarGraph');

From version 2.22, SVGGraph also supports assigning legend entries using structured data, which makes it easier to give specific data items an entry:

$settings['structure'] = array(
  'key' => 0, 'value' => array(1, 2), 'legend_text' => array('l1', 'l2')
);

$values = array(
  array(0, 18, 22, 'l1' => 'Monday',    'l2' => 'Twenty-two'),
  array(1, 17, 25, 'l1' => 'Tuesday'),
  array(2, 14, 27, 'l1' => 'Wednesday'),
  array(3, 15, 23, 'l1' => 'Thursday'),
  array(4, 13, 24, 'l1' => 'Friday',    'l2' => 'Another one'),
  array(5, 16, 24, 'l1' => 'Saturday'),
  array(6, 12, 21, 'l1' => 'Sunday')
);
$graph = new Goat1000\SVGGraph\SVGGraph(300, 200, $settings);

$graph->values($values);
$graph->render('GroupedBarGraph');

The full list of legend options available is shown in the table on the main SVGGraph settings page. The values in the first code sample above are used for the example in Figure 1 below.

The default height of a legend entry is 20 pixels, which makes the legend much too big for these small graphs. In Figure 2, I've reduced the size of the legend entries with the legend_entry_height option, and given the legend a title with the legend_title option.

Draggable and autohide

The legend still takes up a lot of space on the graph, and we can't see what the bars for Saturday and Sunday look like. There are a few ways to deal with this. By default, SVGGraph will make the legend draggable – when you move your mouse over the legend, the cursor should change to the crossed arrows “move” cursor. You can drag the legend across the graph by holding down the left mouse button.

Figure 3 below uses a different method to deal with the problem. The legend_draggable option has been set to FALSE to turn off dragging, and the legend_autohide option has been set to TRUE to enable hiding the legend when the mouse passes over it.

You can use legend_draggable and legend_autohide together if you want to, but dragging a box you can't see doesn't feel quite right to me. In Figure 3 I also set legend_text_side to "left" to display the text on the left-hand side of the entries.

Positioning the legend

Figure 4 shows an example of setting the legend_position option to "bottom left 3 -3" to move the legend to somewhere it will not cover up significant information. The "3 -3" part of the option adds an offset of 3 pixels in X and -3 pixels in Y.

Because there are a lot of places where you might want the legend to go, the legend_position option accepts several different values in the string to make up a position. The default is "inner top right" – the "inner" means that the legend should be positioned relative to the content of the graph inside the padding. Using "outer" instead means the legend will be positioned relative to the edges of the SVG document. The position may contain the words "inner", "outer", "top", "bottom", "right" and "left", and pairs of X and Y offsets.

Figure 5 shows the legend positioned to the side of a Pie3DGraph using "outer right -5 40" as the legend_position option. Only "right" is required and not "top", because an empty position string means the origin of the SVG in the top left. The legend_stroke_width has been set to 0 to prevent the border around the legend from being drawn, and legend_shadow_opacity is also 0 to prevent the shadow showing up.

The colours in the legend look different to those in the previous examples, even though the same colour settings are used. This is because pie graphs do not use gradients, so the legend entries are plain too. Also, the default for pie graphs is to sort the entries by size, largest first, which means the colours are not assigned in the same order as the entries.

Figure 6 shows how the legend works on a MultiLineGraph. Each data set marker and line is drawn on the legend instead of the filled box used by the other graph types. Similarly, the legend for a scatter graph contains only the markers against each entry.

Since there are only three data sets on the graph, the fourth and subsequent values in the legend_entries option are ignored. The legend_back_colour has been set to "#ccc" to make it easier to see the yellow line for Wednesday's entry. I've also set the legend_round option to 5 to give the box a rounded edge.

Multiple columns

SVGGraph now supports using multiple columns to display the legend entries by setting the legend_columns option, as shown in figure 7 below.

The number of columns that are actually shown may be lower than the value set for legend_columns when there are not enough entries to fill the columns:

entries per column = ⌈ number of entries / legend_columns ⌉

number of columns = ⌈ number of entries / entries per column ⌉

So if we wanted our 7 days of the week in 5 columns, the number of entries per column would be ceil( 7 / 5 ) == 2, and the actual number of columns would be ceil( 7 / 2 ) == 4.

Order of entries

In previous versions of SVGGraph the order that the entries appear in the legend was wholly determined by the type of graph. Most graphs display the entries in the same order as the legend_entries array, though the horizontal bar graph and stacked bar graphs display them in reverse order to match the order that the data values appear on the graph.

Version 3.2 adds the legend_order option, which allows you to override the order chosen by the graph. The legend can be displayed in normal order, or reversed, sorted, or using an array to specify an order.

For more details, visit the legend_order page in the options index.

« Back to top of page Markers »

Copyright © 2020, Goat 1000