SVGGraph options: guideline

« Return to SVGGraph options page

Option name:
guideline
Default value:
NULL
Added in version:
2.7
Data type:
array [?]

The datatypes used in this documentation for specifying SVGGraph options are described below. All options can be a literal value of the data type described, a variable containing the data type, or an expression that will produce the data type when evaluated (and they must always be valid PHP expressions).

array
An array(), the number and data types of its members will depend on the option for which is it used.
boolean
A boolean TRUE or FALSE value, or any values that convert easily such as 1, "1", 0 and "".
callback
A callable function, which can be either the name of a function or an anonymous function itself.
colour
Any of the colour values supported by SVG inside a single or double quoted string. These include three and six digit hex codes, RGB and RGBA colours, and colour names. SVG uses "none" for no colour, which generally leaves things transparent.
fill
A colour value or one of the gradients and patterns supported by SVGGraph. See the SVGGraph colours page for details.
integer
A negative or positive whole number or 0.
number
Any number supported by PHP, for example 1 or -3.2 or 1.63e5 or M_PI.
string
Single or double quoted strings. Remember to double-quote your strings if you are inserting a line break: "Line 1\nLine 2".
Per-dataset:
no [?]

Per-dataset options allow specifying one option for all datasets or an array of options to be used for each dataset in turn. If there are more datasets than entries in the option array, the sequence will be repeated.

Example:

$settings['widget_taste'] = 'banana';
$settings['widget_colour'] = array('red', 'green', 'blue');

For this example, the widgets for all datasets will taste of banana. The graph will use red widgets for dataset 0, green widgets for dataset 1 and blue widgets for dataset 2. Dataset 3 repeats the sequence so its widgets will be red, dataset 4 will have green widgets and dataset 5 will have blue widgets.

Supported by:
Bar3DGraph BarAndLineGraph BarGraph BoxAndWhiskerGraph BubbleGraph CylinderGraph FloatingBarGraph GroupedBar3DGraph GroupedBarGraph GroupedCylinderGraph HorizontalBarGraph HorizontalFloatingBarGraph HorizontalGroupedBarGraph HorizontalStackedBarGraph LineGraph MultiLineGraph MultiScatterGraph PopulationPyramid ScatterGraph StackedBar3DGraph StackedBarGraph StackedCylinderGraph StackedGroupedBar3DGraph StackedGroupedBarGraph StackedGroupedCylinderGraph StackedLineGraph
Tags:
guideline target line

Adds guide/target lines to the graph.

This option specifies one or more guide or target lines to be added to the graph. The format of this option must be either a single guideline specification, or an array of guideline specifications.

A guideline specification can be a single numeric value for the Y-axis position of the line, or an array containing a numeric values followed by other options for controlling the position and appearance of the line.

These are the fields available for use in a guideline specification:

  • 0 (first entry in array, required)

    The position of the line. This must be a numeric value in units on the chosen axis. If the ends of the axes are being calculated by SVGGraph (without the axis_min_h, axis_max_h, axis_min_v and axis_max_v options being used) they will be modified to include any guidelines on the graph.

  • 1 (second entry in array, default NULL)

    A text label for the line. A "\n" character in the string will split the text over multiple lines.

  • 2 (third entry in array, default "y")

    The axis to draw the line from. The option should be either "x" or "y".

The rest of the options all have matching guideline_* options that specify the default values for all lines:

  • "above"

    Specifies whether the line is drawn on top of the graph or below it. Value should be true or false.

  • "length"

    The length of the line in pixels. A positive value will start the line at the left or bottom of the graph and a negative value will draw the line from the right or top of the graph.

  • "length_units"

    The length of the line in grid units. As with the length option, a positive value will start the line at the left or bottom of the graph and a negative value will draw the line from the right or top of the graph.

  • "colour"

    This sets the colour of the line and its text label.

  • "text_colour"

    This sets the colour of the text label, overriding the colour setting.

  • "opacity"

    This sets how opaque or transparent the line and label are. A value of 1 is fully opaque and a value of 0 is fully transparent.

  • "text_opacity"

    This sets how opaque or transparent the text label is, overriding the value of the opacity option.

  • "stroke_width"

    The thickness of the line in pixels.

  • "dash"

    A dash pattern for the line. See the stroke_dash option for details of the dash pattern syntax.

  • "text_position"

    Sets the position of the text relative to the line. See the guideline_text_position option for details of the position string format.

  • "text_align"

    Label text alignment, which must be one of "left", "right" or "centre".

  • "text_padding"

    The space between the line and the text label in pixels.

  • "text_angle"

    A rotation angle for the text label, in degrees.

  • "font"

    The font to use for the text label.

  • "font_size"

    The font size to use for the text label.

  • "font_adjust"

    Font adjustment factor.

  • "font_weight"

    The font weight to use for the text label. This should be one of the CSS font weight values (listed on the guideline_font_weight page).

Here are some simple examples:

  1. a single line meeting the Y axis at 10 units:
    $settings['guideline'] = 10;
  2. a single line meeting the Y axis at 15 units, labelled "Target":
    $settings['guideline'] = array(15, "Target");
  3. two lines, one at 15 units on the Y axis (the same as the previous example) and a red one at 20 units on the X axis.
    $settings['guideline'] = array(
      array(15, "Target"),
      array(20, "Stop", "x", "colour" => "red")
    );

See the Guide or target lines page for more details and examples.

See also:
axis_min_v axis_max_v axis_min_h axis_max_h guideline_above guideline_colour guideline_opacity guideline_stroke_width guideline_dash guideline_font guideline_font_size guideline_font_adjust guideline_font_weight guideline_text_position guideline_text_padding guideline_text_colour guideline_text_angle guideline_text_align guideline_text_opacity guideline_length guideline_length_units stroke_dash

« Back to top of page Main SVGGraph page »