SVGGraph custom labels

« Return to SVGGraph page

Skip to:

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.


Custom labels

The four labels in the centre of the graph are all labelling the grid point (40, 100). The bubble label is labelling the absolute SVG pixel location (200, 100). The settings used for this 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,
  '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'),
    array(200, 100, "This is at (200,100)\nand on two lines", 'type' => 'bubble',
      'fill' => array('#ff6','#ffc','#ff6','h'), 'round' => 10),
  ),
);

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

Label options - Hide table

OptionDefaultDescription
type plain The style of label to use. Options are "plain", "box", "bubble" or "line"
space 3 The space between the label and the coordinates
font sans-serif Font used for label
font_size 10 Font size for label
font_adjust 0.6 Font adjust value for label text
font_weight normal Font weight for label
colour rgb(0,0,0) Text colour for label
back_colour NULL Colour for label text border, or NULL for none
position top Position of label relative to coordinates. See the data labels page for details
angle 0 Text angle for labels
padding 3 Space between label text and edge of label box
padding_x NULL Horizontal space between label text and edge of label box, overrides padding
padding_y NULL Vertical space between label text and edge of label box, overrides padding
round 0 Radius of rounded corners for box or bubble style labels
fill white Background colour, gradient or pattern for box or bubble style labels
outline_colour rgb(0,0,0) Edge colour for labels
outline_thickness 1 Line thickness for labels
tail_length 3 Length of tail for line or bubble style labels
tail_width 5 Thickness of tail for bubble style labels
shadow_opacity 0.3 Opacity of label shadows
Label options

« Back to top of page Background images »