SVGGraph data labels

« Return to SVGGraph page

Skip to:

Version 2.18 of SVGGraph merges all the previous support for labels on bar graphs and pie graphs into one new 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 the four types of label available with the data_label_type option (on a grouped bar graph with for datasets). The first bar uses the default, “plain” style. The second bar label is a “box”, the third is a “bubble” and the last uses the “line” style.

Figure 1
Data label types
Figure 2

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 is using 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'),
  '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' => 5,
  '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',
);
 

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

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".

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.

Figure 3 below uses “min” and “peaks” together to show labels for the minimum value at 2 and the three peaks at 7, 15 and 21.

Figure 3
data_label_filter = "min peaks"
Figure 4
data_label_filter = "3"

As well as the keywords, you can also use a numeric step value with an optional offset, as demonstrated in figure 4 and figure 5. Without an offset, the first label (position 0) is shown, then label N, label 2×N, label 3×N, etc.

Figure 5 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 5
data_label_filter = "3+2"
Figure 6
data_label_filter =
array("peaks min", "start end 3+2")

Figure 6 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 7 shows the fade in and fade out effects, with the labels fading in quickly and fading out slowly.

Figure 7
data_label_fade_in_speed = 40
data_label_fade_out_speed = 5
Figure 8
data_label_click = "hide"

Figure 8 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 9 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 9
data_label_popfront = true
Figure 10
data_label_fade_in_speed = 40
data_label_fade_out_speed = 5
data_label_click = array("hide","show)
data_label_popfront = true

Figure 10 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.


Structured data labels

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 is also included as part of the “General options” section of the individual graph pages.

Data label options - Hide table

OptionDefaultDescription
show_data_labels false Displays labels for bars, markers, pie slices
data_label_type plain The style of label to use. Options are "plain", "box", "bubble" or "line"
data_label_space 3 The space between the label and the data item.
data_label_font sans-serif Font used for label
data_label_font_size 10 Font size for data label
data_label_font_adjust 0.6 Font adjust value for label text
data_label_font_weight normal Font weight for data label
data_label_colour rgb(0,0,0) Text colour for data label
data_label_colour_outside NULL Text colour for data label when outside bar/slice. NULL for same colour as when inside
data_label_back_colour NULL Colour for label text border, or NULL for none
data_label_back_colour_outside NULL Colour for label text border when outside bar/slice, or NULL for same as when inside
data_label_position top Position of data label relative to bar/marker/slice. See the data labels page for details
data_label_angle 0 Text angle for data labels
data_label_padding 3 Space between data label text and edge of label box
data_label_padding_x NULL Horizontal space between data label text and edge of label box, overrides data_label_padding
data_label_padding_y NULL Vertical space between data label text and edge of label box, overrides data_label_padding
data_label_round 0 Radius of rounded corners for box or bubble style data labels
data_label_fill white Background colour, gradient or pattern for box or bubble style 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_tail_length 3 Length of tail for line or bubble style data labels
data_label_tail_width 5 Thickness of tail for bubble style data labels
data_label_shadow_opacity 0.3 Opacity of data label shadows
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_click false Set to TRUE to enable show/hide labels by clicking bar/marker/slice
data_label_popfront false Set to TRUE to pop the label of the bar/marker/slice under the cursor to top
data_label_filter NULL Filters the list of data labels to be displayed. See the data labels page for details
data_label_max_count 100 Maximum number of data labels to display for a dataset (after filtering)
data_label_min_space 0 Sets the minimum space required for a label to be shown. For vertical bars this is the height of the bar, for horizontal bars it is the width and for pie slices it is the angle in degrees. Has no effect on line and scatter graphs.
data_label_callback NULL Name of callback function for formatting data label text. The function will be called with three arguments: callback($dataset, $key, $value). The function should return a text string to display or NULL for no label. Takes precedence over structured data label values.
units_label NULL Units string to display after value in data labels
units_before_label NULL Units string to display before value in data labels
label NULL Custom labels to display on the graph. See the custom labels page for details.
Data label options

« Back to top of page Legends »