lib/classes/chart_base.php

   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 }