plugin.class.php 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461
  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 Version of this plugin
  47. * @param string $author Author of this plugin
  48. * @param array $settings 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. 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. 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. 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. 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. 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. 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. 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. 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(
  170. $type,
  171. $name,
  172. array($this->get_lang($name), $help)
  173. );
  174. break;
  175. case 'boolean':
  176. $group = array();
  177. $group[] = $result->createElement(
  178. 'radio',
  179. $name,
  180. '',
  181. get_lang('Yes'),
  182. 'true'
  183. );
  184. $group[] = $result->createElement(
  185. 'radio',
  186. $name,
  187. '',
  188. get_lang('No'),
  189. 'false'
  190. );
  191. $result->addGroup(
  192. $group,
  193. null,
  194. array($this->get_lang($name), $help)
  195. );
  196. break;
  197. }
  198. }
  199. $result->setDefaults($defaults);
  200. $result->addElement(
  201. 'style_submit_button',
  202. 'submit_button',
  203. $this->get_lang('Save')
  204. );
  205. return $result;
  206. }
  207. /**
  208. * Returns the value of a given plugin global setting
  209. * @param string Name of the plugin
  210. * @return string Value of the plugin
  211. */
  212. function get($name)
  213. {
  214. $settings = $this->get_settings();
  215. foreach ($settings as $setting) {
  216. if ($setting['variable'] == ($this->get_name() . '_' . $name)) {
  217. return $setting['selected_value'];
  218. }
  219. }
  220. return false;
  221. }
  222. /**
  223. * Returns an array with the global settings for this plugin
  224. * @return array Plugin settings as an array
  225. */
  226. public function get_settings()
  227. {
  228. if (is_null($this->settings)) {
  229. $settings = api_get_settings_params(
  230. array(
  231. "subkey = ? AND category = ? AND type = ? " => array(
  232. $this->get_name(),
  233. 'Plugins',
  234. 'setting'
  235. )
  236. )
  237. );
  238. $this->settings = $settings;
  239. }
  240. return $this->settings;
  241. }
  242. /**
  243. * Tells whether language variables are defined for this plugin or not
  244. * @param string System name of the plugin
  245. * @return boolean True if the plugin has language variables defined,
  246. * false otherwise
  247. */
  248. public function get_lang_plugin_exists($name)
  249. {
  250. return isset($this->strings[$name]);
  251. }
  252. /**
  253. * Hook for the get_lang() function to check for plugin-defined language terms
  254. * @param string Name of the language variable we are looking for
  255. * @return string The translated language term of the plugin
  256. */
  257. public function get_lang($name)
  258. {
  259. // Check whether the language strings for the plugin have already been
  260. // loaded. If so, no need to load them again.
  261. if (is_null($this->strings)) {
  262. global $language_interface;
  263. $root = api_get_path(SYS_PLUGIN_PATH);
  264. $plugin_name = $this->get_name();
  265. //1. Loading english if exists
  266. $english_path = $root . $plugin_name . "/lang/english.php";
  267. if (is_readable($english_path)) {
  268. include $english_path;
  269. $this->strings = $strings;
  270. }
  271. $path = $root . $plugin_name . "/lang/$language_interface.php";
  272. //2. Loading the system language
  273. if (is_readable($path)) {
  274. include $path;
  275. if (!empty($strings)) {
  276. foreach ($strings as $key => $string) {
  277. $this->strings[$key] = $string;
  278. }
  279. }
  280. }
  281. }
  282. if (isset($this->strings[$name])) {
  283. return $this->strings[$name];
  284. }
  285. return get_lang($name);
  286. }
  287. /**
  288. * Caller for the install_course_fields() function
  289. * @param int The course's integer ID
  290. * @param boolean Whether to add a tool link on the course homepage
  291. * @return void
  292. */
  293. function course_install($course_id, $add_tool_link = true)
  294. {
  295. $this->install_course_fields($course_id, $add_tool_link);
  296. }
  297. /**
  298. * Add course settings and, if not asked otherwise, add a tool link on the course homepage
  299. * @param int Course integer ID
  300. * @param boolean Whether to add a tool link or not (some tools might just offer a configuration section and act on the backend)
  301. * @return boolean False on error, null otherwise
  302. */
  303. public function install_course_fields($course_id, $add_tool_link = true)
  304. {
  305. $plugin_name = $this->get_name();
  306. $t_course = Database::get_course_table(TABLE_COURSE_SETTING);
  307. $course_id = intval($course_id);
  308. if (empty($course_id)) {
  309. return false;
  310. }
  311. //Ads course settings
  312. if (!empty($this->course_settings)) {
  313. foreach ($this->course_settings as $setting) {
  314. $variable = Database::escape_string($setting['name']);
  315. $value = '';
  316. if (isset($setting['init_value'])) {
  317. $value = Database::escape_string($setting['init_value']);
  318. }
  319. $type = 'textfield';
  320. if (isset($setting['type'])) {
  321. $type = Database::escape_string($setting['type']);
  322. }
  323. if (isset($setting['group'])) {
  324. $group = Database::escape_string($setting['group']);
  325. $sql = "SELECT value FROM $t_course WHERE c_id = $course_id AND variable = '$group' AND subkey = '$variable' ";
  326. $result = Database::query($sql);
  327. if (!Database::num_rows($result)) {
  328. $sql_course = "INSERT INTO $t_course (c_id, variable, subkey, value, category, type) VALUES ($course_id, '$group', '$variable', '$value', 'plugins', '$type')";
  329. $r = Database::query($sql_course);
  330. }
  331. } else {
  332. $sql = "SELECT value FROM $t_course WHERE c_id = $course_id AND variable = '$variable' ";
  333. $result = Database::query($sql);
  334. if (!Database::num_rows($result)) {
  335. $sql_course = "INSERT INTO $t_course (c_id, variable, value, category, subkey, type) VALUES ($course_id, '$variable','$value', 'plugins', '$plugin_name', '$type')";
  336. $r = Database::query($sql_course);
  337. }
  338. }
  339. }
  340. }
  341. // Stop here if we don't want a tool link on the course homepage
  342. if (!$add_tool_link) {
  343. return true;
  344. }
  345. //Add an icon in the table tool list
  346. $t_tool = Database::get_course_table(TABLE_TOOL_LIST);
  347. $sql = "SELECT name FROM $t_tool WHERE c_id = $course_id AND name = '$plugin_name' ";
  348. $result = Database::query($sql);
  349. if (!Database::num_rows($result)) {
  350. $tool_link = "$plugin_name/start.php";
  351. $visibility = Text::string2binary(
  352. api_get_setting('course_create_active_tools', $plugin_name)
  353. );
  354. $sql_course = "INSERT INTO $t_tool VALUES ($course_id, NULL, '$plugin_name', '$tool_link', '$plugin_name.png',' " . $visibility . "','0', 'squaregrey.gif','NO','_self','plugin','0')";
  355. Database::query($sql_course);
  356. }
  357. }
  358. /**
  359. * Delete the fields added to the course settings page and the link to the
  360. * tool on the course's homepage
  361. * @param int The integer course ID
  362. * @return void
  363. */
  364. public function uninstall_course_fields($course_id)
  365. {
  366. $course_id = intval($course_id);
  367. if (empty($course_id)) {
  368. return false;
  369. }
  370. $plugin_name = $this->get_name();
  371. $t_course = Database::get_course_table(TABLE_COURSE_SETTING);
  372. $t_tool = Database::get_course_table(TABLE_TOOL_LIST);
  373. if (!empty($this->course_settings)) {
  374. foreach ($this->course_settings as $setting) {
  375. $variable = Database::escape_string($setting['name']);
  376. if (!empty($setting['group'])) {
  377. $variable = Database::escape_string($setting['group']);
  378. }
  379. $sql = "DELETE FROM $t_course WHERE c_id = $course_id AND variable = '$variable'";
  380. Database::query($sql);
  381. }
  382. }
  383. $sql = "DELETE FROM $t_tool WHERE c_id = $course_id AND name = '$plugin_name'";
  384. Database::query($sql);
  385. }
  386. /**
  387. * Install the course fields and tool link of this plugin in all courses
  388. * @param boolean Whether we want to add a plugin link on the course homepage
  389. * @return void
  390. */
  391. function install_course_fields_in_all_courses($add_tool_link = true)
  392. {
  393. // Update existing courses to add conference settings
  394. $t_courses = Database::get_main_table(TABLE_MAIN_COURSE);
  395. $sql = "SELECT id, code FROM $t_courses ORDER BY id";
  396. $res = Database::query($sql);
  397. while ($row = Database::fetch_assoc($res)) {
  398. $this->install_course_fields($row['id'], $add_tool_link);
  399. }
  400. }
  401. /**
  402. * Uninstall the plugin settings fields from all courses
  403. * @return void
  404. */
  405. function uninstall_course_fields_in_all_courses()
  406. {
  407. // Update existing courses to add conference settings
  408. $t_courses = Database::get_main_table(TABLE_MAIN_COURSE);
  409. $sql = "SELECT id, code FROM $t_courses ORDER BY id";
  410. $res = Database::query($sql);
  411. while ($row = Database::fetch_assoc($res)) {
  412. $this->uninstall_course_fields($row['id']);
  413. }
  414. }
  415. /**
  416. * Method to be extended when changing the setting in the course
  417. * configuration should trigger the use of a callback method
  418. * @param array Values sent back from the course configuration script
  419. * @return void
  420. */
  421. public function course_settings_updated($values = array())
  422. {
  423. }
  424. }