BPCharts

   

Table of Contents

  1. Overview
  2. Getting Started
  3. Colors (chco)
  4. Bar Width and Spacing (chbh)
  5. Axis Definitions (chxt, chxr, chxl, chxlg, 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. Title (chtt and chts)
  13. Advanced Examples

Overview

The horizontal grouped 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 bvg.



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)
chs=150x150
By default, SVG output format uses Points rather than Pixels for the chart width and height.
This can cause anti-aliasing (edges not sharp or precise) when scaled to pixel equivalents.
You can add an optional ",px" attribute to the chs parameter to use Pixels instead.
(This will only work with SVG charts)
chof=s (SVG)
chs=150x150,px


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.
  • 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. 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.
Note: If a bar width in pixels is specified using <bar_width_or_scale>, you may also specify <space_between_bars> but <space_between_groups> will be ignored. <space_between_groups> will be the remaining space after the first two parameters have been satisfied.

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

Example

Description Image
The chart adds some spacing (15 pixels) between groups.
chbh=a,5,15


Axis Definitions (chxt, chxr, chxl, chxlg, chxs)

You can control chart axes using the chxt, chxr, chxl, chxlg, and chxs 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 chxlg option allows you to manually specify the gap between the labels for an axis and the axis itself.

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

Note: For backwards compatibility reasons, this chxs parameter is ignored unless the Chart Version is greater than zero.
You specify the Chart Version (default version is zero) by using the CHVS= parameter.
If you want to use chxs, then include the following in the BpChart URL... 
&chvs=1

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>

chxlg=<axis_1>,<gap_1>
|...|<axis_n>,<gap_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 omitted. 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 omitted. 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 ("").
<gap>
The gap, in pixels for raster formats and points for vector formats, between the axis labels and the axis.
<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
chvs=1
Display a x-axis on the bottom of the chart with labels every other year.
chxt=x
chxl=0:||2012||2013||2014||2015
Create a 20-pixel gap between the labels of the y-axis on the left of the chart and the chart itself.
chxlg=y,20


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
  • c - + Cross
  • x - x Cross
  • u - Up pointing triangle
  • d - Down pointing triangle
  • l - Left pointing triangle
  • r - Right pointing triangle

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=D/H/ht/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>,<opt_placement>,<opt_font_angle>,<opt_line_style>
        |...|
      [@]<marker_type>,<color>,<series_index>,<opt_which_points>,<size>,<opt_z_order>,<opt_placement>,<opt_font_angle>,<opt_line_style>
<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. If the number of data-points in the line, is not the same as the number of bar groups, then the line will be scaled to fit the X Axis. If this scaling is active and you have specified both a primary (left) Y Axis and a secondary (right) Y Axis, then the line data will also be scaled to this secondary (right) Y Axis. See the example chart at the end of this 'Markers' section.
  • H - Horizontal line of spanning the full width of the chart.
  • ht - Horizontal Text at a given position - the required text should follow immediately after the "ht" in the following format...
    chm=
       ht<text>,<color>,<x_coordinate>,<y_coordinate>,<font_size>
         |...|
       ht<text>,<color>,<x_coordinate>,<y_coordinate>,<font_size>
  • 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.
This parameter is interpreted as <x_coordinate> for marker type "ht". This is a percentage based x coordinate. 0 is left, 100 is right (out of chart).
This parameter is ignored when <marker_type> is set to 'N' unless the Chart Version is greater than zero. You specify the Chart Version (default version is zero) by using the CHVS= parameter. If you want to have different data-value-marker styling for each time series, then include the following in the BpChart URL... 
&chvs=1

<opt_which_points>
[Optional] The zero-based index of the data-point on which to draw a marker (i.e. set to 2 for marker on the the third bar group). Default is all markers.
This parameter is interpreted as <y_coordinate> for marker type "ht" (and is not optional for this Marker Type). This is a value based y coordinate, and must be between the minimum and maximum y values on the chart.
This parameter is ignored when marker-type is 'N' unless chart-version is set greater than zero using 'chvs='
<size>
The size of the marker, in pixels (or <font_size> when <marker_type> is set to 'N' or 'ht').
<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.
<opt_placement>
[Optional] This parameter is ignored unless <marker_type> is set to 'N' and the Chart Version is greater than zero. You specify the Chart Version (default version is zero) by using the CHVS= parameter.
When this parameter is supplied, both an X Offset and a Y Offset in pixels must be given, separated by ':'. For example '0:-10' will move the data-value markers up by 10 pixels.
<opt_font_angle>
[Optional] This parameter is ignored unless <marker_type> is set to 'N'
When this parameter is supplied, the font used for the data-value markers will be rotated anti-clockwise by the number of degrees that the parameter specifies.
For instance, setting this parameter to 90 will result in vertical text being used for the data-value markers.
<opt_line_style>
[Optional] Only applies to marker types "D", "V" and "H".
When supplied, it should be one of the following: "dash", "dot","dot-dash", or "alt-dash"

Example

Description Image

chm=H, Mark the X Axis zero value with a line in black (000000), send this to the front (in front of bars and lines) by setting the z-order to 1.

chm=N, Add data-value markers for data-series zero and one i.e. the bars (Markers have one decimal place with trailing zero = *f1z* , and use 6pt font rotated anti-clockwise by 90 degrees. Markers for series zero are RED and offset 2 pixels to the left. Markers for series one are BLUE and offset 2 pixels to the right.)

chm=D, Add line-trace markers for data-series two and three, send these to the front by setting the z-order to 1.

chm=H,000000,0,0,1,1
chm=N*f1z*,FF0000,0,,6,,-2:0,90
chm=N*f1z*,0000FF,1,,6,,2:0,90
chm=D,E96610,2,0,2,1
chm=D,728EB2,3,0,2,1
chvs=1


Chart Title (chtt, chts)

You can specify the title text, color, and font size for your chart.

Syntax

chtt=<chart_title>
chts=<color>,<font_size>,<opt_alignment>

 

chtt - Specifies the chart title.

<chart_title>
Title to show for the chart. You cannot specify where this appears, but you can optionally specify the font size and color. Use a + sign to indicate spaces, and a pipe character ( | ) to indicate line breaks.

 

chts [Optional] - Colors and font size for the chtt parameter.

<color>
The title color, in RRGGBB hexadecimal format. Default color is black.
<font_size>
Font size of the title, in points.
<opt_alignment>
[Optional] Alignment of the title. Choose one of the following case-sensitive string values: "l" (left), "c" (centered) "r" (right). Default is "c".

Example

Description Image

chtt=This+is+a+two+line|Chart+Title

chts=ff0000,10,c

chtt=This+is+a+two+line|Chart+Title
chts=ff0000,10,c


Advanced Examples

Description Image
This chart shows number markers above the bars.
This chart demonstrates removing the vertical grid lines and adding a vertical line marker.
There are no bars on this chart at all. It is plotted entirely with Circle, Square and Bullseye markers.

Again, this chart is plotted entirely with markers. Here we include a legend, and specify both square and circle legend icons.