BPCharts

   

Table of Contents

  1. Overview
  2. Getting Started
  3. Colors (chco)
  4. Bar Width and Spacing (chbh)
  5. Axis Definitions (chxt, chxr, chxl, chxs)
  6. Grid Lines (chgx)
  7. Fills (chf)
  8. Fonts and Font Sizes (chft and chfts)
  9. Margins (chmg)
  10. Chart Legend Text and Style(chdl, chdlp, chdls)
  11. Markers (chm)
  12. Advanced Examples


Overview

The vertical overlapped barchart can be used to draw a variety of different charts just by changing a few query string options.

The chart type code for the line chart is bvo.



Getting Started

Description Image

Line values are drawn from left to right. The y-axis range will automatically be scaled based on the values.

For historical reasons, the line chart displays solid vertical grid lines and dotted horizontal grid lines by default. This can be controlled via Grid Lines (chgx). All future examples on this page will have grid lines explicitly turned off using chgx=.
&chd=t:8,12,20,25,50,47,43|15,13,17,20,35,37,32|5,6,7,12,22,23,22&chco=104A7D|EA8C1B|B2C5E1
As with all charts, you can specify data using different data encodings. See data encodings for more information.
chd=s:sengelha,robertca
Missing values will be drawn as gaps.
&chd=s:sen_elha,rob_rtc
As with all charts, the chart size is controllable using the chs parameter.
chs=75x75
As with all charts, you can generate other image types using the chof parameter.
chof=s (SVG)


Colors (chco)

You can control the colors of individual lines using the chco option.

See also Colors.

Syntax

chco=<color_1>|...|<color_n>
<color>
The color, in RRGGBB or RRGGBBAA format, to apply to the line.

Example

Description Image
Make the first bar set red (FF0000) and the second bar set green (00FF00).
chd=s:sengelha,
  BOBCASEY
chco=FF0000|00FF00

Bar Width and Spacing (chbh)

You can optionally specify custom values for bar widths and spacing between bars and groups. You can only specify one set of width values for all bars.

Syntax

chbh= <bar_width_or_scale>,<space_between_bars>,<space_between_groups>
<bar_width_or_scale>
The width of the bar. You can specify widths and spacing absolutely or relatively, by entering one of the following values.
  • width - Bar width, in pixels. All spacing values are also absolute values, in pixels. Bars can be clipped if the chart isn't wide enough.
  • a - space_between_bars and space_between_groups are given in absolute units (or default absolute values, if not specified). Bars will be resized so that all bars will fit in the chart.
  • (currently not supported)r - space_between_bars and space_between_groups are given in relative units (or default relative values, if not specified) Relative units are floating point values compared to the bar width, where the bar width is 1.0: for example, 0.5 is half the bar width, 2.0 is twice the bar width. Bars can be clipped if the chart isn't wide enough.
<space_between_bars>
[Optional] Space between bars in the same group. If sizing is absolute, this is a width in pixels; if sizing is relative, this is a floating point value where 1.0 is the bar width. Default value is 4 pixels for absolute values, or 4/23 for relative values.
<space_between_groups>
[Optional] Space between bar groups in the same group. If sizing is absolute, this is a width in pixels; if sizing is relative, this is a floating point value where 1.0 is the bar width. Default value is 8 pixels for absolute values, or 8/23 for relative values.

You cannot omit intermediate optional parameters; you must end with a stated value. For example: chbh=10,5,10 is valid, chbh=10,,10 is not, chbh=10,5, is not.

Example

Description Image
This chart adds some spacing (40 pixels) between bars.
chbh=a,40


Axis Definitions (chxt, chxr, chxl, chxs)

You can control chart axes using the chxt, chxr, and chxl options.

The chxt option controls which axes you wish to display.

The chxr option controls a range for one or more axes. It can only be used for the y and r axes. (use chxl to specify labels for the x-axis)

The chxl option allows you to manually specify the labels for an axis.

The chxs option controls style for one or more axes. It can only be used for the y and r axes.

Syntax

chxt=<axis_1>,...,<axis_n>

chxr=<axis_1>,<range_start_1>,<range_end_1>,<opt_major_interval_1>,<opt_minor_interval_1>
|...|<axis_n>,<range_start_n>,<range_end_n>,<opt_major_interval_n>,<opt_minor_interval_n>

chxl=<axis_index_1>:|<label_1>|...|<label_n>
|...|<axis_index_n>:|<label_1>|...|<label_n>

chxs=<axis_index_1><opt_format_string>,<opt_label_color>,<opt_font_size>
|...|<axis_index_n><opt_format_string>,<opt_label_color>,<opt_font_size>
<axis>

Display the axis, using the following axis codes:

  • x - X-Axis on the bottom of the chart
  • y - Y-Axis on the left of the chart
  • r - Y-Axis on the right of the chart
<range_start>
The start of the range for the axis. When Chart Version (chvs=) is greater than zero (default is zero) then <range_start> may be optionally ommitted. The range-start will then be calculated automatically.
<range_end>
The end of the range for the axis. When Chart Version (chvs=) is greater than zero (default is zero) then <range_end> may be optionally ommitted. The range-end will then be calculated automatically.
<opt_major_interval>
[Optional] The major interval for the axis. Determines how frequently grid lines are displayed.
<opt_minor_interval>
[Optional] The minor interval for the axis.
<axis_index>
A zero-based index to specify the axis for which you want to specify labels. This is a zero-based index into the chxt parameter.
<label>
The label you wish to display. May be the empty string ("").
<opt_format_string>
[Optional] This is an optional format string that, if used, follows immediately after the axis index number without an intervening comma. It starts with a literal letter N followed by an optional format string.

The formatting string syntax is as follows:
       N<preceding_text>*<number_type><decimal_places>zs<x or y>*<following_text>

Here is the meaning of each element:
  • <preceding_text> - Literal text to precede each value.
  • *...* - An optional block wrapped in literal asterisks, in which you can specify formatting details for numbers. The following values are supported, and are all optional:
    • <number_type> - The number format, for numeric values. Choose one of the following:
      • f - [Default] Floating point format.
      • p - Percentage format. A % sign is appended automatically.
        Note: When using this format, data values from 0.0 — 1.0 map to 0 — 100% (for example, 0.43 will be shown as 43%).
      • k - Thousand abbreviated number. The value will be divided by 1,000 before display.
        Note: If you want a symbol to indicate thousand abbreviation (such as "1.2k") then add the symbol as <following_text> or <preceding_text>.
      • m - Million abbreviated number. The value will be divided by 1,000,000 before display.
        Note: If you want a symbol to indicate million abbreviation (such as "1.2m") then add the symbol as <following_text> or <preceding_text>.
      • e - Scientific notation format.
      • c<CUR> - Format the number in the currency specified, with the appropriate currency marker. Replace <CUR> with a three-letter currency code. Example: cEUR for Euros. You can find a list of codes on the ISO web site, although not all symbols are supported.
    • <decimal_places> - An integer specifying how many decimal places to show. The value is rounded (not truncated) to this length. Default is 2.
    • z - Display trailing zeros. Default is no.
    • s - Display group separators. Default is no.
    • x or y - This parameter is not currently supported - its content will be ignored.
  • <following_text> - Literal text to follow each value.
<opt_label_color>
[Optional]The color, in RRGGBB or RRGGBBAA format, to apply to the label.
<opt_font_size>
[Optional]The point size of the font used to render the labels.

Example

Description Image
Display a y-axis on the left of the chart with an automatically determined range.
chxt=y
Display a y-axis on the right of the chart with a range from 0 to 100. Draw the axis labels in 12 point red font, with trailing % symbol
chxt=r
chxr=r,0,100,10
chxs=0N*f0*%,FF0000,12
Display a x-axis on the bottom of the chart with labels every other year.
chxt=x
chxl=0:||1999||2000||2001||2002


Grid Lines (chgx)

You can control the chart grid lines using the chgx option.

chgx stands for axis-aligned grid lines. The horizontal grid lines are drawn aligned with the axis major interval for the y/r-axis, as specified by the chxr option. For vertical grid-lines, grid lines are drawn for every point with a non-empty label on the x-axis, as specified by the chxl option. Use a space or non-empty string to denote the place where you want to denote a grid line to be drawn and an empty string to denote no grid line.

Syntax

chgx=<axis>,<opt_dash_length>,<opt_space_length>,<opt_color>,<opt_thickness>
     |...|
     <axis>,<opt_dash_length>,<opt_space_length>,<opt_color>,<opt_thickness>
<axis>

The axis with whose major interval you want the grid lines synchronized.

  • x - Vertical grid lines aligned with the x-axis major interval
  • y - Horizontal grid lines aligned with the y-axis major interval.
<opt_dash_length>,<opt_space_length>
[Optional] Used to define dashed grid lines. The first parameter is the length of each line dash. The second parameter is the spacing between dashes. Specify 0 for <opt_space_length> for a solid line. Default values are 1,0.
<opt_color>
[Optional] The color, in RRGGBBAA format, of the grid lines. Defaults to black (000000)
<opt_thickness>
[Optional] The thickness of the grid lines. Defaults to 1.

Example

Description Image
Turn off all grid lines.
chgx=
Draw a chart with solid horizontal grid lines only.
chgx=y
Draw a chart with solid gray (CCCCCC) horizontal axis lines and dotted gray (CCCCCC) vertical axis lines.
chgx=x,1,3,CCCCCC|
  y,1,0,CCCCCC
Draw a chart with 3-pixel-thick dashed red (FF0000) vertical grid lines. By default a vertical grid line will be drawn through every data point.
chgx=x,4,2,FF0000,3
Draw a chart with 3-pixel-thick dashed red (FF0000) vertical grid lines for every other data point. This uses spaces to denote "draw a grid line" and an empty string to denote "no grid line".
chgx=x,4,2,FF0000,3
chxl=0:| || || |


Fills (chf)

The background color of the chart can be controlled using the chart fill option.

Syntax

chf=<fill_type>,s,<color>
<fill_type>

The part of the chart being filled. Specify one of the following values:

  • bg - Background fill
  • c - Chart area fill - the part of the chart that contains the data
s
Indicates a solid fill.
<color>
The fill color, in RRGGBB or RRGGBBAA format.

Example

Description Image
Fill the chart background with pale grey (EFEFEF).
chf=bg,s,EFEFEF
chxt=y
Fill only the charting area with pale grey (EFEFEF).
chf=c,s,EFEFEF
chxt=y
Fill the chart background with semi-transparent yellow (FBF8DDCC).
chf=bg,s,FBF8DDCC
chxt=y
Fill the charting area with semi-transparent yellow (FBF8DDCC). Note: We must also make the chart background fully transparent (00000000), otherwise the semi-transparent area will simply show the default chart background (white).
chf=bg,s,00000000
chf=c,s,FBF8DDCC
chxt=y


Fonts and Font Sizes (chft and chfts)

The fonts that BPCharts uses to renders labels can be controlled using the chft (font name) and chfts (font size) options.

For raster (e.g. PNG) charts, only fonts which exist on the BPCharts server may be used. For vector (e.g. SVG) charts, the font does not need to exist on the BPCharts server but the client which renders the SVG must have the font installed.

Syntax

chft=<font_name>
chfts=<font_size>
<font_name>
The name of the font to use to render the chart. Defaults to Verdana.
<font_size>

The size of the font to use to render the chart. For raster charts (e.g. PNG) this is in pixels; for vector charts (e.g. SVG) this is in points.

For raster charts, defaults to 11 pixels tall. For vector charts, defaults to 8 points tall.

Example

Description Image
Draw the axis labels in 18-pixel-tall Times New Roman.
chft=Times New Roman
chfts=18


Margins (chmg)

A chart's margins are defined as the area outside of the rendering of the chart data itself. The chart margin may include labels or legends.

By default, BPCharts automatically picks chart margins which fit the labels and legends.

Syntax

chmg=<top>,<right>,<bottom>,<left>
<top>
The top margin for the chart.
<right>
The right margin for the chart.
<bottom>
The bottom margin for the chart.
<left>
The left margin for the chart.

Example

Description Image
Adjust the chart margins to 5 pixels on top, 30 pixels on the right, 20 pixels on the bottom, and 10 pixels on the left. Use background and chart area colors to demonstrate the separation between the two.
chmg=5,30,20,10
chxt=r
chf=bg,s,93C5D0
chf=c,s,FBF8DD


Chart Legend Text and Style (chdl, chdlp, chdls)

This parameter is used to declare where the labels is inserted in a chart and legend order.

Syntax

chdl=<data_series_1_label>|...|<data_series_n_label>
chdlp=<opt_position>|<opt_label_order>
chdls=<color>,<size>,<opt_symbol>
<data_series_label>

The text for the legend entries. Each label applies to the corresponding series in the chd array

<opt_position>

Specifies the position of the legend on the chart:

  • t - Top
  • b - Bottom
  • l - Left
  • r - Right
  • tv - Top and legend is showed vertically
  • bv - Bottom and legend is showed vertically
<opt_label_order>

The order in which the labels are shown in the legend. Choose one of the following value:

  • l - Display labels in the order given to chdl
  • r - Display labels in the reverse order as given to chdl. This is useful in stacked bar charts to show the legend
  • a - Automatic ordering: roughly means sorting by length, shortest first, as measured in 10 pixel blocks. When two elements are the same length (divided into 10 pixel blocks), the one listed first will appear first.
  • 0,1 - Custom label order. This is a list of zero-based label indexes from chdl, separated by commas
<color>

Specify color (hex format): rrggbb

<font-size>

Specify font-color (pt)

<opt_symbol>

Specify the symbol for legend keys. Default if not specified is a square symbol.

  • s - Square
  • o - Circle
  • b - Bullseye
  • h - Horizontal Line
  • v - Vertical Line

Use a single character to apply the same symbol to all legend keys.
Or specify multiple characters to control the symbol for individual legend keys
e.g. "ssso" uses square symbols for the first 3 legend keys, but a circle symbol for the fourth key.

Example

Description Image
Legend position: top chdlp=t
Legend position: bottom and vertical legend chdlp=bv
Legend position: Reverse order legend chdlp=bv|r
Legend Color chdls=ff0000
Legend font size chdls=ff0000,12
Legend Symbol chdls=ff0000,12,hb




Chart Markers (chm=C/D/H/N/V)

You can combine markers with any other chm parameters using a pipe character ( | ) to separate the chm parameters.

Syntax

Specify one set of the following parameters for each series that should be marked. To mark multiple series, create additional parameter sets, delimited by a pipe character. You do not need to mark up all series. If you do not assign markers to a data series, it will not get any markers.

chm=
      [@]<marker_type>,<color>,<series_index>,<opt_which_points>,<size>,<opt_z_order>
        |...|
      [@]<marker_type>,<color>,<series_index>,<opt_which_points>,<size>,<opt_z_order>
<marker_type>
The type of marker to use. Specify one of the following types:
  • C - Rectangle. You must have at least two data series, where series 0 specifies the bottom edge and series 1 specifies the top edge. <size> specifies the width of the rectangle, in pixels.
  • D - Line Trace
  • H - Horizontal line through the specified data marker. This supports an extended <size> syntax that lets you specify an exact line length: line_thickness[:length] where :length is optional, and defaults to the full chart area width.
  • N<opt_format_string> - The value of the data at this point, with optional formatting.

    The formatting string syntax is as follows:
           N<preceding_text>*<number_type><decimal_places>zs<x or y>*<following_text>

    Here is the meaning of each element:
    • <preceding_text> - Literal text to precede each value.
    • *...* - An optional block wrapped in literal asterisks, in which you can specify formatting details for numbers. The following values are supported, and are all optional:
      • <number_type> - The number format, for numeric values. Choose one of the following:
        • f - [Default] Floating point format.
        • p - Percentage format. A % sign is appended automatically.
          Note: When using this format, data values from 0.0 — 1.0 map to 0 — 100% (for example, 0.43 will be shown as 43%).
        • k - Thousand abbreviated number. The value will be divided by 1,000 before display.
          Note: If you want a symbol to indicate thousand abbreviation (such as "1.2k") then add the symbol as <following_text> or <preceding_text>.
        • m - Million abbreviated number. The value will be divided by 1,000,000 before display.
          Note: If you want a symbol to indicate million abbreviation (such as "1.2m") then add the symbol as <following_text> or <preceding_text>.
        • e - Scientific notation format.
        • c<CUR> - Format the number in the currency specified, with the appropriate currency marker. Replace <CUR> with a three-letter currency code. Example: cEUR for Euros. You can find a list of codes on the ISO web site, although not all symbols are supported.
      • <decimal_places> - An integer specifying how many decimal places to show. The value is rounded (not truncated) to this length. Default is 2.
      • z - Display trailing zeros. Default is no.
      • s - Display group separators. Default is no.
      • x or y - This parameter is not currently supported - its content will be ignored.
    • <following_text> - Literal text to follow each value.

  • o - Circle
  • s - Square
  • u - Bullseye
  • V - Vertical line of spanning the full height of the chart.
<color>
The color of the markers for this series, in RRGGBBAA hexadecimal format - where AA Alpha Channel (transparency) is optional.
<series_index>
The zero-based index of the data series on which to draw the markers. When <marker_type> is set to 'C' a second data series is required, and this will be assumed to have an index one greater than the index supplied here. This parameter is ignored when <marker_type> is set to 'N'.
<opt_which_points>
[Optional] Which point(s) to draw markers on. Default is all markers. Ignored when <marker_type> is set to 'N'
<size>
The size of the marker, in pixels (or Font size when <marker_type> is set to 'N'). The H marker supports the syntax <size>[:width] where the optional second part specifies the line or marker length. Where this second part is omitted, the horizontal line will span the entire chart.
<opt_z_order>
[Optional] When supplied, any negative integer will cause the layer on which the marker is drawn, to be sent to the back of the Z Order.

Example

Description Image
Mark the X Axis zero value with a line in red (FF0000), send this to the back (behind bars) by setting the z-order to -1.

chm=H,FF0000,0,0,1,-1
Add bar value labels (in colour 0000AA) - show these labels as Euro currency with 2 decimal places and trailing zeros ("*cEUR2z*"). Change X Axis line to black (000000).

chm=H,000000,0,0,1,-1
chm=N*cEUR2z*,0000AA,,,8
Add a third data series and use this to add green (00FF00) line marks on each bar.

chm=H,000000,0,0,1,-1
chm=N*cEUR2z*,0000AA,,,8
chm=H,00FF00,2,0,1:30
Add a fourth and fifth data series, then use these to add blue (0000FF) rectangles on each bar.

chm=H,000000,0,0,1,-1
chm=N*cEUR2z*,0000AA,,,8
chm=H,00FF00,2,0,1:30
chm=C,0000FF,3,0,30


Advanced Examples

Description Image
There are no bars on this chart at all. It is plotted entirely with "Rectangle Markers".
This allows "bars" (i.e. rectangles) to not only be overlayed, but also to float above the X Axis - such as the right most bar which has a minimum value of 2%
All data series in the chd= parameter are "secondary data series" as "t:0" is used.

As in the previous example, there are no bars on this chart at all. It is plotted entirely with Circle, Square and Bullseye markers.