Merge branch 'MDL-60494-stray_img_end-39' of https://github.com/leonstr/moodle into...
[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 defined('MOODLE_INTERNAL') || die();
33 /**
34  * Class allowing different systems for mapping and rendering icons.
35  *
36  * Possible icon styles are:
37  *   1. standard - image tags are generated which point to pix icons stored in a plugin pix folder.
38  *   2. fontawesome - font awesome markup is generated with the name of the icon mapped from the moodle icon name.
39  *   3. inline - inline tags are used for svg and png so no separate page requests are made (at the expense of page size).
40  *
41  * @package    core
42  * @category   output
43  * @copyright  2016 Damyon Wiese
44  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
45  */
46 abstract class icon_system {
47     /**
48      * @const STANDARD Default icon system.
49      */
50     const STANDARD = '\\core\\output\\icon_system_standard';
51     /**
52      * @const FONTAWESOME Default icon system.
53      */
54     const FONTAWESOME = '\\core\\output\\icon_system_fontawesome';
56     /**
57      * @var \core\output\icon_system $instance The cached default instance
58      */
59     private static $instance = null;
61     /**
62      * @var array $map A cached mapping of moodle icons to other icons
63      */
64     private $map = null;
66     /**
67      * Constructor
68      */
69     private function __construct() {
70     }
72     /**
73      * Factory method
74      *
75      * @param string $type Either a specific type, or null to get the default type.
76      * @return \core\output\icon_system
77      */
78     public final static function instance($type = null) {
79         global $PAGE;
81         if (empty(self::$instance)) {
82             $icontype = $PAGE->theme->get_icon_system();
83             self::$instance = new $icontype();
84         }
86         // If $type is specified we need to make sure that the theme icon system supports this type,
87         // if not, we will return a generic new instance of the $type.
88         if ($type === null || is_a(self::$instance, $type)) {
89             return self::$instance;
90         } else {
91             return new $type();
92         }
93     }
95     /**
96      * Validate the theme config setting.
97      *
98      * @param string $system
99      * @return boolean
100      */
101     public final static function is_valid_system($system) {
102         return class_exists($system) && is_subclass_of($system, self::class);
103     }
105     /**
106      * The name of an AMD module extending core/icon_system
107      *
108      * @return string
109      */
110     public abstract function get_amd_name();
112     /**
113      * Render the pix icon according to the icon system.
114      *
115      * @param renderer_base $output
116      * @param pix_icon $icon
117      * @return string
118      */
119     public abstract function render_pix_icon(renderer_base $output, pix_icon $icon);
121     /**
122      * Overridable function to get a mapping of all icons.
123      * Default is to do no mapping.
124      */
125     public function get_icon_name_map() {
126         return [];
127     }
129     /**
130      * Overridable function to map the icon name to something else.
131      * Default is to do no mapping. Map is cached in the singleton.
132      */
133     public final function remap_icon_name($iconname, $component) {
134         if ($this->map === null) {
135             $this->map = $this->get_icon_name_map();
136         }
137         if ($component == null || $component == 'moodle') {
138             $component = 'core';
139         } else if ($component != 'theme') {
140             $component = \core_component::normalize_componentname($component);
141         }
143         if (isset($this->map[$component . ':' . $iconname])) {
144             return $this->map[$component . ':' . $iconname];
145         }
146         return false;
147     }
149     /**
150      * Clears the instance cache, for use in unit tests
151      */
152     public static function reset_caches() {
153         self::$instance = null;
154     }