[#2458] Documented the plot module

ckanext/stats/public/ckanext/stats/javascript/modules/plot.js

@@ -1,14 +1,51 @@
+/* A quick module for generating flot charts from an HTML table. Options can
+ * be passed directly to flot using the data-module-* attributes. The tables
+ * are currently expected to be marked up as follows:
+ *
+ *   <table data-module="plot">
+ *     <thead>
+ *       <tr>
+ *         <th>X Axis</th>
+ *         <th>Series A Legend</th>
+ *         <th>Series B Legend</th>
+ *       </tr>
+ *     </thead>
+ *     <tbody>
+ *       <tr>
+ *         <th>X Value</th>
+ *         <td>Series A Y Value</td>
+ *         <td>Series B Y Value</td>
+ *       </tr>
+ *       ...
+ *     </tbody>
+ *   </table>
+ *
+ * Points are pulled out of the th/td elements using innerHTML or by looking
+ * for a data-value attribute. This is useful when a more readable value
+ * needs to be used in the elements contents (eg. dates). A data-type attribute
+ * can also be applied to parse the value. Only data-type="date" is currently
+ * supported and expects data-value to be a unix timestamp.
+ */
 this.ckan.module('plot', function (jQuery, _) {
   return {
+    /* Holds the jQuery.plot() object when created */
     graph: null,
+
+    /* Holds the canvas container when created */
     canvas: null,
+
+    /* Default options */
     options: {
       xaxis: {},
       yaxis: {},
       legend: {position: 'nw'},
       colors: ['#ffcc33', '#ff8844']
     },
 
+    /* Sets up the canvas element and parses the table.
+     *
+     * Returns nothing.
+     */
     initialize: function () {
       jQuery.proxyAll(this, /_on/);
 
@@ -17,30 +54,62 @@ this.ckan.module('plot', function (jQuery, _) {
       }
 
       this.setupCanvas();
+
+      // Because the canvas doesn't render correctly unless visible we must
+      // listen for events that reveal the canvas and then try and re-render.
+      // Currently the most common of these is the "shown" event triggered by
+      // the tabs plugin.
       this.sandbox.body.on("shown", this._onShown);
       this.data = this.parseTable(this.el);
 
       this.draw();
-
-      window.g = window.g || [];
-      window.g.push(this.graph);
     },
 
+    /* Removes event handlers when the module is removed from the DOM.
+     *
+     * Returns nothing.
+     */
     teardown: function () {
       this.sandbox.body.off("shown", this._onShown);
     },
 
+    /* Creates the canvas wrapper and removes the table from the document.
+     *
+     * Returns nothing.
+     */
     setupCanvas: function () {
       this.canvas = jQuery('<div class="module-plot-canvas">');
       this.el.replaceWith(this.canvas);
     },
 
+    /* Attempts to draw the chart if the canvas is visible. If not visible the
+     * graph does not render correctly. So we keep trying until it is.
+     *
+     * Examples
+     *
+     *   module.draw();
+     *
+     * Returns nothing.
+     */
     draw: function () {
       if (!this.drawn && this.canvas.is(':visible')) {
         this.graph = jQuery.plot(this.canvas, this.data, this.options);
       }
     },
 
+    /* Parses an HTML table element to build the data array for the chart.
+     * The thead element provides the axis and labels for the series. The
+     * first column in the tbody is used for the x-axis and subsequent
+     * columns are the series.
+     *
+     * table - A table element to parse.
+     *
+     * Examples
+     *
+     *   module.parseTable(module.el);
+     *
+     * Returns data object suitable for use in jQuery.plot().
+     */
     parseTable: function (table) {
       var data = [];
       var _this = this;
@@ -67,20 +136,70 @@ this.ckan.module('plot', function (jQuery, _) {
       return data;
     },
 
+    /* Retrieves the value from a td/th element. This first looks for a
+     * data-value attribute on the element otherwise uses the element
+     * text contents.
+     *
+     * A data-type attribute can also be provided to tell the module how
+     * to deal with the element. By default we let jQuery.data() handle
+     * the parsing but this can provide additional data. See .parseValue()
+     * for more info.
+     *
+     * cell - An element to extract a value from.
+     *
+     * Examples
+     *
+     *   var element = jQuery('<td data-value="10">Ten</td>');
+     *   module.getValue(element); //=> 10
+     *
+     *   var element = jQuery('<td>20</td>');
+     *   module.getValue(element); //=> 20
+     *
+     *   var element = jQuery('<td data-type="date">1343747094</td>');
+     *   module.getValue(element); //=> <Date Tue Jul 31 2012 16:04:54 GMT+0100 (BST)>
+     *
+     * Returns the parsed value.
+     */
     getValue: function (cell) {
       var item  = cell instanceof jQuery ? cell : jQuery(cell);
       var type  = item.data('type')  || 'string';
       var value = item.data('value') || item.text();
       return this.parseValue(value, type);
     },
 
+    /* Provides the ability to further format a value.
+     *
+     * If date is provided as a type then it expects value to be a unix
+     * timestamp in seconds.
+     *
+     * value - The value extracted from the element.
+     * type  - A type string, currently only supports "date".
+     *
+     * Examples
+     *
+     *   module.parseValue(10); // => 10
+     *   module.parseValue("cat"); // => "cat"
+     *   module.parseValue(1343747094, 'date'); // => <Date Tue Jul 31 2012 16:04:54 GMT+0100 (BST)>
+     *
+     * Returns the parsed value.
+     */
     parseValue: function (value, type) {
       if (type === 'date') {
         value = new Date(parseInt(value, 10) * 1000);
+        if (!value) {
+          value = 0;
+        }
       }
       return value;
     },
 
+    /* Event handler for when tabs are toggled. Determines if the canvas
+     * resides in the shown element and attempts to re-render.
+     *
+     * event - The shown event object.
+     *
+     * Returns nothing.
+     */
     _onShown: function (event) {
       if (!this.drawn && jQuery.contains(jQuery(event.target.hash)[0], this.canvas[0])) {
         this.draw();