plugin.class.php 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638
  1. <?php
  2. /* For licensing terms, see /license.txt */
  3. /**
  4. * Class Plugin
  5. * Base class for plugins
  6. *
  7. *
  8. * This class has to be extended by every plugin. It defines basic methods
  9. * to install/uninstall and get information about a plugin
  10. *
  11. * @copyright (c) 2012 University of Geneva
  12. * @license GNU General Public License - http://www.gnu.org/copyleft/gpl.html
  13. * @author Laurent Opprecht <laurent@opprecht.info>
  14. * @author Julio Montoya <gugli100@gmail.com> added course settings support + lang variable fixes
  15. * @author Yannick Warnier <ywarnier@beeznest.org> added documentation
  16. */
  17. class Plugin
  18. {
  19. protected $version = '';
  20. protected $author = '';
  21. protected $fields = array();
  22. private $settings = null;
  23. // Translation strings.
  24. private $strings = null;
  25. public $is_course_plugin = false;
  26. /**
  27. * When creating a new course, these settings are added to the course, in
  28. * the course_info/infocours.php
  29. * To show the plugin course icons you need to add these icons:
  30. * main/img/icons/22/plugin_name.png
  31. * main/img/icons/64/plugin_name.png
  32. * main/img/icons/64/plugin_name_na.png
  33. * @example
  34. * $course_settings = array(
  35. array('name' => 'big_blue_button_welcome_message', 'type' => 'text'),
  36. array('name' => 'big_blue_button_record_and_store', 'type' => 'checkbox')
  37. );
  38. */
  39. public $course_settings = array();
  40. /**
  41. * This indicates whether changing the setting should execute the callback
  42. * function.
  43. */
  44. public $course_settings_callback = false;
  45. /**
  46. * Default constructor for the plugin class. By default, it only sets
  47. * a few attributes of the object
  48. * @param string Version of this plugin
  49. * @param string Author of this plugin
  50. * @param array Array of global settings to be proposed to configure the plugin
  51. */
  52. protected function __construct($version, $author, $settings = array())
  53. {
  54. $this->version = $version;
  55. $this->author = $author;
  56. $this->fields = $settings;
  57. global $language_files;
  58. $language_files[] = 'plugin_' . $this->get_name();
  59. }
  60. /**
  61. * Gets an array of information about this plugin (name, version, ...)
  62. * @return array Array of information elements about this plugin
  63. */
  64. public function get_info()
  65. {
  66. $result = array();
  67. $result['title'] = $this->get_title();
  68. $result['comment'] = $this->get_comment();
  69. $result['version'] = $this->get_version();
  70. $result['author'] = $this->get_author();
  71. $result['plugin_class'] = get_class($this);
  72. $result['is_course_plugin'] = $this->is_course_plugin;
  73. if ($form = $this->get_settings_form()) {
  74. $result['settings_form'] = $form;
  75. foreach ($this->fields as $name => $type) {
  76. $value = $this->get($name);
  77. $result[$name] = $value;
  78. }
  79. }
  80. return $result;
  81. }
  82. /**
  83. * Returns the "system" name of the plugin in lowercase letters
  84. * @return string
  85. */
  86. public function get_name()
  87. {
  88. $result = get_class($this);
  89. $result = str_replace('Plugin', '', $result);
  90. $result = strtolower($result);
  91. return $result;
  92. }
  93. /**
  94. * Returns the 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. * @return string
  104. */
  105. public function get_comment()
  106. {
  107. return $this->get_lang('plugin_comment');
  108. }
  109. /**
  110. * Returns the version of the plugin
  111. * @return string
  112. */
  113. public function get_version()
  114. {
  115. return $this->version;
  116. }
  117. /**
  118. * Returns the author of the plugin
  119. * @return string
  120. */
  121. public function get_author()
  122. {
  123. return $this->author;
  124. }
  125. /**
  126. * Returns the contents of the CSS defined by the plugin
  127. * @return array
  128. */
  129. public function get_css()
  130. {
  131. $name = $this->get_name();
  132. $path = api_get_path(SYS_PLUGIN_PATH)."$name/resources/$name.css";
  133. if (!is_readable($path)) {
  134. return '';
  135. }
  136. $css = array();
  137. $css[] = file_get_contents($path);
  138. $result = implode($css);
  139. return $result;
  140. }
  141. /**
  142. * Returns an HTML form (generated by FormValidator) of the plugin settings
  143. * @return string FormValidator-generated form
  144. */
  145. public function get_settings_form()
  146. {
  147. $result = new FormValidator($this->get_name());
  148. $defaults = array();
  149. foreach ($this->fields as $name => $type) {
  150. $value = $this->get($name);
  151. $defaults[$name] = $value;
  152. $type = isset($type) ? $type : 'text';
  153. $help = null;
  154. if ($this->get_lang_plugin_exists($name.'_help')) {
  155. $help = $this->get_lang($name.'_help');
  156. }
  157. switch ($type) {
  158. case 'html':
  159. $result->addElement('html', $this->get_lang($name));
  160. break;
  161. case 'wysiwyg':
  162. $result->add_html_editor($name, $this->get_lang($name));
  163. break;
  164. case 'text':
  165. $result->addElement($type, $name, array($this->get_lang($name), $help));
  166. break;
  167. case 'boolean':
  168. $group = array();
  169. $group[] = $result->createElement('radio', $name, '', get_lang('Yes'), 'true');
  170. $group[] = $result->createElement('radio', $name, '', get_lang('No'), 'false');
  171. $result->addGroup($group, null, array($this->get_lang($name), $help));
  172. break;
  173. }
  174. }
  175. $result->setDefaults($defaults);
  176. $result->addElement('style_submit_button', 'submit_button', $this->get_lang('Save'));
  177. return $result;
  178. }
  179. /**
  180. * Returns the value of a given plugin global setting
  181. * @param string Name of the plugin
  182. *
  183. * @return string Value of the plugin
  184. */
  185. public function get($name)
  186. {
  187. $settings = $this->get_settings();
  188. foreach ($settings as $setting) {
  189. if ($setting['variable'] == ($this->get_name() . '_' . $name)) {
  190. return $setting['selected_value'];
  191. }
  192. }
  193. return false;
  194. }
  195. /**
  196. * Returns an array with the global settings for this plugin
  197. * @return array Plugin settings as an array
  198. */
  199. public function get_settings()
  200. {
  201. if (is_null($this->settings)) {
  202. $settings = api_get_settings_params(
  203. array(
  204. "subkey = ? AND category = ? AND type = ? " => array($this->get_name(), 'Plugins', 'setting')
  205. )
  206. );
  207. $this->settings = $settings;
  208. }
  209. return $this->settings;
  210. }
  211. /**
  212. * Tells whether language variables are defined for this plugin or not
  213. * @param string System name of the plugin
  214. *
  215. * @return boolean True if the plugin has language variables defined, false otherwise
  216. */
  217. public function get_lang_plugin_exists($name)
  218. {
  219. return isset($this->strings[$name]);
  220. }
  221. /**
  222. * Hook for the get_lang() function to check for plugin-defined language terms
  223. * @param string Name of the language variable we are looking for
  224. *
  225. * @return string The translated language term of the plugin
  226. */
  227. public function get_lang($name)
  228. {
  229. // Check whether the language strings for the plugin have already been
  230. // loaded. If so, no need to load them again.
  231. if (is_null($this->strings)) {
  232. global $language_interface;
  233. $root = api_get_path(SYS_PLUGIN_PATH);
  234. $plugin_name = $this->get_name();
  235. //1. Loading english if exists
  236. $english_path = $root.$plugin_name."/lang/english.php";
  237. if (is_readable($english_path)) {
  238. include $english_path;
  239. $this->strings = $strings;
  240. }
  241. $path = $root.$plugin_name."/lang/$language_interface.php";
  242. //2. Loading the system language
  243. if (is_readable($path)) {
  244. include $path;
  245. if (!empty($strings)) {
  246. foreach ($strings as $key => $string) {
  247. $this->strings[$key] = $string;
  248. }
  249. }
  250. }
  251. }
  252. if (isset($this->strings[$name])) {
  253. return $this->strings[$name];
  254. }
  255. return get_lang($name);
  256. }
  257. /**
  258. * Caller for the install_course_fields() function
  259. * @param int The course's integer ID
  260. * @param boolean Whether to add a tool link on the course homepage
  261. *
  262. * @return void
  263. */
  264. public function course_install($courseId, $addToolLink = true)
  265. {
  266. $this->install_course_fields($courseId, $addToolLink);
  267. }
  268. /**
  269. * Add course settings and, if not asked otherwise, add a tool link on the course homepage
  270. * @param int Course integer ID
  271. * @param boolean Whether to add a tool link or not (some tools might just offer a configuration section and act on the backend)
  272. * @return boolean False on error, null otherwise
  273. */
  274. public function install_course_fields($course_id, $add_tool_link = true)
  275. {
  276. $plugin_name = $this->get_name();
  277. $t_course = Database::get_course_table(TABLE_COURSE_SETTING);
  278. $course_id = intval($course_id);
  279. if (empty($course_id)) {
  280. return false;
  281. }
  282. // Ads course settings.
  283. if (!empty($this->course_settings)) {
  284. foreach ($this->course_settings as $setting) {
  285. $variable = Database::escape_string($setting['name']);
  286. $value ='';
  287. if (isset($setting['init_value'])) {
  288. $value = Database::escape_string($setting['init_value']);
  289. }
  290. $type = 'textfield';
  291. if (isset($setting['type'])) {
  292. $type = Database::escape_string($setting['type']);
  293. }
  294. if (isset($setting['group'])) {
  295. $group = Database::escape_string($setting['group']);
  296. $sql = "SELECT value FROM $t_course WHERE c_id = $course_id AND variable = '$group' AND subkey = '$variable' ";
  297. $result = Database::query($sql);
  298. if (!Database::num_rows($result)) {
  299. $sql_course = "INSERT INTO $t_course (c_id, variable, subkey, value, category, type) VALUES ($course_id, '$group', '$variable', '$value', 'plugins', '$type')";
  300. Database::query($sql_course);
  301. }
  302. } else {
  303. $sql = "SELECT value FROM $t_course WHERE c_id = $course_id AND variable = '$variable' ";
  304. $result = Database::query($sql);
  305. if (!Database::num_rows($result)) {
  306. $sql_course = "INSERT INTO $t_course (c_id, variable, value, category, subkey, type) VALUES ($course_id, '$variable','$value', 'plugins', '$plugin_name', '$type')";
  307. Database::query($sql_course);
  308. }
  309. }
  310. }
  311. }
  312. // Stop here if we don't want a tool link on the course homepage
  313. if (!$add_tool_link) {
  314. return true;
  315. }
  316. //Add an icon in the table tool list
  317. $t_tool = Database::get_course_table(TABLE_TOOL_LIST);
  318. $sql = "SELECT name FROM $t_tool WHERE c_id = $course_id AND name = '$plugin_name' ";
  319. $result = Database::query($sql);
  320. if (!Database::num_rows($result)) {
  321. $tool_link = "$plugin_name/start.php";
  322. $visibility = string2binary(api_get_setting('course_create_active_tools', $plugin_name));
  323. $sql_course = "INSERT INTO $t_tool
  324. VALUES ($course_id, NULL, '$plugin_name', '$tool_link', '$plugin_name.png',' ".$visibility."','0', 'squaregrey.gif','NO','_self','plugin','0')";
  325. Database::query($sql_course);
  326. }
  327. }
  328. /**
  329. * Delete the fields added to the course settings page and the link to the
  330. * tool on the course's homepage
  331. * @param int The integer course ID
  332. * @return void
  333. */
  334. public function uninstall_course_fields($course_id)
  335. {
  336. $course_id = intval($course_id);
  337. if (empty($course_id)) {
  338. return false;
  339. }
  340. $plugin_name = $this->get_name();
  341. $t_course = Database::get_course_table(TABLE_COURSE_SETTING);
  342. $t_tool = Database::get_course_table(TABLE_TOOL_LIST);
  343. if (!empty($this->course_settings)) {
  344. foreach ($this->course_settings as $setting) {
  345. $variable = Database::escape_string($setting['name']);
  346. if (!empty($setting['group'])) {
  347. $variable = Database::escape_string($setting['group']);
  348. }
  349. if (empty($variable)) {
  350. continue;
  351. }
  352. $sql = "DELETE FROM $t_course
  353. WHERE c_id = $course_id AND variable = '$variable'";
  354. Database::query($sql);
  355. }
  356. }
  357. $plugin_name = Database::escape_string($plugin_name);
  358. $sql = "DELETE FROM $t_tool WHERE c_id = $course_id AND name = '$plugin_name'";
  359. Database::query($sql);
  360. }
  361. /**
  362. * Install the course fields and tool link of this plugin in all courses
  363. * @param boolean Whether we want to add a plugin link on the course homepage
  364. *
  365. * @return void
  366. */
  367. public function install_course_fields_in_all_courses($add_tool_link = true)
  368. {
  369. // Update existing courses to add conference settings
  370. $t_courses = Database::get_main_table(TABLE_MAIN_COURSE);
  371. $sql = "SELECT id FROM $t_courses ORDER BY id";
  372. $res = Database::query($sql);
  373. while ($row = Database::fetch_assoc($res)) {
  374. $this->install_course_fields($row['id'], $add_tool_link);
  375. }
  376. }
  377. /**
  378. * Uninstall the plugin settings fields from all courses
  379. * @return void
  380. */
  381. public function uninstall_course_fields_in_all_courses()
  382. {
  383. // Update existing courses to add conference settings
  384. $t_courses = Database::get_main_table(TABLE_MAIN_COURSE);
  385. $sql = "SELECT id FROM $t_courses ORDER BY id";
  386. $res = Database::query($sql);
  387. while ($row = Database::fetch_assoc($res)) {
  388. $this->uninstall_course_fields($row['id']);
  389. }
  390. }
  391. /**
  392. * @return array
  393. */
  394. public function getCourseSettings()
  395. {
  396. $settings = array();
  397. if (is_array($this->course_settings)) {
  398. foreach ($this->course_settings as $item) {
  399. if (isset($item['group'])) {
  400. if (!in_array($item['group'], $settings)) {
  401. $settings[] = $item['group'];
  402. }
  403. } else {
  404. $settings[] = $item['name'];
  405. }
  406. }
  407. }
  408. return $settings;
  409. }
  410. /**
  411. * Method to be extended when changing the setting in the course
  412. * configuration should trigger the use of a callback method
  413. * @param array Values sent back from the course configuration script
  414. * @return void
  415. */
  416. public function course_settings_updated($values = array())
  417. {
  418. }
  419. /**
  420. * Add a tab to chamilo's platform
  421. * @param type $tabName
  422. */
  423. public function addTab($tabName, $url)
  424. {
  425. $sql = "SELECT *
  426. FROM settings_current
  427. WHERE variable = 'show_tabs'
  428. AND subkey like 'custom_tab_%'";
  429. $result = Database::query($sql);
  430. $customTabsNum = Database::count_rows($result);
  431. $tabNum = $customTabsNum + 1;
  432. //Avoid Tab Name Spaces
  433. $tabNameNoSpaces = preg_replace('/\s+/', '', $tabName);
  434. $subkeytext = "Tabs" . $tabNameNoSpaces;
  435. $subkey = 'custom_tab_' . $tabNum;
  436. $attributes = array(
  437. 'variable' => 'show_tabs',
  438. 'subkey' => $subkey,
  439. 'type' => 'checkbox',
  440. 'category' => 'Platform',
  441. 'selected_value' => 'true',
  442. 'title' => $tabName,
  443. 'comment' => $url,
  444. 'subkeytext' => $subkeytext,
  445. 'access_url' => 1,
  446. 'access_url_changeable' => 0,
  447. 'access_url_locked' => 0
  448. );
  449. $resp = Database::insert('settings_current', $attributes);
  450. //Save the id
  451. $settings = $this->get_settings();
  452. $setData = array (
  453. 'comment' => $subkey
  454. );
  455. $whereCond = array(
  456. 'id = ?' => key($settings)
  457. );
  458. Database::update('settings_current', $setData, $whereCond);
  459. return $resp;
  460. }
  461. /**
  462. * Delete a tab to chamilo's platform
  463. * @param type $key
  464. */
  465. public function deleteTab($key)
  466. {
  467. $sql = "SELECT *
  468. FROM settings_current
  469. WHERE variable = 'show_tabs'
  470. AND subkey <> '$key'";
  471. $resp = $result = Database::query($sql);
  472. $customTabsNum = Database::count_rows($result);
  473. if (!empty($key)) {
  474. $whereCond = array(
  475. 'variable = ? AND subkey = ?' => array('show_tabs', $key)
  476. );
  477. Database::delete('settings_current', $whereCond);
  478. //if there is more than one tab
  479. //reenumerate them
  480. if ($customTabsNum > 0) {
  481. $i = 1;
  482. while ($row = Database::fetch_assoc($result)) {
  483. $attributes = array(
  484. 'subkey' => 'custom_tab_' . $i
  485. );
  486. $resp = $this->updateTab($row['subkey'], $attributes);
  487. $i++;
  488. }
  489. }
  490. }
  491. return $resp;
  492. }
  493. /**
  494. * Update the tabs attributes
  495. * @param string $key
  496. * @param array $attributes
  497. * @return boolean
  498. */
  499. public function updateTab($key, $attributes)
  500. {
  501. $whereCond = array(
  502. 'variable = ? AND subkey = ?' => array('show_tabs', $key)
  503. );
  504. $resp = Database::update('settings_current', $attributes, $whereCond);
  505. return $resp;
  506. }
  507. /**
  508. * Add aditional plugin Settings
  509. * @param array $settings
  510. */
  511. public function addExtraSettings($settings)
  512. {
  513. $pluginName = $this->get_name();
  514. $resp = false;
  515. foreach ($settings as $setting => $value) {
  516. $attributes = array(
  517. 'variable' => 'plugin_settings_' . $pluginName,
  518. 'subkey' => $setting,
  519. 'selected_value' => $value,
  520. 'category' => 'PluginSettings'
  521. );
  522. if (empty($this->getExtraSettingValue($setting))) {
  523. $resp = Database::insert('settings_current', $attributes);
  524. }
  525. }
  526. return $resp;
  527. }
  528. /**
  529. * Edit aditional Plugin Settings
  530. * @param array $settings
  531. */
  532. public function editExtraSetting($key, $attributes)
  533. {
  534. $pluginName = $this->get_name();
  535. $whereCond = array(
  536. 'variable = ? AND subkey = ?' => array('plugin_settings_' . $pluginName, $key)
  537. );
  538. $resp = Database::update('settings_current', $attributes, $whereCond);
  539. return $resp;
  540. }
  541. /**
  542. * Delete all aditional plugin settings
  543. */
  544. public function deleteExtraSettings()
  545. {
  546. $pluginName = $this->get_name();
  547. $whereCond = array(
  548. 'variable = ?' => 'plugin_settings_' . $pluginName
  549. );
  550. $resp = Database::delete('settings_current', $whereCond);
  551. return $resp;
  552. }
  553. /**
  554. * Give extra setting value
  555. * @param string $settingName
  556. */
  557. public function getExtraSettingValue($settingName)
  558. {
  559. $pluginName = $this->get_name();
  560. $fullSetting = api_get_full_setting('plugin_settings_' . $pluginName, $settingName);
  561. if (empty($fullSetting)) {
  562. return false;
  563. } else {
  564. $setting = current($fullSetting);
  565. return $setting['selected_value'];
  566. }
  567. }
  568. }