Browse Source

Extended possibilities of plugin class to allow for invisible course plugins - refs #4796

Yannick Warnier 12 years ago
parent
commit
1235cff872
1 changed files with 97 additions and 11 deletions
  1. 97 11
      main/inc/lib/plugin.class.php

+ 97 - 11
main/inc/lib/plugin.class.php

@@ -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);