SVGGraph data labels
Skip to:
Version 2.18 of SVGGraph merged all the previous support for labels on bar graphs and pie graphs into one system that works for all the graph types. This page shows some of the options available and how to use them.
Types of label
Figure 1 below shows all the types of label available with the
data_label_type
option (using a grouped bar graph with a dataset
for each label type).
The styles used for these labels are: “plain”, “box”, “bubble” and “line”, along with these new styles added in version 2.26: “circle”, “square”, “linecircle”, “linebox”, “linesquare” and “line2”.
Figure 2 above uses the same data and the same choice of label types, but modifies the styling options a bit. The settings that it uses for the labels are shown in the code block below.
$settings = array(
// other settings left out...
'show_data_labels' => true,
'data_label_type' => array('plain', 'box', 'bubble', 'line',
'circle', 'square', 'linecircle', 'linebox', 'linesquare', 'line2'),
'data_label_space' => 5,
'data_label_back_colour' => array('#ccc', null, null, '#ccc'),
'data_label_padding' => 5,
'data_label_round' => 4,
'data_label_tail_length' => "auto",
'data_label_tail_width' => 5,
'data_label_font_size' => 12,
'data_label_fill' => array(
array('#ccc','#fff','#ccc','h'),
),
'data_label_outline_thickness' => 2,
'data_label_position' => 'above',
'data_label_tail_end' => 'filled',
'data_label_tail_end_width' => 16,
);
These options should be self explanatory, though a couple of them might seem a bit odd. The tail length of the bubble label is the 5 pixels specified, but the length of the line label is much longer. This is because line labels have a minimum length the same as the font size - much smaller and the line can look like a hyphen or other character.
The other strange option is the data_label_fill
, which has an
array inside an array. This is because I wanted to use a gradient to fill the
label, which means using an array of colours. Since the option uses an array to
choose different fill colours for different datasets, I had to wrap the gradient
array inside the outer array. I hope that makes sense.
Positions
The data_label_position
option specifies where the label goes,
relative to the bars or markers (labels are positioned differently for pie
slices). SVGGraph can ignore your choice when it doesn't make sense, like
attempting to put the label inside a marker where it will not fit.
The table below shows the different positions that you can specify with the
data_label_position
option. The shaded area represents a bar on a
bar graph, and the table cells are where the labels would be.
outside top left | outside top inside left | outside top | outside top inside right | outside top right |
inside top outside left | top left | top | top right | inside top outside right |
outside left | left | centre | right | outside right |
inside bottom outside left | bottom left | bottom | bottom right | inside bottom outside right |
outside bottom left | outside bottom inside left | outside bottom | outside bottom inside right | outside bottom right |
The table doesn't look much like a bar on a graph though, and aligning the text the same way would be tricky, so here is a mock-up of a bar surrounded by labels in all the fixed positions:
Apart from these options, SVGGraph also supports “inner” and “outer” as alternatives to “inside” and “outside”, and the values “above” and “below” as alternatives to “outside top” and “outside bottom“.
You can also add two integers to the end of the position string as an X,Y
offset, e.g. "top right -20 20"
.
Tail endings
The newer label styles that use filled line tails all support different end caps for the tail line. Figure 3 below uses the “linecircle” style and structured data to set each tail ending individually.
The value for the data_label_tail_end_width
has been increased
to 40 pixels to make the endings easier to see. When the tail width is not
enough to draw the ending completely it will fall back to using a simpler
ending style.
Filters
The data_label_filter
option allows you to fine-tune which labels
will be shown for a dataset. The default is to show all the labels, though you
can use a combination of these options:
- all
- Display all labels in dataset.
- none
- Display none of the labels. You can still use structured data to show specific item labels.
- start
- end
- Display labels for the first/last entries in the dataset.
- min
- max
- Display labels for the minimum/maximum values in the dataset.
- peaks
- troughs
- Display labels where the data trend has changed direction.
- nonzero
- Display labels for all values other than 0.
Figure 4 below uses “min” and “peaks” together to show labels for the minimum value at 2 and the three peaks at 7, 15 and 21.
As well as the keywords, you can also use a numeric step value with an optional offset, as demonstrated in figure 5 and figure 6. Without an offset, the first label (position 0) is shown, then label N, label 2×N, label 3×N, etc.
Figure 6 uses an offset of 2 (data_label_filter = "3+2"
) to
label positions 2 (0 + 2), 5 (3 + 2), 8 (6 + 2), etc. If you want to use an
offset, don't forget to enclose the filter value in quotation marks - otherwise
the step and offset will be added together and give you a different step value.
Figure 7 shows the use of an array to filter the two datasets differently. The first dataset is labelled on the peaks and minimum value, and the second dataset is labelled at both ends and every third entry starting with position 2.
Interactive label options
These options use Javascript to control label visibility when you move the cursor over (or click on) the bar, marker or pie slice. Figure 8 shows the fade in and fade out effects, with the labels fading in quickly and fading out slowly.
Figure 9 uses the data_label_click
option to toggle visibility
of the labels when bars are clicked. The “hide” value means that the
labels should be hidden initially, whereas a value of “show” will
display all labels at the start.
Figure 10 demonstrates the effect of data_label_popfront
. The
labels are quite large in relation to the bars, so they overlap in places - with
this option enabled, the label for the bar under the cursor will be popped to
the front of all the other labels.
Figure 11 uses all the options together, this time using an array to make the click labels start hidden for the first dataset and shown for the second dataset.
The labels that are not already visible will fade in and out when you move the cursor over the bars. Clicking on a bar will keep it visible or allow it to fade out again, and the labels will pop to the front when the mouse is over the relevant bar.
Structured data labels
Most of the label options are also supported by the structured data
structure
array option, as demonstrated by the example graph
below.
Use the full data_label_*
option name in your
structure
array to specify which options you want to change from
the data. The structure
array and data values used in the example
graph are shown in the code below.
$settings = array(
// other settings left out...
'structure' => array(
'key' => 0, 'value' => 1,
'data_label_type' => 'dlt',
'data_label_padding' => 'dlp',
'data_label_round' => 'dlr',
'data_label_position' => 'dlpos',
'data_label_fill' => 'dlbg',
'data_label_font' => 'dlf',
'data_label_font_adjust' => 'dlfa',
'label' => 'lbl',
),
);
$values = array(
array(0, 5, 'dlt' => 'box',),
array(1, 6),
array(2, 6, 'dlpos' => 'left'),
array(3, 7, 'dlt' => 'bubble'),
array(4, 6, 'dlt' => 'bubble', 'dlp' => 10, 'dlr' => 8),
array(5, 5),
array(6, 3, 'dlpos' => 'above', 'dlt' => 'bubble', 'dlp' => 10, 'dlr' => 10,
'dlf' => 'Times New Roman', 'dlfa' => 0.45,
'lbl' => "Label\nText", 'dlbg' => array('#99f','#fff','#99f','h')),
);
This example also uses the older structured data option “label” to set the text for the last label explicitly.
Other details
These are just a few points that don't fit into the sections above.
— The data_label_max_count
option limits the number of labels
created for a dataset, to prevent generating huge numbers of labels that would
probably overlap anyway. This option does not support arrays, as it is a simple
sanity check and defaults to 100. The count applies after any filters, so if
your labels appear to run out halfway across the graph, try a
data_label_filter
step of 2 (or increase
data_label_max_count
if you really want hundreds of labels).
— The units_label
and units_before_label
options were previously available for use with pie and bar labels, and will now
work for all data labels. They do not alter the text of labels when it comes
from a structured data label
field.
— Several of the older pie graph label options are still required, as
there are no equivalents for graphs in general. These options are
show_label_key
, show_label_amount
,
show_label_percent
, label_position
and
label_percent_decimals
. Pie graphs still use
label_position
for positioning the label because it uses a single
value for the distance from the centre instead of the relative positions
supported by data_label_position
.
— The bar_total_*
options supported by the stacked bar
graphs use the same data labels code, so there are now several more options
available for styling the total labels.
All the options
Just as a recap, here are all the data label options. This table lists all
the options tagged with data-label
from the options index.
Data label options - Hide table
Option | Default | Description |
---|---|---|
data_label_align |
null |
Data label text alignment. |
data_label_angle |
0 |
Text angle for data labels. |
data_label_back_colour |
NULL |
Colour of label text border. |
data_label_back_colour_outside |
NULL |
Alternative label text border colour. |
data_label_callback |
NULL |
Callback function for data label text. |
data_label_click |
false |
Enables click-to-show/hide for data labels. |
data_label_colour |
"rgb(0,0,0)" |
Text colour for data labels. |
data_label_colour_outside |
NULL |
Alternative text colour for data labels. |
data_label_datetime_format |
"Y-m-d H:i:s" |
Date format for date/time keys in labels. |
data_label_fade_in_speed |
0 |
Fade in speed for data labels. |
data_label_fade_out_speed |
0 |
Fade out speed for data labels. |
data_label_fill |
"white" |
Data label background colour. |
data_label_filter |
NULL |
Limits the data labels displayed. |
data_label_font |
"Arial" |
Font used for data labels. |
data_label_font_adjust |
0.6 |
Font adjust value for label text. |
data_label_font_size |
10 |
Font size for data labels. |
data_label_font_weight |
"normal" |
Font weight for data labels. |
data_label_line_spacing |
null |
Sets line spacing for data labels. |
data_label_max_count |
100 |
Maximum number of data labels to display. |
data_label_min_space |
0 |
Minimum space required for label. |
data_label_opacity |
1 |
Sets the opacity of data labels. |
data_label_outline_colour |
"rgb(0,0,0)" |
Edge colour for data labels. |
data_label_outline_thickness |
1 |
Line thickness for data labels. |
data_label_padding |
3 |
Space inside data label boxes. |
data_label_padding_x |
NULL |
Horizontal space in data label box. |
data_label_padding_y |
NULL |
Vertical space in data label box. |
data_label_popfront |
false |
Enables pop-to-front for data labels. |
data_label_position |
"top" |
Position of data label. |
data_label_round |
0 |
Radius of data label corners. |
data_label_same_size |
false |
Determines if all data labels should be the same size. |
data_label_shadow_opacity |
0.3 |
Opacity of data label shadows. |
data_label_space |
3 |
The space between the label and the data item. |
data_label_tail_end |
"flat" |
Style of data label tail ending. |
data_label_tail_end_angle |
45 |
Angle of data label tail ending. |
data_label_tail_end_width |
10 |
Width of data label tail ending. |
data_label_tail_length |
3 |
Length of data label tails. |
data_label_tail_width |
5 |
Thickness of data label tails. |
data_label_type |
"plain" |
The style of label to use. |
label |
NULL |
Adds custom labels to the graph. |
label_percent_decimals |
2 |
Decimal places in label percentages. |
label_position |
0.75 |
Distance of label from centre. |
show_data_labels |
false |
Displays labels for data items. |
show_label_amount |
false |
Shows item amount in data label. |
show_label_key |
true |
Shows item key in data label. |
show_label_percent |
false |
Shows item percentage in data label. |
units_before_label |
NULL |
String to display before value in data labels. |
units_label |
NULL |
String to display after value in data labels. |