|
@@ -3,11 +3,15 @@
|
|
|
|
|
|
/**
|
|
|
* Base class for plugins
|
|
|
+ *
|
|
|
+ * This class has to be extended by every plugin. It defines basic methods
|
|
|
+ * to install/uninstall and get information about a plugin
|
|
|
*
|
|
|
* @copyright (c) 2012 University of Geneva
|
|
|
* @license GNU General Public License - http://www.gnu.org/copyleft/gpl.html
|
|
|
* @author Laurent Opprecht <laurent@opprecht.info>
|
|
|
* @author Julio Montoya <gugli100@gmail.com> added course settings support + lang variable fixes
|
|
|
+ * @author Yannick Warnier <ywarnier@beeznest.org> added documentation
|
|
|
*
|
|
|
*/
|
|
|
class Plugin {
|
|
@@ -35,6 +39,14 @@ class Plugin {
|
|
|
*/
|
|
|
public $course_settings = array();
|
|
|
|
|
|
+ /**
|
|
|
+ * Default constructor for the plugin class. By default, it only sets
|
|
|
+ * a few attributes of the object
|
|
|
+ * @param string Version of this plugin
|
|
|
+ * @param string Author of this plugin
|
|
|
+ * @param array Array of global settings to be proposed to configure the plugin
|
|
|
+ * @return void
|
|
|
+ */
|
|
|
protected function __construct($version, $author, $settings = array()) {
|
|
|
$this->version = $version;
|
|
|
$this->author = $author;
|
|
@@ -43,7 +55,10 @@ class Plugin {
|
|
|
global $language_files;
|
|
|
$language_files[] = 'plugin_' . $this->get_name();
|
|
|
}
|
|
|
-
|
|
|
+ /**
|
|
|
+ * Gets an array of information about this plugin (name, version, ...)
|
|
|
+ * @return array Array of information elements about this plugin
|
|
|
+ */
|
|
|
function get_info() {
|
|
|
$result = array();
|
|
|
|
|
@@ -63,7 +78,10 @@ class Plugin {
|
|
|
}
|
|
|
return $result;
|
|
|
}
|
|
|
-
|
|
|
+ /**
|
|
|
+ * Returns the "system" name of the plugin in lowercase letters
|
|
|
+ * @param string Name of the plugin
|
|
|
+ */
|
|
|
function get_name() {
|
|
|
$result = get_class($this);
|
|
|
$result = str_replace('Plugin', '', $result);
|
|
@@ -71,22 +89,42 @@ class Plugin {
|
|
|
return $result;
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Returns the title of the plugin
|
|
|
+ * @param string Title of the plugin
|
|
|
+ */
|
|
|
function get_title() {
|
|
|
return $this->get_lang('plugin_title');
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Returns the description of the plugin
|
|
|
+ * @param string Description of the plugin
|
|
|
+ */
|
|
|
function get_comment() {
|
|
|
return $this->get_lang('plugin_comment');
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Returns the version of the plugin
|
|
|
+ * @param string Version of the plugin
|
|
|
+ */
|
|
|
function get_version() {
|
|
|
return $this->version;
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Returns the author of the plugin
|
|
|
+ * @param string Author(s) of the plugin
|
|
|
+ */
|
|
|
function get_author() {
|
|
|
return $this->author;
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Returns the contents of the CSS defined by the plugin
|
|
|
+ * @param string The CSS string
|
|
|
+ */
|
|
|
function get_css() {
|
|
|
$name = $this->get_name();
|
|
|
$path = api_get_path(SYS_PLUGIN_PATH)."$name/resources/$name.css";
|
|
@@ -100,8 +138,8 @@ class Plugin {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- *
|
|
|
- * @return FormValidator
|
|
|
+ * Returns an HTML form (generated by FormValidator) of the plugin settings
|
|
|
+ * @return string FormValidator-generated form
|
|
|
*/
|
|
|
function get_settings_form() {
|
|
|
$result = new FormValidator($this->get_name());
|
|
@@ -141,6 +179,11 @@ class Plugin {
|
|
|
return $result;
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Returns the value of a given plugin global setting
|
|
|
+ * @param string Name of the plugin
|
|
|
+ * @return string Value of the plugin
|
|
|
+ */
|
|
|
function get($name) {
|
|
|
$settings = $this->get_settings();
|
|
|
foreach ($settings as $setting) {
|
|
@@ -151,6 +194,10 @@ class Plugin {
|
|
|
return false;
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Returns an array with the global settings for this plugin
|
|
|
+ * @return array Plugin settings as an array
|
|
|
+ */
|
|
|
public function get_settings() {
|
|
|
if (is_null($this->settings)) {
|
|
|
$settings = api_get_settings_params(array("subkey = ? AND category = ? AND type = ? " => array($this->get_name(), 'Plugins', 'setting')));
|
|
@@ -159,11 +206,23 @@ class Plugin {
|
|
|
return $this->settings;
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Tells whether language variables are defined for this plugin or not
|
|
|
+ * @param string System name of the plugin
|
|
|
+ * @return boolean True if the plugin has languag variables defined, false otherwise
|
|
|
+ */
|
|
|
public function get_lang_plugin_exists($name) {
|
|
|
return isset($this->strings[$name]);
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Hook for the get_lang() function to check for plugin-defined language terms
|
|
|
+ * @param string Name of the language variable we are looking for
|
|
|
+ * @return string The translated language term of the plugin
|
|
|
+ */
|
|
|
public function get_lang($name) {
|
|
|
+ // Check whether the language strings for the plugin have already been
|
|
|
+ // loaded. If so, no need to load them again.
|
|
|
if (is_null($this->strings)) {
|
|
|
global $language_interface;
|
|
|
$root = api_get_path(SYS_PLUGIN_PATH);
|
|
@@ -194,13 +253,24 @@ class Plugin {
|
|
|
return get_lang($name);
|
|
|
}
|
|
|
|
|
|
- function course_install($course_id) {
|
|
|
- $this->install_course_fields($course_id);
|
|
|
+ /**
|
|
|
+ * Caller for the install_course_fields() function
|
|
|
+ * @param int The course's integer ID
|
|
|
+ * @param boolean Whether to add a tool link on the course homepage
|
|
|
+ * @return void
|
|
|
+ */
|
|
|
+ function course_install($course_id, $add_tool_link = true) {
|
|
|
+ $this->install_course_fields($course_id, $add_tool_link);
|
|
|
}
|
|
|
|
|
|
|
|
|
- /* Add course settings and add a tool link */
|
|
|
- public function install_course_fields($course_id) {
|
|
|
+ /**
|
|
|
+ * Add course settings and, if not asked otherwise, add a tool link on the course homepage
|
|
|
+ * @param int Course integer ID
|
|
|
+ * @param boolean Whether to add a tool link or not (some tools might just offer a configuration section and act on the backend)
|
|
|
+ * @return boolean False on error, null otherwise
|
|
|
+ */
|
|
|
+ public function install_course_fields($course_id, $add_tool_link = true) {
|
|
|
$plugin_name = $this->get_name();
|
|
|
$t_course = Database::get_course_table(TABLE_COURSE_SETTING);
|
|
|
|
|
@@ -220,7 +290,8 @@ class Plugin {
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
-
|
|
|
+ // Stop here if we don't want a tool link on the course homepage
|
|
|
+ if (!$add_tool_link) { return true; }
|
|
|
//Add an icon in the table tool list
|
|
|
$t_tool = Database::get_course_table(TABLE_TOOL_LIST);
|
|
|
$sql = "SELECT name FROM $t_tool WHERE c_id = $course_id AND name = '$plugin_name' ";
|
|
@@ -233,6 +304,12 @@ class Plugin {
|
|
|
}
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Delete the fields added to the course settings page and the link to the
|
|
|
+ * tool on the course's homepage
|
|
|
+ * @param int The integer course ID
|
|
|
+ * @return void
|
|
|
+ */
|
|
|
public function uninstall_course_fields($course_id) {
|
|
|
$course_id = intval($course_id);
|
|
|
if (empty($course_id)) {
|
|
@@ -255,16 +332,25 @@ class Plugin {
|
|
|
Database::query($sql_course);
|
|
|
}
|
|
|
|
|
|
- function install_course_fields_in_all_courses() {
|
|
|
+ /**
|
|
|
+ * Install the course fields and tool link of this plugin in all courses
|
|
|
+ * @param boolean Whether we want to add a plugin link on the course homepage
|
|
|
+ * @return void
|
|
|
+ */
|
|
|
+ function install_course_fields_in_all_courses($add_tool_link = true) {
|
|
|
// Update existing courses to add conference settings
|
|
|
$t_courses = Database::get_main_table(TABLE_MAIN_COURSE);
|
|
|
$sql = "SELECT id, code FROM $t_courses ORDER BY id";
|
|
|
$res = Database::query($sql);
|
|
|
while ($row = Database::fetch_assoc($res)) {
|
|
|
- $this->install_course_fields($row['id']);
|
|
|
+ $this->install_course_fields($row['id'], $add_tool_link);
|
|
|
}
|
|
|
}
|
|
|
|
|
|
+ /**
|
|
|
+ * Uninstall the plugin settings fields from all courses
|
|
|
+ * @return void
|
|
|
+ */
|
|
|
function uninstall_course_fields_in_all_courses() {
|
|
|
// Update existing courses to add conference settings
|
|
|
$t_courses = Database::get_main_table(TABLE_MAIN_COURSE);
|