SVGGraph data labels

« Return to SVGGraph page

Skip to:

• Types of label
• Positions
• Tail endings
• Filters
• Interactive label options
• Structured data labels
• Other details
• All options

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.

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.

« Back to top of page Legends »

Copyright © 2021, Goat 1000