SVGGraph custom labels

« Return to SVGGraph page

Skip to:

• Using custom labels
• Label format
• Label options

There are options for labelling the axes, bars, pie slices and other data objects, but sometimes you just want a label saying what you want and where you want it. This is where custom labels come in handy.

Using custom labels

The example line graph below shows several custom labels, not labelling anything in particular.

The four labels in the centre of the graph are all labelling the grid point (40, 100). The yellow bubble label is labelling the absolute SVG pixel location (200, 100). The blue label points to a location just to right of the yellow label, with an offset position moving it down and to the right. The six white labels in the bottom left corner show how the labels are drawn in the order they appear in the array, with later labels drawn over the top of previous labels.

The settings used for the example graph are shown below.

$settings = array(
  'data_label_font' => 'Courier',
  'data_label_font_adjust' => 0.6,
  'data_label_type' => 'box',
  'data_label_space' => 10,
  'data_label_padding' => 6,
  'data_label_tail_length' => 'auto',
  'data_label_tail_end' => 'filled',
  'data_label_tail_end_width' => 18,
  'data_label_tail_end_angle' => 30,
  'label' => array(
    array(
      'g40', 'g100',
      'Label above'
    ),
    array(
      'g40', 'g100',
      'Label to right',
      'position' => 'right'
    ),
    array(
      'g40', 'g100',
      'Label to left',
      'position' => 'left'
    ),
    array(
      'g40', 'g100',
      'Label below',
      'position' => 'bottom'
    ),

    // yellow label
    array(
      200, 100,
      "This is at (200,100)\nand on two lines",
      'type' => 'bubble',
      'fill' => array('#ff6','#ffc','#ff6','h'),
      'round' => 10
    ),

    // blue label
    array(
      280, 80,
      "A label pointing\nto another label",
      'type' => 'linebox',
      'fill' => '#cef',
      'position' => '200 50',
      'round' => 10,
      'padding' => 10,
      'tail_end_width' => 20,
    ),

    // crossing white labels
    array(
      100, 370,
      'Labels',
      'type' => 'linebox',
      'position' => '100 -100'
    ),
    array(
      100, 350,
      'are',
      'type' => 'linebox',
      'position' => '100 -60'
    ),
    array(
      100, 330,
      'drawn',
      'type' => 'linebox',
      'position' => '100 -20'
    ),
    array(
      100, 310,
      'in',
      'type' => 'linebox',
      'position' => '100 20'
    ),
    array(
      100, 290,
      'array',
      'type' => 'linebox',
      'position' => '100 60'
    ),
    array(
      100, 270,
      'order',
      'type' => 'linebox',
      'position' => '100 100'
    ),
  ),
);

Most of the settings for the custom labels are inherited from the data_label_* options - though show_data_labels is not enabled on this graph and the points on the line are not labelled.

Label format

Custom labels are defined with the label option, which must be either an array containing the details of a single label, or an array of arrays which each define a label.

There are only three fields required in a label array - the X and Y coordinates, and the text to go in the label.

$settings['label'] = array(
  200, 150,
  "Label at 200, 150",
  'angle' => 90,
  'position' => 'below'
);

This example creates a label for the coordinates (200, 150), containing the text “Label at 200, 150”. The angle option rotates the text 90° and the position option places the label below the given coordinates.

Note - the coordinates are the position of whatever is being labelled, not where the label itself will appear. The actual position of the label is controlled by the position and space options.

The coordinates can be simple numbers for use on any type of graph, or you can use relative positioning coordinates, as described on the shapes page.

Label options

Custom labels support most of the same options as the data labels, but with some minor differences. Since these options only appear as part of the label option, their names are shortened to type, space and so on, instead of data_label_type or data_label_space.

Since the custom labels are not labelling anything clearly defined, the interactive Javascript fading, click to hide/show and pop to front options supported by data labels are not available.

One final option that is not listed here but does affect custom labels is the data_label_max_count option, which limits the number of labels in a dataset that are shown. All the custom labels exist in a single virtual dataset, so you need to make sure that the number of custom labels is smaller than the data_label_max_count value or some of them will be hidden.

The defaults listed here are actually the default values for the underlying data_label_* options. Custom labels will inherit the values from any related data_label_* options that you set.

The links on each of the options in the table above go through to the equivalent data_label_* details page in the options index.

« Back to top of page Background images »

Copyright © 2020, Goat 1000