plugin.class.php 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429
  1. <?php
  2. /* For licensing terms, see /license.txt */
  3. /**
  4. * Base class for plugins
  5. *
  6. * This class has to be extended by every plugin. It defines basic methods
  7. * to install/uninstall and get information about a plugin
  8. *
  9. * @copyright (c) 2012 University of Geneva
  10. * @license GNU General Public License - http://www.gnu.org/copyleft/gpl.html
  11. * @author Laurent Opprecht <laurent@opprecht.info>
  12. * @author Julio Montoya <gugli100@gmail.com> added course settings support + lang variable fixes
  13. * @author Yannick Warnier <ywarnier@beeznest.org> added documentation
  14. *
  15. */
  16. class Plugin
  17. {
  18. protected $version = '';
  19. protected $author = '';
  20. protected $fields = array();
  21. private $settings = null;
  22. private $strings = null; //translation strings
  23. public $is_course_plugin = false;
  24. /**
  25. * When creating a new course, these settings are added to the course, in
  26. * the course_info/infocours.php
  27. * To show the plugin course icons you need to add these icons:
  28. * main/img/icons/22/plugin_name.png
  29. * main/img/icons/64/plugin_name.png
  30. * main/img/icons/64/plugin_name_na.png
  31. * @example
  32. * $course_settings = array(
  33. array('name' => 'big_blue_button_welcome_message', 'type' => 'text'),
  34. array('name' => 'big_blue_button_record_and_store', 'type' => 'checkbox')
  35. );
  36. */
  37. public $course_settings = array();
  38. /**
  39. * This indicates whether changing the setting should execute the callback
  40. * function.
  41. */
  42. public $course_settings_callback = false;
  43. /**
  44. * Default constructor for the plugin class. By default, it only sets
  45. * a few attributes of the object
  46. * @param string Version of this plugin
  47. * @param string Author of this plugin
  48. * @param array Array of global settings to be proposed to configure the plugin
  49. */
  50. protected function __construct($version, $author, $settings = array())
  51. {
  52. $this->version = $version;
  53. $this->author = $author;
  54. $this->fields = $settings;
  55. global $language_files;
  56. $language_files[] = 'plugin_' . $this->get_name();
  57. }
  58. /**
  59. * Gets an array of information about this plugin (name, version, ...)
  60. * @return array Array of information elements about this plugin
  61. */
  62. public function get_info()
  63. {
  64. $result = array();
  65. $result['title'] = $this->get_title();
  66. $result['comment'] = $this->get_comment();
  67. $result['version'] = $this->get_version();
  68. $result['author'] = $this->get_author();
  69. $result['plugin_class'] = get_class($this);
  70. $result['is_course_plugin'] = $this->is_course_plugin;
  71. if ($form = $this->get_settings_form()) {
  72. $result['settings_form'] = $form;
  73. foreach ($this->fields as $name => $type) {
  74. $value = $this->get($name);
  75. $result[$name] = $value;
  76. }
  77. }
  78. return $result;
  79. }
  80. /**
  81. * Returns the "system" name of the plugin in lowercase letters
  82. * @param string Name of the plugin
  83. * @return string
  84. */
  85. public function get_name()
  86. {
  87. $result = get_class($this);
  88. $result = str_replace('Plugin', '', $result);
  89. $result = strtolower($result);
  90. return $result;
  91. }
  92. /**
  93. * Returns the title of the plugin
  94. * @param string title of the plugin
  95. * @return string
  96. */
  97. public function get_title()
  98. {
  99. return $this->get_lang('plugin_title');
  100. }
  101. /**
  102. * Returns the description of the plugin
  103. * @param string description of the plugin
  104. * @return string
  105. */
  106. public function get_comment()
  107. {
  108. return $this->get_lang('plugin_comment');
  109. }
  110. /**
  111. * Returns the version of the plugin
  112. * @param string Version of the plugin
  113. * @return string
  114. */
  115. public function get_version()
  116. {
  117. return $this->version;
  118. }
  119. /**
  120. * Returns the author of the plugin
  121. * @param string Author(s) of the plugin
  122. * @return string
  123. */
  124. public function get_author()
  125. {
  126. return $this->author;
  127. }
  128. /**
  129. * Returns the contents of the CSS defined by the plugin
  130. * @param string The CSS string
  131. * @return array
  132. */
  133. public function get_css()
  134. {
  135. $name = $this->get_name();
  136. $path = api_get_path(SYS_PLUGIN_PATH)."$name/resources/$name.css";
  137. if (!is_readable($path)) {
  138. return '';
  139. }
  140. $css = array();
  141. $css[] = file_get_contents($path);
  142. $result = implode($css);
  143. return $result;
  144. }
  145. /**
  146. * Returns an HTML form (generated by FormValidator) of the plugin settings
  147. * @return string FormValidator-generated form
  148. */
  149. public function get_settings_form()
  150. {
  151. $result = new FormValidator($this->get_name());
  152. $defaults = array();
  153. foreach ($this->fields as $name => $type) {
  154. $value = $this->get($name);
  155. $defaults[$name] = $value;
  156. $type = isset($type) ? $type : 'text';
  157. $help = null;
  158. if ($this->get_lang_plugin_exists($name.'_help')) {
  159. $help = $this->get_lang($name.'_help');
  160. }
  161. switch ($type) {
  162. case 'html':
  163. $result->addElement('html', $this->get_lang($name));
  164. break;
  165. case 'wysiwyg':
  166. $result->add_html_editor($name, $this->get_lang($name));
  167. break;
  168. case 'text':
  169. $result->addElement($type, $name, array($this->get_lang($name), $help));
  170. break;
  171. case 'boolean':
  172. $group = array();
  173. $group[] = $result->createElement('radio', $name, '', get_lang('Yes'), 'true');
  174. $group[] = $result->createElement('radio', $name, '', get_lang('No'), 'false');
  175. $result->addGroup($group, null, array($this->get_lang($name), $help));
  176. break;
  177. }
  178. }
  179. $result->setDefaults($defaults);
  180. $result->addElement('style_submit_button', 'submit_button', $this->get_lang('Save'));
  181. return $result;
  182. }
  183. /**
  184. * Returns the value of a given plugin global setting
  185. * @param string Name of the plugin
  186. * @return string Value of the plugin
  187. */
  188. public function get($name)
  189. {
  190. $settings = $this->get_settings();
  191. foreach ($settings as $setting) {
  192. if ($setting['variable'] == ($this->get_name() . '_' . $name)) {
  193. return $setting['selected_value'];
  194. }
  195. }
  196. return false;
  197. }
  198. /**
  199. * Returns an array with the global settings for this plugin
  200. * @return array Plugin settings as an array
  201. */
  202. public function get_settings()
  203. {
  204. if (is_null($this->settings)) {
  205. $settings = api_get_settings_params(array("subkey = ? AND category = ? AND type = ? " => array($this->get_name(), 'Plugins', 'setting')));
  206. $this->settings = $settings;
  207. }
  208. return $this->settings;
  209. }
  210. /**
  211. * Tells whether language variables are defined for this plugin or not
  212. * @param string System name of the plugin
  213. * @return boolean True if the plugin has language variables defined, false otherwise
  214. */
  215. public function get_lang_plugin_exists($name)
  216. {
  217. return isset($this->strings[$name]);
  218. }
  219. /**
  220. * Hook for the get_lang() function to check for plugin-defined language terms
  221. * @param string Name of the language variable we are looking for
  222. * @return string The translated language term of the plugin
  223. */
  224. public function get_lang($name)
  225. {
  226. // Check whether the language strings for the plugin have already been
  227. // loaded. If so, no need to load them again.
  228. if (is_null($this->strings)) {
  229. global $language_interface;
  230. $root = api_get_path(SYS_PLUGIN_PATH);
  231. $plugin_name = $this->get_name();
  232. //1. Loading english if exists
  233. $english_path = $root.$plugin_name."/lang/english.php";
  234. if (is_readable($english_path)) {
  235. include $english_path;
  236. $this->strings = $strings;
  237. }
  238. $path = $root.$plugin_name."/lang/$language_interface.php";
  239. //2. Loading the system language
  240. if (is_readable($path)) {
  241. include $path;
  242. if (!empty($strings)) {
  243. foreach ($strings as $key => $string) {
  244. $this->strings[$key] = $string;
  245. }
  246. }
  247. }
  248. }
  249. if (isset($this->strings[$name])) {
  250. return $this->strings[$name];
  251. }
  252. return get_lang($name);
  253. }
  254. /**
  255. * Caller for the install_course_fields() function
  256. * @param int The course's integer ID
  257. * @param boolean Whether to add a tool link on the course homepage
  258. * @return void
  259. */
  260. public function course_install($course_id, $add_tool_link = true)
  261. {
  262. $this->install_course_fields($course_id, $add_tool_link);
  263. }
  264. /**
  265. * Add course settings and, if not asked otherwise, add a tool link on the course homepage
  266. * @param int Course integer ID
  267. * @param boolean Whether to add a tool link or not (some tools might just offer a configuration section and act on the backend)
  268. * @return boolean False on error, null otherwise
  269. */
  270. public function install_course_fields($course_id, $add_tool_link = true)
  271. {
  272. $plugin_name = $this->get_name();
  273. $t_course = Database::get_course_table(TABLE_COURSE_SETTING);
  274. $course_id = intval($course_id);
  275. if (empty($course_id)) {
  276. return false;
  277. }
  278. //Ads course settings
  279. if (!empty($this->course_settings)) {
  280. foreach ($this->course_settings as $setting) {
  281. $variable = Database::escape_string($setting['name']);
  282. $value ='';
  283. if (isset($setting['init_value'])) {
  284. $value = Database::escape_string($setting['init_value']);
  285. }
  286. $type = 'textfield';
  287. if (isset($setting['type'])) {
  288. $type = Database::escape_string($setting['type']);
  289. }
  290. if (isset($setting['group'])) {
  291. $group = Database::escape_string($setting['group']);
  292. $sql = "SELECT value FROM $t_course WHERE c_id = $course_id AND variable = '$group' AND subkey = '$variable' ";
  293. $result = Database::query($sql);
  294. if (!Database::num_rows($result)) {
  295. $sql_course = "INSERT INTO $t_course (c_id, variable, subkey, value, category, type) VALUES ($course_id, '$group', '$variable', '$value', 'plugins', '$type')";
  296. $r = Database::query($sql_course);
  297. }
  298. } else {
  299. $sql = "SELECT value FROM $t_course WHERE c_id = $course_id AND variable = '$variable' ";
  300. $result = Database::query($sql);
  301. if (!Database::num_rows($result)) {
  302. $sql_course = "INSERT INTO $t_course (c_id, variable, value, category, subkey, type) VALUES ($course_id, '$variable','$value', 'plugins', '$plugin_name', '$type')";
  303. $r = Database::query($sql_course);
  304. }
  305. }
  306. }
  307. }
  308. // Stop here if we don't want a tool link on the course homepage
  309. if (!$add_tool_link) {
  310. return true;
  311. }
  312. //Add an icon in the table tool list
  313. $t_tool = Database::get_course_table(TABLE_TOOL_LIST);
  314. $sql = "SELECT name FROM $t_tool WHERE c_id = $course_id AND name = '$plugin_name' ";
  315. $result = Database::query($sql);
  316. if (!Database::num_rows($result)) {
  317. $tool_link = "$plugin_name/start.php";
  318. $visibility = string2binary(api_get_setting('course_create_active_tools', $plugin_name));
  319. $sql_course = "INSERT INTO $t_tool
  320. VALUES ($course_id, NULL, '$plugin_name', '$tool_link', '$plugin_name.png',' ".$visibility."','0', 'squaregrey.gif','NO','_self','plugin','0')";
  321. Database::query($sql_course);
  322. }
  323. }
  324. /**
  325. * Delete the fields added to the course settings page and the link to the
  326. * tool on the course's homepage
  327. * @param int The integer course ID
  328. * @return void
  329. */
  330. public function uninstall_course_fields($course_id)
  331. {
  332. $course_id = intval($course_id);
  333. if (empty($course_id)) {
  334. return false;
  335. }
  336. $plugin_name = $this->get_name();
  337. $t_course = Database::get_course_table(TABLE_COURSE_SETTING);
  338. $t_tool = Database::get_course_table(TABLE_TOOL_LIST);
  339. if (!empty($this->course_settings)) {
  340. foreach ($this->course_settings as $setting) {
  341. $variable = Database::escape_string($setting['name']);
  342. if (!empty($setting['group'])) {
  343. $variable = Database::escape_string($setting['group']);
  344. }
  345. $sql_course = "DELETE FROM $t_course WHERE c_id = $course_id AND variable = '$variable'";
  346. Database::query($sql_course);
  347. }
  348. }
  349. $sql_course = "DELETE FROM $t_tool WHERE c_id = $course_id AND name = '$plugin_name'";
  350. Database::query($sql_course);
  351. }
  352. /**
  353. * Install the course fields and tool link of this plugin in all courses
  354. * @param boolean Whether we want to add a plugin link on the course homepage
  355. * @return void
  356. */
  357. public function install_course_fields_in_all_courses($add_tool_link = true)
  358. {
  359. // Update existing courses to add conference settings
  360. $t_courses = Database::get_main_table(TABLE_MAIN_COURSE);
  361. $sql = "SELECT id, code FROM $t_courses ORDER BY id";
  362. $res = Database::query($sql);
  363. while ($row = Database::fetch_assoc($res)) {
  364. $this->install_course_fields($row['id'], $add_tool_link);
  365. }
  366. }
  367. /**
  368. * Uninstall the plugin settings fields from all courses
  369. * @return void
  370. */
  371. public function uninstall_course_fields_in_all_courses()
  372. {
  373. // Update existing courses to add conference settings
  374. $t_courses = Database::get_main_table(TABLE_MAIN_COURSE);
  375. $sql = "SELECT id, code FROM $t_courses ORDER BY id";
  376. $res = Database::query($sql);
  377. while ($row = Database::fetch_assoc($res)) {
  378. $this->uninstall_course_fields($row['id']);
  379. }
  380. }
  381. /**
  382. * Method to be extended when changing the setting in the course
  383. * configuration should trigger the use of a callback method
  384. * @param array Values sent back from the course configuration script
  385. * @return void
  386. */
  387. public function course_settings_updated($values = array())
  388. {
  389. }
  390. }