Charting API… Again!

<< It is an ancient device used many years ago by tribe members in their mating rituals.

Scientists believe that these were placed within another device to produce sounds, although there is no known evidence of these devices existing.

So, on to the charting API.

Balancing Graphs

Another graph has been born. The balancing graph, prevalent in the first few admin pages, has now been put inside a class named ”Balancing_Graph”.

This chart is used mainly for showing that systems are balanced (or unbalanced!) across nodes. The first step to using it is to create it and setup a few constants:

$chart = new Balancing_Chart();

$chart->min_height = 13;
$chart->misc_add_until_sum_greater = true;
$chart->disable_column_sort = false;

All constants are optional. min_height specifies the minimum height of any given cell (remember that the text size is 13).

misc_add_until_sum_greater alternates between the two modes of calculating which cells are miscellaneous. If true, then the miscellaneous cell will be as small as possible without exceeding the min height. If false, then every single cell will be larger than the min_height, and the misc cell will encapsulate all of the cells that are smaller than min_height. The second one gives a more accurate representation of what the actual size of the column is, but the misc cell can get to be quite large. Imagine a data set where every single individual piece is smaller than 13px: setting this to false will turn everything into a single giant miscellaneous cell.

disable_column_sort is fairly self-explanatory. If false, then column sort is enabled, and at the start of a render the columns will be sorted by name. The default, true, leaves columns sorted in whatever order the class was first made aware of the column.

The next step is to define the callbacks:

$chart->setCellFn('cell_user_function');
$chart->setMiscCellFn('misc_cell_user_function');
$chart->setColumnFn('col_user_function');
$chart->setCellValueFn('cell_get_index_fn');
$chart->setHeightFn('cell_get_height_fn');

All callbacks are optional*. setCellFn sets the function that is called when a cell is rendered. It is called once per cell. It outputs whatever you want the cell to display: You can more or less anything, but stay away from tables and divs. That would be HTML injection, which is bad. It takes a single argument, which is the user data for the cell.

setMiscCellFn does the same thing, except it does it for the miscellaneous cell, and it takes two arguments: The summed value, and a list of all of the cells that were determined to be miscellaneous. It is called once per column at most. If it is not specified, then miscellaneous cells will not be calculated. Be warned.

setColumnFn renders the column’s header text. It is passed the column name, and the list of cells within that column. Again, called once per column. The default is to print whatever the column name is.

setCellValueFn… even though it’s optional, don’t forget it. This function takes in a single argument, the cell, and outputs a single scalar value which is used to determine the sort order, height of cells, which cells are miscellaneous, etc.

setHeightFromCellFn figures out the height of a cell given the cell’s user data. This contrasts with setHeightFn, which calculates the height given the cell’s value.

Last, and least, is setHeightFn. Notice how it isn’t even included in the example. This function is called to figure out the height of a cell given it’s scalar value. If it is not specified, then it will (by default) calculate the height by multiplying the value of the cell by it’s “height_scalar” attribute. By default the height_scalar attribute equals five point six. (I hate fractions at the end of sentences!)

Then, you have to set the data for the chart. It’s easy: Run addCell over and over until you’ve added all of the cells. If you want to be picky, there’s an addColumn function also, but… I don’t really care about that. Neither does the API. By the time you get there, it might even be gone. addCell takes three arguments: The column name, the cell name, and the cell user data. If the column name doesn’t exist, then the column is created. The cell name must be unique within the column. The cell user data is what is passed to most of the functions that take a ‘cell’ as an argument: The ‘cell’ is actually this user data. Here’s the code that generated the example image at the top of the page:

for ($i=0; $i<7; $i+=1) {
   for ($j=0; $j<$i; $j+=1) {
      $chart->addCell("column $i", "cell $j", array("cell $j", $j));
   }
}

Then, after having added all of the data, you can render the chart with a single function call:

$chart->render();

• You might not like the defaults.

MySQL-Style Data Entry

In response to popular request, I’ve rounded off some of the edges to the MySQL data entry method for line charts. Table charts already have this as their default data input method, so I won’t discuss that here.

MySQL data comes in ordered rows, directly from mysql_query_all or similar. It isn’t an associative array. Each row must contain at least three elements: a value which defines the X-position, a value which defines the Y-position at that X-position, and a value which defines what series we’re a part of.

The meta has values that directly correlate with the above three variables:

Note that this data form completely overrides the entire notion of having series’s be associative arrays with data.

Summary

• Balancing Graphs
• MySQL Data Entry