[Summary view] [Print] [Text view]

   1  // This file is part of Moodle - http://moodle.org/
   2  //
   3  // Moodle is free software: you can redistribute it and/or modify
   4  // it under the terms of the GNU General Public License as published by
   5  // the Free Software Foundation, either version 3 of the License, or
   6  // (at your option) any later version.
   7  //
   8  // Moodle is distributed in the hope that it will be useful,
   9  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  // GNU General Public License for more details.
  12  //
  13  // You should have received a copy of the GNU General Public License
  14  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  15  
  16  /**
  17   * Chart series.
  18   *
  19   * @package    core
  20   * @copyright  2016 Frédéric Massart - FMCorz.net
  21   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  22   * @module     core/chart_series
  23   */
  24  define([], function() {
  25  
  26      /**
  27       * Chart data series.
  28       *
  29       * @class
  30       * @alias module:core/chart_series
  31       * @param {String} label The series label.
  32       * @param {Number[]} values The values.
  33       */
  34      function Series(label, values) {
  35          if (typeof label !== 'string') {
  36              throw new Error('Invalid label for series.');
  37  
  38          } else if (typeof values !== 'object') {
  39              throw new Error('Values for a series must be an array.');
  40  
  41          } else if (values.length < 1) {
  42              throw new Error('Invalid values received for series.');
  43          }
  44  
  45          this._colors = [];
  46          this._label = label;
  47          this._values = values;
  48      }
  49  
  50      /**
  51       * The default type of series.
  52       *
  53       * @type {Null}
  54       * @const
  55       */
  56      Series.prototype.TYPE_DEFAULT = null;
  57  
  58      /**
  59       * Type of series 'line'.
  60       *
  61       * @type {String}
  62       * @const
  63       */
  64      Series.prototype.TYPE_LINE = 'line';
  65  
  66      /**
  67       * The colors of the series.
  68       *
  69       * @type {String[]}
  70       * @protected
  71       */
  72      Series.prototype._colors = null;
  73  
  74      /**
  75       * The label of the series.
  76       *
  77       * @type {String}
  78       * @protected
  79       */
  80      Series.prototype._label = null;
  81  
  82      /**
  83       * The labels for the values of the series.
  84       *
  85       * @type {String[]}
  86       * @protected
  87       */
  88       Series.prototype._labels = null;
  89  
  90      /**
  91       * Whether the line of the serie should be smooth or not.
  92       *
  93       * @type {Bool}
  94       * @protected
  95       */
  96      Series.prototype._smooth = false;
  97  
  98      /**
  99       * The type of the series.
 100       *
 101       * @type {String}
 102       * @protected
 103       */
 104      Series.prototype._type = Series.prototype.TYPE_DEFAULT;
 105  
 106      /**
 107       * The values in the series.
 108       *
 109       * @type {Number[]}
 110       * @protected
 111       */
 112      Series.prototype._values = null;
 113  
 114      /**
 115       * The index of the X axis.
 116       *
 117       * @type {Number[]}
 118       * @protected
 119       */
 120      Series.prototype._xaxis = null;
 121  
 122      /**
 123       * The index of the Y axis.
 124       *
 125       * @type {Number[]}
 126       * @protected
 127       */
 128      Series.prototype._yaxis = null;
 129  
 130      /**
 131       * Create a new instance of a series from serialised data.
 132       *
 133       * @static
 134       * @method create
 135       * @param {Object} obj The data of the series.
 136       * @return {module:core/chart_series}
 137       */
 138      Series.prototype.create = function(obj) {
 139          var s = new Series(obj.label, obj.values);
 140          s.setType(obj.type);
 141          s.setXAxis(obj.axes.x);
 142          s.setYAxis(obj.axes.y);
 143          s.setLabels(obj.labels);
 144  
 145          // Colors are exported as an array with 1, or n values.
 146          if (obj.colors && obj.colors.length > 1) {
 147              s.setColors(obj.colors);
 148          } else {
 149              s.setColor(obj.colors[0]);
 150          }
 151  
 152          s.setSmooth(obj.smooth);
 153          return s;
 154      };
 155  
 156      /**
 157       * Get the color.
 158       *
 159       * @return {String}
 160       */
 161      Series.prototype.getColor = function() {
 162          return this._colors[0] || null;
 163      };
 164  
 165      /**
 166       * Get the colors for each value in the series.
 167       *
 168       * @return {String[]}
 169       */
 170      Series.prototype.getColors = function() {
 171          return this._colors;
 172      };
 173  
 174      /**
 175       * Get the number of values in the series.
 176       *
 177       * @return {Number}
 178       */
 179      Series.prototype.getCount = function() {
 180          return this._values.length;
 181      };
 182  
 183      /**
 184       * Get the series label.
 185       *
 186       * @return {String}
 187       */
 188      Series.prototype.getLabel = function() {
 189          return this._label;
 190      };
 191  
 192      /**
 193       * Get labels for the values of the series.
 194       *
 195       * @return {String[]}
 196       */
 197      Series.prototype.getLabels = function() {
 198          return this._labels;
 199      };
 200  
 201      /**
 202       * Get whether the line of the serie should be smooth or not.
 203       *
 204       * @returns {Bool}
 205       */
 206      Series.prototype.getSmooth = function() {
 207          return this._smooth;
 208      };
 209  
 210      /**
 211       * Get the series type.
 212       *
 213       * @return {String}
 214       */
 215      Series.prototype.getType = function() {
 216          return this._type;
 217      };
 218  
 219      /**
 220       * Get the series values.
 221       *
 222       * @return {Number[]}
 223       */
 224      Series.prototype.getValues = function() {
 225          return this._values;
 226      };
 227  
 228      /**
 229       * Get the index of the X axis.
 230       *
 231       * @return {Number}
 232       */
 233      Series.prototype.getXAxis = function() {
 234          return this._xaxis;
 235      };
 236  
 237      /**
 238       * Get the index of the Y axis.
 239       *
 240       * @return {Number}
 241       */
 242      Series.prototype.getYAxis = function() {
 243          return this._yaxis;
 244      };
 245  
 246      /**
 247       * Whether there is a color per value.
 248       *
 249       * @return {Bool}
 250       */
 251      Series.prototype.hasColoredValues = function() {
 252          return this._colors.length == this.getCount();
 253      };
 254  
 255      /**
 256       * Set the series color.
 257       *
 258       * @param {String} color A CSS-compatible color.
 259       */
 260      Series.prototype.setColor = function(color) {
 261          this._colors = [color];
 262      };
 263  
 264      /**
 265       * Set a color for each value in the series.
 266       *
 267       * @param {String[]} colors CSS-compatible colors.
 268       */
 269      Series.prototype.setColors = function(colors) {
 270          if (colors && colors.length != this.getCount()) {
 271              throw new Error('When setting multiple colors there must be one per value.');
 272          }
 273          this._colors = colors || [];
 274      };
 275  
 276      /**
 277       * Set the labels for the values of the series.
 278       *
 279       * @param {String[]} labels the labels of the series values.
 280       */
 281      Series.prototype.setLabels = function(labels) {
 282          this._validateLabels(labels);
 283          labels = typeof labels === 'undefined' ? null : labels;
 284          this._labels = labels;
 285      };
 286  
 287      /**
 288       * Set Whether the line of the serie should be smooth or not.
 289       *
 290       * Only applicable for line chart or a line series, if null it assumes the chart default (not smooth).
 291       *
 292       * @param {Bool} smooth True if the lines should be smooth, false for tensioned lines.
 293       */
 294      Series.prototype.setSmooth = function(smooth) {
 295          smooth = typeof smooth === 'undefined' ? null : smooth;
 296          this._smooth = smooth;
 297      };
 298  
 299      /**
 300       * Set the type of the series.
 301       *
 302       * @param {String} type A type constant value.
 303       */
 304      Series.prototype.setType = function(type) {
 305          if (type != this.TYPE_DEFAULT && type != this.TYPE_LINE) {
 306              throw new Error('Invalid serie type.');
 307          }
 308          this._type = type || null;
 309      };
 310  
 311      /**
 312       * Set the index of the X axis.
 313       *
 314       * @param {Number} index The index.
 315       */
 316      Series.prototype.setXAxis = function(index) {
 317          this._xaxis = index || null;
 318      };
 319  
 320  
 321      /**
 322       * Set the index of the Y axis.
 323       *
 324       * @param {Number} index The index.
 325       */
 326      Series.prototype.setYAxis = function(index) {
 327          this._yaxis = index || null;
 328      };
 329  
 330      /**
 331       * Validate series labels.
 332       *
 333       * @protected
 334       * @param {String[]} labels The labels of the serie.
 335       */
 336      Series.prototype._validateLabels = function(labels) {
 337          if (labels && labels.length > 0 && labels.length != this.getCount()) {
 338              throw new Error('Series labels must match series values.');
 339          }
 340      };
 341  
 342      return Series;
 343  
 344  });