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         global $CFG;
  80         return [
  81             'type' => $this->get_type(),
  82             'series' => $this->series,
  83             'labels' => $this->labels,
  84             'title' => $this->title,
  85             'axes' => [
  86                 'x' => $this->xaxes,
  87                 'y' => $this->yaxes,
  88             ],
  89             'config_colorset' => !empty($CFG->chart_colorset) ? $CFG->chart_colorset : null
  90         ];
  91     }
  92
  93     /**
  94      * Get an axis.
  95      *
  96      * @param string $type Accepts values 'x' or 'y'.
  97      * @param int $index The index of this axis.
  98      * @param bool $createifnotexists Whether to create the axis if not found.
  99      * @return chart_axis
 100      */
 101     private function get_axis($type, $index, $createifnotexists) {
 102         $isx = $type === 'x';
 103         if ($isx) {
 104             $axis = isset($this->xaxes[$index]) ? $this->xaxes[$index] : null;
 105         } else {
 106             $axis = isset($this->yaxes[$index]) ? $this->yaxes[$index] : null;
 107         }
 108
 109         if ($axis === null) {
 110             if (!$createifnotexists) {
 111                 throw new coding_exception('Unknown axis.');
 112             }
 113
 114             $axis = new chart_axis();
 115             if ($isx) {
 116                 $this->set_xaxis($axis, $index);
 117             } else {
 118                 $this->set_yaxis($axis, $index);
 119             }
 120         }
 121
 122         return $axis;
 123     }
 124
 125     /**
 126      * Get the labels of the X axis.
 127      *
 128      * @return string[]
 129      */
 130     public function get_labels() {
 131         return $this->labels;
 132     }
 133
 134     /**
 135      * Get the series.
 136      *
 137      * @return chart_series[]
 138      */
 139     public function get_series() {
 140         return $this->series;
 141     }
 142
 143     /**
 144      * Get the title.
 145      *
 146      * @return string
 147      */
 148     public function get_title() {
 149         return $this->title;
 150     }
 151
 152     /**
 153      * Get the chart type.
 154      *
 155      * @return string
 156      */
 157     public function get_type() {
 158         $classname = get_class($this);
 159         return substr($classname, strpos($classname, '_') + 1);
 160     }
 161
 162     /**
 163      * Get the X axes.
 164      *
 165      * @return chart_axis[]
 166      */
 167     public function get_xaxes() {
 168         return $this->xaxes;
 169     }
 170
 171     /**
 172      * Get an X axis.
 173      *
 174      * @param int $index The index of the axis.
 175      * @param bool $createifnotexists When true, create an instance of the axis if none exist at this index yet.
 176      * @return chart_axis
 177      */
 178     public function get_xaxis($index = 0, $createifnotexists = false) {
 179         return $this->get_axis('x', $index, $createifnotexists);
 180     }
 181
 182     /**
 183      * Get the Y axes.
 184      *
 185      * @return chart_axis[]
 186      */
 187     public function get_yaxes() {
 188         return $this->yaxes;
 189     }
 190
 191     /**
 192      * Get a Y axis.
 193      *
 194      * @param int $index The index of the axis.
 195      * @param bool $createifnotexists When true, create an instance of the axis if none exist at this index yet.
 196      * @return chart_axis
 197      */
 198     public function get_yaxis($index = 0, $createifnotexists = false) {
 199         return $this->get_axis('y', $index, $createifnotexists);
 200     }
 201
 202     /**
 203      * Set the defaults for this chart type.
 204      *
 205      * Child classes can extend this to set default values on instantiation.
 206      *
 207      * In general the constructor could be used, but this method is here to
 208      * emphasize and self-document the default values set by the chart type.
 209      *
 210      * @return void
 211      */
 212     protected function set_defaults() {
 213     }
 214
 215     /**
 216      * Set the chart labels.
 217      *
 218      * @param string[] $labels The labels.
 219      */
 220     public function set_labels(array $labels) {
 221         $this->labels = $labels;
 222     }
 223
 224     /**
 225      * Set the title.
 226      *
 227      * @param string $title The title.
 228      */
 229     public function set_title($title) {
 230         $this->title = $title;
 231     }
 232
 233     /**
 234      * Set an X axis.
 235      *
 236      * Note that this will override any predefined axis without warning.
 237      *
 238      * @param chart_axis $axis The axis.
 239      * @param int $index The index of the axis.
 240      */
 241     public function set_xaxis(chart_axis $axis, $index = 0) {
 242         $this->validate_axis('x', $axis, $index);
 243         return $this->xaxes[$index] = $axis;
 244     }
 245
 246     /**
 247      * Set an Y axis.
 248      *
 249      * Note that this will override any predefined axis without warning.
 250      *
 251      * @param chart_axis $axis The axis.
 252      * @param int $index The index of the axis.
 253      */
 254     public function set_yaxis(chart_axis $axis, $index = 0) {
 255         $this->validate_axis('y', $axis, $index);
 256         return $this->yaxes[$index] = $axis;
 257     }
 258
 259     /**
 260      * Validate an axis.
 261      *
 262      * We validate this from PHP because not doing it here could result in errors being
 263      * hard to trace down. For instance, if we were to add axis at keys without another
 264      * axis preceding, we would effectively contain the axes in an associative array
 265      * rather than a simple array, and that would have consequences on serialisation.
 266      *
 267      * @param string $xy Accepts x or y.
 268      * @param chart_axis $axis The axis to validate.
 269      * @param index $index The index of the axis.
 270      */
 271     protected function validate_axis($xy, chart_axis $axis, $index = 0) {
 272         if ($index > 0) {
 273             $axes = $xy == 'x' ? $this->xaxes : $this->yaxes;
 274             if (!isset($axes[$index - 1])) {
 275                 throw new coding_exception('Missing ' . $xy . ' axis at index lower than ' . $index);
 276             }
 277         }
 278     }
 279
 280 }