[Summary view] [Print] [Text view]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * Chart base.
  19   *
  20   * @package    core
  21   * @copyright  2016 Frédéric Massart - FMCorz.net
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  namespace core;
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  use coding_exception;
  29  use JsonSerializable;
  30  use renderable;
  31  
  32  /**
  33   * Chart base class.
  34   *
  35   * @package    core
  36   * @copyright  2016 Frédéric Massart - FMCorz.net
  37   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38   */
  39  class chart_base implements JsonSerializable, renderable {
  40  
  41      /** @var chart_series[] The series constituting this chart. */
  42      protected $series = [];
  43      /** @var string[] The labels for the X axis when categorised. */
  44      protected $labels = [];
  45      /** @var string The title of the chart. */
  46      protected $title = null;
  47      /** @var chart_axis[] The X axes. */
  48      protected $xaxes = [];
  49      /** @var chart_axis[] The Y axes. */
  50      protected $yaxes = [];
  51  
  52      /**
  53       * Constructor.
  54       *
  55       * Must not take any argument.
  56       *
  57       * Most of the time you do not want to extend this, rather extend the
  58       * method {@link self::set_defaults} to set the defaults on instantiation.
  59       */
  60      public function __construct() {
  61          $this->set_defaults();
  62      }
  63  
  64      /**
  65       * Add a series to the chart.
  66       *
  67       * @param chart_series $serie The serie.
  68       */
  69      public function add_series(chart_series $serie) {
  70          $this->series[] = $serie;
  71      }
  72  
  73      /**
  74       * Serialize the object.
  75       *
  76       * @return array
  77       */
  78      public function jsonSerialize() { // @codingStandardsIgnoreLine (CONTRIB-6469).
  79          return [
  80              'type' => $this->get_type(),
  81              'series' => $this->series,
  82              'labels' => $this->labels,
  83              'title' => $this->title,
  84              'axes' => [
  85                  'x' => $this->xaxes,
  86                  'y' => $this->yaxes,
  87              ]
  88          ];
  89      }
  90  
  91      /**
  92       * Get an axis.
  93       *
  94       * @param string $type Accepts values 'x' or 'y'.
  95       * @param int $index The index of this axis.
  96       * @param bool $createifnotexists Whether to create the axis if not found.
  97       * @return chart_axis
  98       */
  99      private function get_axis($type, $index, $createifnotexists) {
 100          $isx = $type === 'x';
 101          if ($isx) {
 102              $axis = isset($this->xaxes[$index]) ? $this->xaxes[$index] : null;
 103          } else {
 104              $axis = isset($this->yaxes[$index]) ? $this->yaxes[$index] : null;
 105          }
 106  
 107          if ($axis === null) {
 108              if (!$createifnotexists) {
 109                  throw new coding_exception('Unknown axis.');
 110              }
 111  
 112              $axis = new chart_axis();
 113              if ($isx) {
 114                  $this->set_xaxis($axis, $index);
 115              } else {
 116                  $this->set_yaxis($axis, $index);
 117              }
 118          }
 119  
 120          return $axis;
 121      }
 122  
 123      /**
 124       * Get the labels of the X axis.
 125       *
 126       * @return string[]
 127       */
 128      public function get_labels() {
 129          return $this->labels;
 130      }
 131  
 132      /**
 133       * Get the series.
 134       *
 135       * @return chart_series[]
 136       */
 137      public function get_series() {
 138          return $this->series;
 139      }
 140  
 141      /**
 142       * Get the title.
 143       *
 144       * @return string
 145       */
 146      public function get_title() {
 147          return $this->title;
 148      }
 149  
 150      /**
 151       * Get the chart type.
 152       *
 153       * @return string
 154       */
 155      public function get_type() {
 156          $classname = get_class($this);
 157          return substr($classname, strpos($classname, '_') + 1);
 158      }
 159  
 160      /**
 161       * Get the X axes.
 162       *
 163       * @return chart_axis[]
 164       */
 165      public function get_xaxes() {
 166          return $this->xaxes;
 167      }
 168  
 169      /**
 170       * Get an X axis.
 171       *
 172       * @param int $index The index of the axis.
 173       * @param bool $createifnotexists When true, create an instance of the axis if none exist at this index yet.
 174       * @return chart_axis
 175       */
 176      public function get_xaxis($index = 0, $createifnotexists = false) {
 177          return $this->get_axis('x', $index, $createifnotexists);
 178      }
 179  
 180      /**
 181       * Get the Y axes.
 182       *
 183       * @return chart_axis[]
 184       */
 185      public function get_yaxes() {
 186          return $this->yaxes;
 187      }
 188  
 189      /**
 190       * Get a Y axis.
 191       *
 192       * @param int $index The index of the axis.
 193       * @param bool $createifnotexists When true, create an instance of the axis if none exist at this index yet.
 194       * @return chart_axis
 195       */
 196      public function get_yaxis($index = 0, $createifnotexists = false) {
 197          return $this->get_axis('y', $index, $createifnotexists);
 198      }
 199  
 200      /**
 201       * Set the defaults for this chart type.
 202       *
 203       * Child classes can extend this to set default values on instantiation.
 204       *
 205       * In general the constructor could be used, but this method is here to
 206       * emphasize and self-document the default values set by the chart type.
 207       *
 208       * @return void
 209       */
 210      protected function set_defaults() {
 211      }
 212  
 213      /**
 214       * Set the chart labels.
 215       *
 216       * @param string[] $labels The labels.
 217       */
 218      public function set_labels(array $labels) {
 219          $this->labels = $labels;
 220      }
 221  
 222      /**
 223       * Set the title.
 224       *
 225       * @param string $title The title.
 226       */
 227      public function set_title($title) {
 228          $this->title = $title;
 229      }
 230  
 231      /**
 232       * Set an X axis.
 233       *
 234       * Note that this will override any predefined axis without warning.
 235       *
 236       * @param chart_axis $axis The axis.
 237       * @param int $index The index of the axis.
 238       */
 239      public function set_xaxis(chart_axis $axis, $index = 0) {
 240          $this->validate_axis('x', $axis, $index);
 241          return $this->xaxes[$index] = $axis;
 242      }
 243  
 244      /**
 245       * Set an Y axis.
 246       *
 247       * Note that this will override any predefined axis without warning.
 248       *
 249       * @param chart_axis $axis The axis.
 250       * @param int $index The index of the axis.
 251       */
 252      public function set_yaxis(chart_axis $axis, $index = 0) {
 253          $this->validate_axis('y', $axis, $index);
 254          return $this->yaxes[$index] = $axis;
 255      }
 256  
 257      /**
 258       * Validate an axis.
 259       *
 260       * We validate this from PHP because not doing it here could result in errors being
 261       * hard to trace down. For instance, if we were to add axis at keys without another
 262       * axis preceding, we would effectively contain the axes in an associative array
 263       * rather than a simple array, and that would have consequences on serialisation.
 264       *
 265       * @param string $xy Accepts x or y.
 266       * @param chart_axis $axis The axis to validate.
 267       * @param index $index The index of the axis.
 268       */
 269      protected function validate_axis($xy, chart_axis $axis, $index = 0) {
 270          if ($index > 0) {
 271              $axes = $xy == 'x' ? $this->xaxes : $this->yaxes;
 272              if (!isset($axes[$index - 1])) {
 273                  throw new coding_exception('Missing ' . $xy . ' axis at index lower than ' . $index);
 274              }
 275          }
 276      }
 277  
 278  }