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"></canvas>
        
        <script type="text/javascript">
          var g = new Bluff.Line('graph', 300);
          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();

Options

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

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.

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_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_title

Set to true to prevent the title being rendered.

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

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.

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, transpose = false)

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 transpose, if set to true, will cause Bluff to pick the opposite orientation to the one it would have picked automatically.

g.draw()

Renders the graph.

g.replace_colors(color_list)

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

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.font = 'Georgia'.

g.set_margins(value)

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