MDL-52996 Atto: Allow plugins to customise toolbar
[moodle.git] / lib / editorlib.php
CommitLineData
5ca3c838 1<?php
2
8fd57583 3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * Utility classes and functions for text editor integration.
20 *
20e5da7d 21 * @package core
8fd57583 22 * @subpackage editor
11e1f828 23 * @copyright 2009 Petr Skoda {@link http://skodak.org}
8fd57583 24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
5ca3c838 26
78bfb562
PS
27defined('MOODLE_INTERNAL') || die();
28
1905b5f6 29/**
30 * Returns users preferred editor for given format
11e1f828 31 *
1905b5f6 32 * @param int $format text format or null of none
4c508047 33 * @return texteditor object
1905b5f6 34 */
20e5da7d 35function editors_get_preferred_editor($format = NULL) {
8213007c
PS
36 global $USER, $CFG;
37
38 if (!empty($CFG->adminsetuppending)) {
39 // Must not use other editors before install completed!
40 return get_texteditor('textarea');
41 }
5ca3c838 42
20e5da7d 43 $enabled = editors_get_enabled();
5ca3c838 44
3d27180e
DW
45 $preference = get_user_preferences('htmleditor', '', $USER);
46
47 if (isset($enabled[$preference])) {
48 // Edit the list of editors so the users preferred editor is first in the list.
49 $editor = $enabled[$preference];
50 unset($enabled[$preference]);
51 array_unshift($enabled, $editor);
52 }
5ca3c838 53
54 // now find some plugin that supports format and is available
55 $editor = false;
20e5da7d 56 foreach ($enabled as $e) {
5ca3c838 57 if (!$e->supported_by_browser()) {
58 // bad luck, this editor is not compatible
59 continue;
60 }
61 if (!$supports = $e->get_supported_formats()) {
20e5da7d 62 // buggy editor!
5ca3c838 63 continue;
64 }
3d27180e 65 if (is_null($format) || in_array($format, $supports)) {
5ca3c838 66 // editor supports this format, yay!
67 $editor = $e;
68 break;
69 }
70 }
71
72 if (!$editor) {
73 $editor = get_texteditor('textarea'); // must exist and can edit anything
74 }
75
76 return $editor;
77}
78
20e5da7d
PS
79/**
80 * Returns users preferred text format.
81 * @return int standard text format
82 */
83function editors_get_preferred_format() {
84 global $USER;
85
3d27180e 86 $editor = editors_get_preferred_editor();
20e5da7d
PS
87 return $editor->get_preferred_format();
88}
89
90/**
91 * Returns list of enabled text editors
92 * @return array of name=>texteditor
93 */
94function editors_get_enabled() {
95 global $CFG;
96
97 if (empty($CFG->texteditors)) {
adca7326 98 $CFG->texteditors = 'atto,tinymce,textarea';
20e5da7d
PS
99 }
100 $active = array();
101 foreach(explode(',', $CFG->texteditors) as $e) {
102 if ($editor = get_texteditor($e)) {
103 $active[$e] = $editor;
104 }
105 }
106
107 if (empty($active)) {
108 return array('textarea'=>get_texteditor('textarea')); // must exist and can edit anything
109 }
110
111 return $active;
112}
113
1905b5f6 114/**
115 * Returns instance of text editor
11e1f828 116 *
1905b5f6 117 * @param string $editorname name of editor (textarea, tinymce, ...)
11e1f828 118 * @return object|bool texeditor instance or false if does not exist
1905b5f6 119 */
120function get_texteditor($editorname) {
5ca3c838 121 global $CFG;
122
1905b5f6 123 $libfile = "$CFG->libdir/editor/$editorname/lib.php";
5ca3c838 124 if (!file_exists($libfile)) {
125 return false;
126 }
127 require_once($libfile);
1905b5f6 128 $classname = $editorname.'_texteditor';
5ca3c838 129 if (!class_exists($classname)) {
130 return false;
131 }
132 return new $classname();
133}
134
1905b5f6 135/**
5ca3c838 136 * Get the list of available editors
11e1f828
MH
137 *
138 * @return array Array ('editorname'=>'localised editor name')
5ca3c838 139 */
20e5da7d 140function editors_get_available() {
5ca3c838 141 $editors = array();
bd3b3bba 142 foreach (core_component::get_plugin_list('editor') as $editorname => $dir) {
a4ba0a96 143 $editors[$editorname] = get_string('pluginname', 'editor_'.$editorname);
5ca3c838 144 }
145 return $editors;
146}
147
ff5fe311 148/**
149 * Setup all JS and CSS needed for editors.
150 * @return void
151 */
152function editors_head_setup() {
153 global $CFG;
154
155 if (empty($CFG->texteditors)) {
adca7326 156 $CFG->texteditors = 'atto,tinymce,textarea';
ff5fe311 157 }
158 $active = explode(',', $CFG->texteditors);
159
160 foreach ($active as $editorname) {
161 if (!$editor = get_texteditor($editorname)) {
162 continue;
163 }
164 if (!$editor->supported_by_browser()) {
165 // bad luck, this editor is not compatible
166 continue;
167 }
168 $editor->head_setup();
169 }
170}
171
5ca3c838 172/**
1905b5f6 173 * Base abstract text editor class.
11e1f828
MH
174 *
175 * @copyright 2009 Petr Skoda {@link http://skodak.org}
176 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
177 * @package moodlecore
5ca3c838 178 */
179abstract class texteditor {
1905b5f6 180 /**
181 * Is editor supported in current browser?
182 * @return bool
183 */
5ca3c838 184 public abstract function supported_by_browser();
1905b5f6 185
186 /**
187 * Returns list of supported text formats
11e1f828 188 * @return array Array (FORMAT=>FORMAT)
1905b5f6 189 */
5ca3c838 190 public abstract function get_supported_formats();
1905b5f6 191
192 /**
193 * Returns main preferred text format.
194 * @return int text format
195 */
5ca3c838 196 public abstract function get_preferred_format();
1905b5f6 197
198 /**
199 * Supports file picker and repos?
11e1f828 200 * @return object book object
1905b5f6 201 */
5ca3c838 202 public abstract function supports_repositories();
1905b5f6 203
988592c5
DW
204 /**
205 * @var string $text The text set to the editor in the form.
05e4b876 206 * @since 3.0
988592c5
DW
207 */
208 protected $text = '';
209
210 /**
211 * Set the text set for this form field. Will be called before "use_editor".
212 * @param string $text The text for the form field.
213 */
214 public function set_text($text) {
215 $this->text = $text;
216 }
217
218 /**
219 * Get the text set for this form field. Can be called from "use_editor".
220 * @return string
221 */
222 public function get_text() {
223 return $this->text;
224 }
225
1905b5f6 226 /**
13a220cf 227 * Add required JS needed for editor
f66da45f 228 *
229 * Valid options may vary by editor. See the individual editor
230 * implementations of this function for documentation.
231 *
69429650 232 * @param string $elementid id of text area to be converted to editor
f66da45f 233 * @param array $options Editor options
4c508047 234 * @param obejct $fpoptions file picker options
13a220cf 235 * @return void
1905b5f6 236 */
4c508047 237 public abstract function use_editor($elementid, array $options=null, $fpoptions = null);
ff5fe311 238
239 /**
240 * Setup all JS and CSS needed for editor.
241 * @return void
242 */
243 public function head_setup() {
244 }
5ca3c838 245}