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
// 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
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
turn off dragging, and the
legend_autohide option has been set
TRUE to enable hiding the legend when the mouse passes over
You can use
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
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,
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.
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
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
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.
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
legend_columns when there are not enough entries to fill
entries per column = ⌈ number of entries /
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.