Views-independent Highcharts API

Problem/Motivation

• This module in it's current state doesn't fully satisfy the http://dgo.to/highcharts namespace.
• The only current module name in the project repo is views_highcharts, logically supporting only Views integration.
• But there is no abstracted Drupal Highcharts API for modules to make use of apart from Views (there should be).
• Adding this allows us to leverage the entire Highcharts API without needing to define each type separately.

Proposed resolution

• Add a Views-independent highcharts.module, with abstracted functions which can be used by views_highcharts and other modules.
• Move views_highcharts.module to become an included sub-module, dependent on highcharts.module and using the new abstracted API functions.

Remaining tasks

• Currently a sandbox is at http://drupal.org/sandbox/scottrigby/1507774 (sandbox for now because I would prefer to merge efforts if possible) with 7.x-2.x and 6.x-2.x branches (anticipating this change may warrant a new 2x branch)
• Add more highcharts types example code for using the API functions. (however there are examples on highcharts.com already. And the current approach duplicating defaults in JSON is not sustainable - what happens when the API changes? Or even aside from that, why should modules need to override example defaults?)
• Modify views_highcharts to be a wrapper using those functions.
• In highcharts_render() check for all possible highchart options object callbacks (the sandbox module only addresses tooltip so far, but this is a working example for adding highchart options object methods, which can't be passed through Drupal.settings)

User interface changes

Nothing for the time being. The main API module has no UI, and the views_highcharts module can address UI changes in other tickets (since more functionality is now opened up for additional chart types etc).

API changes

There are two primary functions, theme_highcharts_chart() (returns HTML for a highcharts container), and highcharts_render() (renders a highcharts options object).

Modules may create highchart options objects (see http://www.highcharts.com/ref/), leveraging anything available in the highcharts API.

Example options object:

/**
 * Pie-basic highcharts options object.
 *
 * @see highcharts_render()
 */
function custom_pie_basic_options() {
  $options = new stdClass();

  // Chart.
  $options->chart = (object)array(
    'renderTo' => 'container',
    'plotBackgroundColor' => NULL,
    'plotBorderWidth' => NULL,
    'plotShadow' => FALSE,
  );

  // Title.
  $options->title->text = t('Pies');

  // Tooltip.
  // Normally formatter is a function callback. For now we'll make it a string.
  // @todo whenever this is user defined (views config, etc) be sure to sanitize
  // this string before passing to highcharts_render().
  $options->tooltip->formatter = "function() {return '<b>'+ this.point.name +'</b>: '+ this.percentage +' %';}";

  // Plot options.
  $options->plotOptions->pie = (object)array(
    'allowPointSelect' => TRUE,
    'cursor' => 'pointer',
    'dataLabels' => array(
      'enabled' => FALSE,
    ),
    'showInLegend' => TRUE,
  );

  // Series.
  $options->series = array();
  $series = new StdClass();
  $series->type = 'pie';
  $series->name = 'Slices';
  $series->data = array();
  $series->data[] = array('Banana creme', 45.0);
  $series->data[] = array('Pumpkin', 26.8);

  // Selected item is an object.
  $selected = new stdClass();
  $selected->name = 'Apple';
  $selected->y = 12.8;
  $selected->sliced = TRUE;
  $selected->selected = TRUE;
  $series->data[] = $selected;

  $series->data[] = array('Lemon merengue', 8.5);
  $series->data[] = array('Mincemeat', 6.2);
  $series->data[] = array('Others', 0.7);

  $options->series[] = $series;

  // Diable credits.
  $options->credits->enabled = FALSE;

  return $options;
}

Example implementation of new Drupal Highcharts API functions:

/**
 * Pie-basic highcharts block.
 *
 * @return hook_block() view op definition.
 */
function _custom_block_view_pie_basic() {
  $options = custom_pie_basic_options();
  if (is_object($options)) {
    // Render the chart options object, and retrieve the chart id.
    highcharts_render($options);
    // Define required and optional chart container attributes.
    $attributes = array(
      // Required chart id passed by reference.
      'id' => $options->chart->renderTo,
      // Optionally add styles or any other valid attribute.
      'style' => 'height: 400px;'
    );

    // Return block definition.
    return array(
      'subject' => check_plain($options->title->text),
      'content' => theme('highcharts_chart', $attributes),
    );
  }
}

Props

@stovak, nice work on revamping this module. I just feel it could be made more generically useful apart from the current Views-only approach.

@Matt V., thanks for your use of hook_requirements() and hook_theme() approach in your D6 backport from #1282546-3: Highcharts D6 version. This just needed to be more abstracted, enough to be useful to your filter approach, and views_highcharts (so we're not Druplicating code ;)