Bluff API reference

This reference lists all the options and public methods in Bluff.Base, from which all other graph implementations inherit. Some graph types have specific data requirements; see the data() method documentation for more information.

Usage pattern

All graphs will follow the following basic usage pattern:

  // Make a graph object with canvas id and width
  var g = new Bluff.Line('example', 400);

  // Set theme and options
  g.theme_keynote();
  g.title = 'My Graph';

  // Add data and labels
  g.data('Apples', [1, 2, 3, 4, 4, 3]);
  g.data('Oranges', [4, 8, 7, 9, 8, 9]);
  g.data('Watermelon', [2, 3, 1, 5, 6, 8]);
  g.data('Peaches', [9, 9, 10, 8, 7, 9]);
  g.labels = {0: '2003', 2: '2004', 4: '2005'};

  // Render the graph
  g.draw();

The default aspect ratio for the graph is 4:3. If you want to set the height by hand, supply a string instead of a number for the graph size:

  var g = new Bluff.Line('example', '800x300');

The list of graph types currently supported is:

Data from HTML tables

As well as specifying data explicitly as above, Bluff also allows you to pull data from an HTML table. Make sure you use <th> tags for series headings so that these cells are not mistaken for data. For example:

Annual Fruit Sales
Apples Oranges Watermelon Peaches
1 4 2 9
2003 2 8 3 9
3 7 1 10
2004 4 9 5 8
4 8 6 7
2005 3 9 8 9 
  <table id="data">
    <caption>Annual Fruit Sales</caption>
    <thead>
      <tr>
        <th scope="col"></th>
        <th scope="col">Apples</th>
        <th scope="col">Oranges</th>
        <th scope="col">Watermelon</th>
        <th scope="col">Peaches</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope="row"></th>
          <td>1</td> <td>4</td> <td>2</td> <td>9</td>
      </tr>
      <tr>
        <th scope="row">2003</th>
          <td>2</td> <td>8</td> <td>3</td> <td>9</td>
      </tr>
      <tr>
        <th scope="row"></th>
          <td>3</td> <td>7</td> <td>1</td> <td>10</td>
      </tr>
      <tr>
        <th scope="row">2004</th>
          <td>4</td> <td>9</td> <td>5</td> <td>8</td>
      </tr>
      <tr>
        <th scope="row"></th>
          <td>4</td> <td>8</td> <td>6</td> <td>7</td>
      </tr>
      <tr>
        <th scope="row">2005</th>
          <td>3</td> <td>9</td> <td>8</td> <td>9</td>
      </tr>
    </tbody>
  </table>
  <canvas id="graph" width="300" height="225"></canvas>

  <script type="text/javascript">
    var g = new Bluff.Line('graph', '300x225');
    g.theme_odeo();
    g.data_from_table('data');
    g.draw();
  </script>

Themes

A theme is the set of colors used to render a graph. Themes must be set before other color options and before data is added. They can be set manually, or you can use one of the built-in themes. To set it manually, supply a set of colors, a marker_color, a font_color and one or more background_colors:

  g.set_theme({
    colors: ['#202020', 'white', '#a21764', '#8ab438',
             '#999999', '#3a5b87', 'black'],
    marker_color: '#aea9a9',
    font_color: 'black',
    background_colors: ['#ff47a4', '#ff1f81']
  });

The built-in themes are set using methods. The available themes are:

  g.theme_keynote();
  g.theme_37signals();
  g.theme_rails_keynote();
  g.theme_odeo();
  g.theme_pastel();
  g.theme_greyscale();

Tooltips

Some graph types support tooltips, that is they allow you to hover the mouse over a data point to see the name and value of the point in a popup box next to the mouse. This box can be styled using CSS; its markup is as follows:

  <div class="bluff-tooltip">
    <span style="color: #abcdef;">&bull;</span>
    <span class="label">Data series name</span>
    <span class="data">42</span>
  </div>

To enable tooltips, just set g.tooltips = true when setting up a graph. Tooltip support is available on the following graph types:

Options

Options are set before data is added to the graph using the syntax g.foo = 'value'.

bar_spacing

(Bluff.Bar, Bluff.StackedBar, Bluff.Mini.Bar, Bluff.SideBar, Bluff.SideStackedBar, Bluff.Mini.SideBar.) Sets how much of the available space a bar’s width takes up. Should be a value between 0 and 1, where 1 leaves no space between bars and 0 produces bar with zero width.

baseline_value, baseline_color

(Bluff.Line only.) Sets a value at which to draw a horizontal line on the graph as a ‘baseline’. The default color is red, use baseline_color to change this.

dot_radius

(Bluff.Line, Bluff.Net only.) Sets the radius of dots used to plot data points.

font_color

Sets the color used to render text, specified as a CSS-style string, e.g. g.font_color = '#ad845c'. This value must be set after setting the theme for the graph.

*_font_size

Sets the size used to render various textual fragments of the graph. Options include title_font_size, legend_font_size and marker_font_size, all of which should be numbers. Values will be scaled; you should supply pixel values intented for a graph 800px wide.

hide_dots

(Bluff.Line, Bluff.Net only.) Set to true to prevent drawing dots at data points.

hide_labels_less_than

(Bluff.Pie only.) Sets a minimum percentage (0 to 100) required for a text label to be printed for a slice. Slices smaller than this will not get text labels. Use 0 to show all labels. e.g. g.hide_labels_less_than = 10.

hide_legend

Whether the legend should be hidden (true) or not (false).

hide_lines

(Bluff.Line only.) Set to true to prevent drawing of lines; dots will still be rendered.

hide_line_markers

Set to true to hide line markers.

hide_line_numbers

Line numbers are not rendered if this is set to true.

hide_mini_legend

(Bluff.Mini.* types only.) Set to true to hide the legend in mini graphs.

hide_title

Set to true to prevent the title being rendered.

legend_position

(Bluff.Mini.* types only.) Sets where the legend is placed in relation to the graph. Possible values are 'right' and 'bottom', 'bottom' is the default.

line_width

(Bluff.Line, Bluff.Net only.) Sets the widths of the lines used to join data points.

*_margin

Four options – top_margin, right_margin, bottom_margin and left_margin – set the padding around the edge of the canvas. Values should be numbers, representing pixel offsets relative to a graph 800px wide. So, for example if you set g.top_margin = 40 for a graph 400px wide, the actual margin rendered will be 20px.

Since version 0.3.5, title_margin and legend_margin can be used to alter the spacing under the title and legend respectively.

marker_color

CSS color used to render markers, e.g. g.marker_color = '#f5ac34'.

marker_count

Sets the number of horizontal marker lines rendered.

minimum_value, maximum_value

Use these options if you want the range rendered on the axes to extend beyond the range of the data. You must set these values after you’ve supplied all the data to the graph.

no_data_message

Sets the text to display if the graph has no data, e.g. g.no_data_message = 'No data'.

sort

Set to false if you don’t want the data to be sorted with the largest average values at the back.

title

Sets the title of the graph, printed at the top. Should be a string.

tooltips

Set to true to enable on-mouse-hover tooltips. See ‘Tooltips’ above for more information.

x_axis_label

Assign a string to this option to have it printed below the x axis of the graph.

y_axis_increment

Sets the distance between horizontal marker lines.

zero_degree

(Bluff.Pie only.) Sets the angle at which to begin drawing, in degrees.

Methods

Bluff.Base defines the following methods for modifying your graph. Note that none of these methods re-draw the graph, you must call g.draw() for that.

g.add_color(color)

Adds color to the list of available colors used for drawing lines/bars.

g.clear()

Clears the canvas and removes all text nodes used to render the graph.

g.data(name, data_points, color)

Adds a data series to the graph. name is a string used to render the legend, data_points is an array of numbers, and color is an optional string to specify the color used to render the series. If no color is given, one is picked from the graph’s theme settings.

Some graph types have specific data requirements:

g.data_from_table(table, options = {})

Adds data and labels to the graph by scanning the given table element. table may be an ID string or an HTMLElement reference to a <table>.

The table scanner will usually make a reasonable guess as to the orientation (row- or column-wise) of the data series in the table; the optional parameter orientation can be used to override this. Calling g.data_from_table('foo', {orientation: 'rows'}) maps the rows to data series, while a value of 'cols' maps the columns to data series.

You can also tell it to omit parts of the table using the except option. For example, g.data_from_table('foo', {except: ['Total', 'Users']}) will ignore data in any row or column whose title is Total or Users.

g.draw()

Renders the graph.

g.replace_colors(color_list)

Replaces all the colors in the graph with the array color_list.

g.set_background(options)

Can be used to just set the background color if you don’t want to set all the colors through g.set_theme(). For example, g.set_background({colors: ['#d1edf5', 'white']}).

g.set_font(font)

Sets the font used to render textual content. Arial is used by default; bear in mind you should only use widely available fonts as the text is rendered using regular HTML nodes. Should be a string, e.g. g.set_font('Georgia').

g.set_margins(value)

Sets the top_margin, right_margin, bottom_margin and left_margin to value.