MDL-40759 icons: Refactor to allow theme icon systems
[moodle.git] / lib / classes / output / icon_system.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/>.
17 /**
18  * Contains class \core\output\icon_system
19  *
20  * @package    core
21  * @category   output
22  * @copyright  2016 Damyon Wiese
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 namespace core\output;
28 use renderer_base;
29 use pix_icon;
31 /**
32  * Class allowing different systems for mapping and rendering icons.
33  *
34  * Possible icon styles are:
35  *   1. standard - image tags are generated which point to pix icons stored in a plugin pix folder.
36  *   2. fontawesome - font awesome markup is generated with the name of the icon mapped from the moodle icon name.
37  *   3. inline - inline tags are used for svg and png so no separate page requests are made (at the expense of page size).
38  *
39  * @package    core
40  * @category   output
41  * @copyright  2016 Damyon Wiese
42  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
43  */
44 abstract class icon_system {
45     const STANDARD = '\\core\\output\\icon_system_standard';
46     const FONTAWESOME = '\\core\\output\\icon_system_fontawesome';
48     private static $instance = null;
49     private $map = null;
51     private function __construct() {
52     }
54     public final static function instance($type = null) {
55         global $PAGE;
57         if ($type == null) {
58             if (!empty(self::$instance)) {
59                 return self::$instance;
60             }
61             $type = $PAGE->theme->get_icon_system();
62             self::$instance = new $type();
63             // Default one is a singleton.
64             return self::$instance;
65         } else {
66             // Not a singleton.
67             return new $type();
68         }
69     }
71     /**
72      * Validate the theme config setting.
73      *
74      * @param string $system
75      * @return boolean
76      */
77     public final static function is_valid_system($system) {
78         return class_exists($system) && is_subclass_of($system, self::class);
79     }
81     /**
82      * The name of an AMD module extending core/icon_system
83      *
84      * @return string
85      */
86     public abstract function get_amd_name();
88     /**
89      * Render the pix icon according to the icon system.
90      *
91      * @param renderer_base $output
92      * @param pix_icon $icon
93      * @return string
94      */
95     public abstract function render_pix_icon(renderer_base $output, pix_icon $icon);
97     /**
98      * Overridable function to get a mapping of all icons.
99      * Default is to do no mapping.
100      */
101     public function get_icon_name_map() {
102         return [];
103     }
105     /**
106      * Overridable function to map the icon name to something else.
107      * Default is to do no mapping. Map is cached in the singleton.
108      */
109     public final function remap_icon_name($iconname, $component) {
110         if ($this->map === null) {
111             $this->map = $this->get_icon_name_map();
112         }
113         if ($component == null || $component == 'moodle') {
114             $component = 'core';
115         } else if ($component != 'theme') {
116             $component = \core_component::normalize_componentname($component);
117         }
119         if (isset($this->map[$component . ':' . $iconname])) {
120             return $this->map[$component . ':' . $iconname];
121         }
122         return false;
123     }