Home

Charts

All charts are drawn using a single function. This ensures consistency in figure setup, while also making the API easier to use. Figures consist of the chart proper, which is a svg canvas containing the chart + key, and the figure legend, which contains a title and longer description. This mimics the style in scientific journals allowing you to present data in a manner intuitive to your users.

How to draw a chart

1. Load the API into the page you would like your diagram using <php tripald3_load_libraries();?>
2. Retrieve you data and manipulate it into the structure required by the chart. This can be done a number of ways, the easiest of which is to query your database in your Drupal preprocess hook and then save the results as a javascript setting.

/**
 * Preprocess hook for template my_example.tpl.php
 * The module name is demo.
 */
function demo_my_example_preprocess(&$variables) {

  // Load the API (Step #1 above)
  tripald3_load_libraries();

  // Retrieve your data.
  $resource = chado_query("SELECT feature_type, num_features FROM {organism_feature_count} WHERE organism_id=:id",
    array(":id" => 1));
  $data = array();
  foreach ($resource as $r) {
    // Save it in the structure required for a simple pie chart.
    $data[] = array(
      "label" => $r->feature_type,
      "count" => $r->num_features,
    );
  }

  // Make it available to javascript via settings.
  $settings = array(
    // Always namespace to your module to avoid collisions.
    'demo' => array(
      // Pass in your data using a descriptive settings key.
      'featureTypePieData' => $data,
    ),
  );
  drupal_add_js($settings, 'setting');
}

3. Draw the chart in your template by calling tripalD3.drawChart(). This is done within a script tag using Drupal behaviours to ensure it is run at the correct point and the data prepared is passed in.

<script type="text/javascript">
  Drupal.behaviors.tripalD3demoSimplePie = {
    attach: function (context, settings) {

      // Pull the data out of the javascript settings.
      var data = Drupal.settings.demo.featureTypePieData;
    
      // Draw your chart.
      tripalD3.drawFigure(
        data,
        {
          "chartType" : "simplepie",
          "elementId": "tripald3-simplepie",
          "height": 250,
          "width": 500,
          "keyPosition": "right",
          "title": "Proportion of <em>Tripalus databasica</em> Feature Types",
          "legend": "The above pie chart depicts the ratio of feature types available for <em>Tripalus databasica</em>.",
        }
      );
    }
  };
</script>

4. There is no step #4. You're done!

General Options

The following options are supported for all charts:

• chartType: the type of chart to draw; (REQUIRED) one of pedigree, simplepie, simpledonut, multidonut, simplebar.
• elementId : The ID of the HTML element the diagram should be attached to.
• width: The width of the drawing canvas (including key and margins) in pixels.
• height: The height of the drawing canvas (including key and margins) in pixels.
• title: the title of the figure diagram.
• legend: a longer description of the diagram to be used as the figure legend following the title. This should include all relevant scientific information as well as instructions on how to interact with the chart.
• margin: an object with 'top', 'right','bottom','left' keys. Values are in pixels and all four keys must be set.
• chartOptions: an object containing options to be passed to the chart. See chart documentation to determine what options are available.
• drawKey: whether or not to draw the key; default is "true".
• keyPosition: control the position of the key on your figure; supported options include right (default) or left.
• keyWidth: the key is fixed width; default width is 250 (pixels).
• key: an object containing additional options for the key. See "drawKey" function for all available options. Some include:
  • title: the title of the key; default "Legend".
  • margin: an object with 'top', 'right','bottom','left' keys. Values are in pixels and all four keys must be set.

While only the chartType is required, it is highly recommended you also provide the elementId, title and legend for all charts to fully explain the chart to your users.