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 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 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", "line", "circle", "square", "linecircle", "linebox", "linesquare" and "line2"
space 3 The space between the label and the coordinates
font "Arial" 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 enclosed labels, or switches to a round bounding box for open text 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 label tail, or "auto" to calculate length
tail_width 5 Thickness of label tail
tail_end "flat" Line ending for labels with filled line tails. Options are "flat", "taper", "point", "filled", "diamond", "arrow", "tee" and "round"
tail_end_width 10 Width of tail ending
tail_end_angle 45 Angle for pointed tail ending
shadow_opacity 0.3 Opacity of label shadows
Label options

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 »