BPCharts

Overview
Getting Started
Colors (chco)
Line Styles (chls)
Axis Definitions (chxt, chxr, chxl, chxs)
Grid Lines (chgx)
Fills (chf)
Chart Marker (chm=ht)
Line Fills (chm=b/B/VLG)
Fonts and Font Sizes (chft and chfts)
Margins (chmg)
Advanced Examples

Overview

The line chart is one of the most flexible charts in BPCharts. It 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 lc.

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:13,8,6,11,8, 9,5,8,7,12`
As with all charts, you can specify data using different data encodings. See data encodings for more information.	`chd=s:sengelha`
Missing values will be drawn as gaps.	`s:sen_elha`
Multiple lines can be drawn by specifying multiple data sets.	`chd=s:sengelha, BOBCASEY`
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.

Syntax

chco=<color_1>|...|<color_n>

<color>: The color, in RRGGBB or RRGGBBAA format, to apply to the line.

Example

Description	Image
Draw the line in red (`FF0000`).	`chco=FF0000`
Make the first line red (`FF0000`) and the second line green (`00FF00`).	`chd=s:sengelha, BOBCASEY chco=FF0000\|00FF00`

Line Styles (`chls`)

Syntax

chls=<thickness_1>,<opt_dash_length_1>,<opt_space_length_1>
     |...|
     <thickness_n>,<opt_dash_length_n>,<opt_space_length_n>

<thickness>: The thickness of the line.
<opt_dash_length>,<opt_space_length>: [Optional] Used to define dashed 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.

Example

Description	Image
Draw a three pixel thick line.	`chls=3`
Draw a dashed line.	`chls=1,4,2`

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.

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>,<opt_alignment>,<opt_axis_or_tick>,<opt_tick_color>
|...|<axis_index_n><opt_format_string>,<opt_label_color>,<opt_font_size>,<opt_alignment>,<opt_axis_or_tick>,<opt_tick_color>

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

<opt_alignment>

[Optional] If supplied, this parameter should always be -1.

<opt_axis_or_tick>

[Optional] Whether to show tick marks and/or axis lines for this axis. Use one of the following values:

l (lowercase 'L') - Draw axis line only.
t - Draw tick marks only. Tick marks are the little lines next to axis labels.
lt - Draw both an axis line and tick marks for all labels.
_ - (Underscore) Draw neither axis line nor tick marks. If you want to hide an axis line, use this value.

<opt_tick_color>

[Optional]The color, in RRGGBB or RRGGBBAA format, to apply to the axis 'tick marks'.

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=0Nf0%,FF0000,12`
Display an x-axis on the bottom of the chart with labels every other year. Enable the axis-line with tick-marks in blue.	`chxt=x chxl=0:\|\|1999\|\|2000\|\|2001 chxs=0,000000,10,-1,lt,0000FF`

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>,<opt_z_order>
     |...|
     <axis>,<opt_dash_length>,<opt_space_length>,<opt_color>,<opt_thickness>,<opt_z_order>

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

<opt_z_order>

[Optional] When supplied, any negative integer will cause the grid lines to be sent to the back of the Z Order.

NOTE: Both horizontal and vertical grid lines must share the same Z Order. Sending either to the back, will cause both to be sent to the back.

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`

Line Fills (`chm=b/B/VLG`)

You can fill the area below a data line with a solid color or a vertical linear gradient.

Syntax

chm=<b_or_B_or_VLG>,<color>,<start_line_index>,<end_line_index>,<0>
     |...|
     <b_or_B_or_VLG>,<color>,<start_line_index>,<end_line_index>,<0>

<b_or_B_or_VLG>

Whether to fill to the bottom of the chart, or just to the next lower line.

B - Fill from <start_line_index> to the bottom of the chart with a solid color.
b - Fill between two lines in a multi-line chart. Start and end lines are indicated by <start_line_index> and <end_line_index>.
VLG - Fill from <start_line_index> to the bottom of the chart with a vertical linear gradient from the color to the background color.

<color>

The color, in RRGGBB or RRGGBBAA format, to fill the area.

<start_line_index>

The index of the line at which the fill starts. The first data series specified in chd has an index of zero (0), the second data series has an index of 1, and so on.

<end_line_index>

Fill type 'b' - The line at which to stop the fill. This line must be below the current line.
Fill type 'B' - This value is ignored.
Fill type 'VLG' - This value is ignored.

<0>

Reserved. Must be 0.

Example

Description	Image
Fill the entire area underneath a line with a blue color (`76A4FB`).	`chm=B,76A4FB,0,0,0`
Fill the two areas between three lines with two different colors.	`chd=s:cefhjkqwrlgYcfgc, QSSVXXdkfZUMRTUQ, HJJMOOUbVPKDHKLH chm=b,224499,0,1,0\| b,FF0000,1,2,0`
Fill the entire area underneath a line with a vertical linear gradient from blue (`76A4FB`) to the default background (white)	`chm=VLG,76A4FB,0,0`
Fill the entire area underneath a line with a vertical linear gradient from white (`FFFFFF`) to a black background (`000000`).	`chm=VLG,FFFFFF,0,0 chf=bg,s,000000 chco=FFFFFF`

Chart Marker (`chm=ht`)

You can add text to the chart.

Syntax

chm=ht<text>,<color>,<x_coordinate>,<y_coordinate>,<font_size>
     |...|
     ht<text>,<color>,<x_coordinate>,<y_coordinate>,<font_size>

<text>: The text to write in the chart
<color>: The color, in RRGGBB or RRGGBBAA format of the text.
<x_coordinate>: Percentage based x coordinate. 0 is left, 100 is right (out of chart)
<y_coordinate>: Value based y coordinate.
<font_size>: The Fontsize

Example

Description	Image
Write some text into the chart	`chm=htWrite something here,37629B,30,70,7`

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`

TODO

Locale (locale)
Axis label gap (chxlg)
Markers (horizontal lines and vertical lines) (chm)

Advanced Examples

Description	Image
This chart is used in EDM. It demonstrates multiple lines, a gradient fill, horizontal chart markers, and custom axis ranges.
This chart is used in the Target Date Report. It demonstrates chart area fills and inter-line fills.
This chart demonstrates custom grid lines, axis labels, and extended encoding with data scaling.
This chart demonstrates removing the vertical grid lines and adding a vertical line marker.

BPCharts

Table of Contents

Overview

Getting Started

Colors (chco)

Syntax

Example

Line Styles (chls)

Syntax

Example

Axis Definitions (chxt, chxr, chxl, chxs)

Syntax

Example

Grid Lines (chgx)

Syntax

Example

Fills (chf)

Syntax

Example

Line Fills (chm=b/B/VLG)

Syntax

Example

Chart Marker (chm=ht)

Syntax

Example

Fonts and Font Sizes (chft and chfts)

Syntax

Example

Margins (chmg)

Syntax

Example

TODO

Advanced Examples

Colors (`chco`)

Line Styles (`chls`)

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

Grid Lines (`chgx`)

Fills (`chf`)

Line Fills (`chm=b/B/VLG`)

Chart Marker (`chm=ht`)

Fonts and Font Sizes (`chft` and `chfts`)

Margins (`chmg`)