Browse Source

Minor - Adding doc blocks, format code.

Julio Montoya 11 years ago
parent
commit
2aed8b37e2
2 changed files with 188 additions and 105 deletions
  1. 69 37
      main/inc/lib/plugin.class.php
  2. 119 68
      main/inc/lib/plugin.lib.php

+ 69 - 37
main/inc/lib/plugin.class.php

@@ -3,7 +3,7 @@
 
 /**
  * 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
  *
@@ -14,18 +14,18 @@
  * @author Yannick Warnier <ywarnier@beeznest.org> added documentation
  *
  */
-class Plugin {
-
+class Plugin
+{
     protected $version = '';
     protected $author = '';
     protected $fields = array();
 
     private $settings = null;
     private $strings = null; //translation strings
-    public  $is_course_plugin = false;
+    public $is_course_plugin = false;
 
     /**
-     * When creating a new course, these settings are added to the course, in 
+     * When creating a new course, these settings are added to the course, in
      * the course_info/infocours.php
      * To show the plugin course icons you need to add these icons:
      * main/img/icons/22/plugin_name.png
@@ -37,12 +37,12 @@ class Plugin {
                     array('name' => 'big_blue_button_record_and_store', 'type' => 'checkbox')
         );
      */
-    public  $course_settings = array();
+    public $course_settings = array();
     /**
      * This indicates whether changing the setting should execute the callback
      * function.
      */
-    public  $course_settings_callback = false;
+    public $course_settings_callback = false;
 
     /**
      * Default constructor for the plugin class. By default, it only sets
@@ -50,9 +50,9 @@ class Plugin {
      * @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()) {
+    protected function __construct($version, $author, $settings = array())
+    {
         $this->version = $version;
         $this->author = $author;
         $this->fields = $settings;
@@ -60,11 +60,13 @@ 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() {
+    public function get_info()
+    {
         $result = array();
 
         $result['title']            = $this->get_title();
@@ -72,7 +74,7 @@ class Plugin {
         $result['version']          = $this->get_version();
         $result['author']           = $this->get_author();
         $result['plugin_class']     = get_class($this);
-        $result['is_course_plugin'] = $this->is_course_plugin;        
+        $result['is_course_plugin'] = $this->is_course_plugin;
 
         if ($form = $this->get_settings_form()) {
             $result['settings_form'] = $form;
@@ -83,11 +85,14 @@ class Plugin {
         }
         return $result;
     }
+
     /**
      * Returns the "system" name of the plugin in lowercase letters
      * @param string Name of the plugin
+     * @return string
      */
-    function get_name() {
+    public function get_name()
+    {
         $result = get_class($this);
         $result = str_replace('Plugin', '', $result);
         $result = strtolower($result);
@@ -96,41 +101,51 @@ class Plugin {
 
     /**
      * Returns the title of the plugin
-     * @param string Title of the plugin
+     * @param string title of the plugin
+     * @return string
      */
-    function get_title() {
+    public function get_title()
+    {
         return $this->get_lang('plugin_title');
     }
 
     /**
      * Returns the description of the plugin
-     * @param string Description of the plugin
+     * @param string description of the plugin
+     * @return string
      */
-    function get_comment() {
+    public function get_comment()
+    {
         return $this->get_lang('plugin_comment');
     }
 
     /**
      * Returns the version of the plugin
      * @param string Version of the plugin
+     * @return string
      */
-    function get_version() {
+    public function get_version()
+    {
         return $this->version;
     }
 
     /**
      * Returns the author of the plugin
      * @param string Author(s) of the plugin
+     * @return string
      */
-    function get_author() {
+    public function get_author()
+    {
         return $this->author;
     }
 
     /**
      * Returns the contents of the CSS defined by the plugin
      * @param string The CSS string
+     * @return array
      */
-    function get_css() {
+    public function get_css()
+    {
         $name = $this->get_name();
         $path = api_get_path(SYS_PLUGIN_PATH)."$name/resources/$name.css";
         if (!is_readable($path)) {
@@ -146,7 +161,8 @@ class Plugin {
      * Returns an HTML form (generated by FormValidator) of the plugin settings
      * @return string FormValidator-generated form
      */
-    function get_settings_form() {
+    public function get_settings_form()
+    {
         $result = new FormValidator($this->get_name());
 
         $defaults = array();
@@ -174,7 +190,7 @@ class Plugin {
                 case 'boolean':
                     $group = array();
                     $group[] = $result->createElement('radio', $name, '', get_lang('Yes'), 'true');
-                    $group[] = $result->createElement('radio', $name, '', get_lang('No'),  'false');
+                    $group[] = $result->createElement('radio', $name, '', get_lang('No'), 'false');
                     $result->addGroup($group, null, array($this->get_lang($name), $help));
                     break;
             }
@@ -189,7 +205,8 @@ class Plugin {
      * @param string Name of the plugin
      * @return string Value of the plugin
      */
-    function get($name) {
+    public function get($name)
+    {
         $settings = $this->get_settings();
         foreach ($settings as $setting) {
             if ($setting['variable'] == ($this->get_name() . '_' . $name)) {
@@ -203,7 +220,8 @@ class Plugin {
      * Returns an array with the global settings for this plugin
      * @return array Plugin settings as an array
      */
-    public function get_settings() {
+    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')));
             $this->settings = $settings;
@@ -214,9 +232,10 @@ class Plugin {
     /**
      * 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
+     * @return boolean True if the plugin has language variables defined, false otherwise
      */
-    public function get_lang_plugin_exists($name) {
+    public function get_lang_plugin_exists($name)
+    {
         return isset($this->strings[$name]);
     }
 
@@ -225,7 +244,8 @@ class Plugin {
      * @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) {
+    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)) {
@@ -249,7 +269,7 @@ class Plugin {
                         $this->strings[$key] = $string;
                     }
                 }
-            } 
+            }
         }
 
         if (isset($this->strings[$name])) {
@@ -264,18 +284,19 @@ class Plugin {
      * @param boolean Whether to add a tool link on the course homepage
      * @return void
      */
-    function course_install($course_id, $add_tool_link = true) {
+    public function course_install($course_id, $add_tool_link = true)
+    {
         $this->install_course_fields($course_id, $add_tool_link);
     }
 
-
     /**
      * 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) {
+    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);
 
@@ -313,8 +334,12 @@ class Plugin {
                 }
             }
         }
+
         // Stop here if we don't want a tool link on the course homepage
-        if (!$add_tool_link) { return true; }
+        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' ";
@@ -322,8 +347,9 @@ class Plugin {
         if (!Database::num_rows($result)) {
             $tool_link = "$plugin_name/start.php";
             $visibility = string2binary(api_get_setting('course_create_active_tools', $plugin_name));
-            $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')";
-            $r = Database::query($sql_course);
+            $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')";
+            Database::query($sql_course);
         }
     }
 
@@ -333,7 +359,8 @@ class Plugin {
      * @param int The integer course ID
      * @return void
      */
-    public function uninstall_course_fields($course_id) {
+    public function uninstall_course_fields($course_id)
+    {
         $course_id = intval($course_id);
         if (empty($course_id)) {
             return false;
@@ -363,7 +390,8 @@ class Plugin {
      * @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) {
+    public 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";
@@ -377,7 +405,8 @@ class Plugin {
      * Uninstall the plugin settings fields from all courses
      * @return void
      */
-    function uninstall_course_fields_in_all_courses() {
+    public function uninstall_course_fields_in_all_courses()
+    {
         // 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";
@@ -386,12 +415,15 @@ class Plugin {
             $this->uninstall_course_fields($row['id']);
         }
     }
+
     /**
      * Method to be extended when changing the setting in the course
      * configuration should trigger the use of a callback method
      * @param array Values sent back from the course configuration script
      * @return void
      */
-    public function course_settings_updated($values = array()) {
+    public function course_settings_updated($values = array())
+    {
+
     }
 }

+ 119 - 68
main/inc/lib/plugin.lib.php

@@ -1,34 +1,34 @@
 <?php
 /* See license terms in /license.txt */
 
-class AppPlugin {
-    var $plugin_regions = array (
- //           'loginpage_main',
-            'login_top',
-            'login_bottom',
-            'menu_top',
-            'menu_bottom',
-/*            'campushomepage_main',
-            'campushomepage_menu',
-            'mycourses_main',
-            'mycourses_menu',*/
-            'content_top',
-            'content_bottom',
-            'header_main',
-            'header_center',
-            'header_left',
-            'header_right',
-            //'footer',
-            'footer_left',
-            'footer_center',
-            'footer_right',
-            'course_tool_plugin'
+class AppPlugin
+{
+    public $plugin_regions = array(
+        'login_top',
+        'login_bottom',
+        'menu_top',
+        'menu_bottom',
+        'content_top',
+        'content_bottom',
+        'header_main',
+        'header_center',
+        'header_left',
+        'header_right',
+        'footer_left',
+        'footer_center',
+        'footer_right',
+        'course_tool_plugin'
     );
 
-    function __construct() {
+    public function __construct()
+    {
     }
 
-    function read_plugins_from_path() {
+    /**
+     * @return array
+     */
+    function read_plugins_from_path()
+    {
         /* We scan the plugin directory. Each folder is a potential plugin. */
         $pluginpath = api_get_path(SYS_PLUGIN_PATH);
         $possible_plugins = array();
@@ -43,7 +43,11 @@ class AppPlugin {
         return $possible_plugins;
     }
 
-    function get_installed_plugins_by_region(){
+    /**
+     * @return array
+     */
+    function get_installed_plugins_by_region()
+    {
         $used_plugins = array();
         /* We retrieve all the active plugins. */
         $result = api_get_settings('Plugins');
@@ -53,7 +57,11 @@ class AppPlugin {
         return $used_plugins;
     }
 
-    function get_installed_plugins() {
+    /**
+     * @return array
+     */
+    function get_installed_plugins()
+    {
         $installed_plugins = array();
         $plugin_array = api_get_settings_params(array("variable = ? AND selected_value = ? AND category = ? " =>
                                                 array('status', 'installed', 'Plugins')));
@@ -67,7 +75,12 @@ class AppPlugin {
         return $installed_plugins;
     }
 
-    function install($plugin_name, $access_url_id = null) {
+    /**
+     * @param string $plugin_name
+     * @param int $access_url_id
+     */
+    function install($plugin_name, $access_url_id = null)
+    {
         if (empty($access_url_id)) {
             $access_url_id = api_get_current_access_url_id();
         } else {
@@ -84,7 +97,12 @@ class AppPlugin {
         }
     }
 
-    function uninstall($plugin_name, $access_url_id = null) {
+    /**
+     * @param string $plugin_name
+     * @param int $access_url_id
+     */
+    public function uninstall($plugin_name, $access_url_id = null)
+    {
         if (empty($access_url_id)) {
             $access_url_id = api_get_current_access_url_id();
         } else {
@@ -99,7 +117,12 @@ class AppPlugin {
         }
     }
 
-    function get_areas_by_plugin($plugin_name) {
+    /**
+     * @param string $plugin_name
+     * @return array
+     */
+    public function get_areas_by_plugin($plugin_name)
+    {
         $result = api_get_settings('Plugins');
         $areas = array();
         foreach ($result as $row) {
@@ -110,11 +133,13 @@ class AppPlugin {
         return $areas;
     }
 
-    function is_valid_plugin_location($location) {
+    function is_valid_plugin_location($location)
+    {
         return in_array($location, $this->plugin_list);
     }
 
-    function is_valid_plugin($plugin_name) {
+    function is_valid_plugin($plugin_name)
+    {
         if (is_dir(api_get_path(SYS_PLUGIN_PATH).$plugin_name)) {
             if (is_file(api_get_path(SYS_PLUGIN_PATH).$plugin_name.'/index.php')) {
                 return true;
@@ -123,19 +148,21 @@ class AppPlugin {
         return false;
     }
 
-    function get_plugin_regions() {
+    function get_plugin_regions()
+    {
         sort($this->plugin_regions);
         return $this->plugin_regions;
     }
 
-    function load_region($region, $main_template, $forced = false) {        
-        if ($region == 'course_tool_plugin') {                        
-            return null;       
+    function load_region($region, $main_template, $forced = false)
+    {
+        if ($region == 'course_tool_plugin') {
+            return null;
         }
         ob_start();
         $this->get_all_plugin_contents_by_region($region, $main_template, $forced);
         $content = ob_get_contents();
-        ob_end_clean();        
+        ob_end_clean();
         return $content;
     }
 
@@ -145,29 +172,30 @@ class AppPlugin {
      * @todo add caching
      * @param string $plugin_name
      */
-    function load_plugin_lang_variables($plugin_name) {
+    function load_plugin_lang_variables($plugin_name)
+    {
         global $language_interface;
         $root = api_get_path(SYS_PLUGIN_PATH);
 
-        //1. Loading english if exists
-        $english_path = $root.$plugin_name."/lang/english.php";     
+        // 1. Loading english if exists
+        $english_path = $root.$plugin_name."/lang/english.php";
 
         if (is_readable($english_path)) {
             include $english_path;
-   
-            foreach ($strings as $key => $string) {                
+
+            foreach ($strings as $key => $string) {
                 $GLOBALS[$key] = $string;
             }
         }
 
-        //2. Loading the system language
+        // 2. Loading the system language
         if ($language_interface != 'english') {
             $path = $root.$plugin_name."/lang/$language_interface.php";
 
             if (is_readable($path)) {
                 include $path;
                 if (!empty($strings)) {
-                    foreach ($strings as $key => $string) {                        
+                    foreach ($strings as $key => $string) {
                         $GLOBALS[$key] = $string;
                     }
                 }
@@ -176,21 +204,21 @@ class AppPlugin {
     }
 
     /**
-     *
      *
      * @param string $block
      * @param obj   template obj
      * @todo improve this function
      */
-    function get_all_plugin_contents_by_region($region, $template, $forced = false) {
-        global $_plugins;                
+    function get_all_plugin_contents_by_region($region, $template, $forced = false)
+    {
+        global $_plugins;
         if (isset($_plugins[$region]) && is_array($_plugins[$region])) {
-        //if (1) {        
+        //if (1) {
             //Load the plugin information
             foreach ($_plugins[$region] as $plugin_name) {
 
                 //The plugin_info variable is available inside the plugin index
-                $plugin_info = $this->get_plugin_info($plugin_name, $forced);                
+                $plugin_info = $this->get_plugin_info($plugin_name, $forced);
 
                 //We also know where the plugin is
                 $plugin_info['current_region'] = $region;
@@ -247,14 +275,15 @@ class AppPlugin {
      * @todo filter setting_form
      * @return array
      */
-    function get_plugin_info($plugin_name, $forced = false) {
+    function get_plugin_info($plugin_name, $forced = false)
+    {
         static $plugin_data = array();
-        
+
         if (isset($plugin_data[$plugin_name]) && $forced == false) {
             return $plugin_data[$plugin_name];
         } else {
             $plugin_file = api_get_path(SYS_PLUGIN_PATH)."$plugin_name/plugin.php";
-            
+
             $plugin_info = array();
             if (file_exists($plugin_file)) {
                 require $plugin_file;
@@ -268,15 +297,18 @@ class AppPlugin {
                 $settings_filtered[$item['variable']] = $item['selected_value'];
             }
             $plugin_info['settings'] = $settings_filtered;
-            $plugin_data[$plugin_name] = $plugin_info;            
+            $plugin_data[$plugin_name] = $plugin_info;
             return $plugin_info;
         }
     }
 
-    /*
+    /**
      * Get the template list
+     * @param  string $plugin_name
+     * @return bool
      */
-    function get_templates_list($plugin_name) {
+    function get_templates_list($plugin_name)
+    {
         $plugin_info = $this->get_plugin_info($plugin_name);
         if (isset($plugin_info) && isset($plugin_info['templates'])) {
             return $plugin_info['templates'];
@@ -285,10 +317,11 @@ class AppPlugin {
         }
     }
 
-    /* *
+    /**
      * Remove all regions of an specific plugin
      */
-    function remove_all_regions($plugin) {
+    public function remove_all_regions($plugin)
+    {
         $access_url_id = api_get_current_access_url_id();
         if (!empty($plugin)) {
             api_delete_settings_params(array('category = ? AND type = ? AND access_url = ? AND subkey = ? ' =>
@@ -297,15 +330,22 @@ class AppPlugin {
         }
     }
 
-    /*
+    /**
      * Add a plugin to a region
+     * @param string $plugin
+     * @param string $region
      */
-    function add_to_region($plugin, $region) {
+    function add_to_region($plugin, $region)
+    {
         $access_url_id = api_get_current_access_url_id();
         api_add_setting($plugin, $region, $plugin, 'region', 'Plugins', $plugin, null, null, null, $access_url_id, 1);
     }
 
-    function install_course_plugins($course_id) {
+    /**
+     * @param int $course_id
+     */
+    function install_course_plugins($course_id)
+    {
         $plugin_list = $this->get_installed_plugins();
 
         if (!empty($plugin_list)) {
@@ -321,7 +361,11 @@ class AppPlugin {
         }
     }
 
-    function add_course_settings_form($form) {
+    /**
+     * @param FormValidator $form
+     */
+    function add_course_settings_form($form)
+    {
         $plugin_list = $this->get_installed_plugins();
         foreach ($plugin_list as $plugin_name) {
             $plugin_info = $this->get_plugin_info($plugin_name);
@@ -357,7 +401,11 @@ class AppPlugin {
         }
     }
 
-    function set_course_settings_defaults(& $values) {
+    /**
+     * @param array $values
+     */
+    function set_course_settings_defaults(& $values)
+    {
         $plugin_list = $this->get_installed_plugins();
         foreach ($plugin_list as $plugin_name) {
             $plugin_info = $this->get_plugin_info($plugin_name);
@@ -376,13 +424,15 @@ class AppPlugin {
             }
         }
     }
+
     /**
-     * When saving the plugin values in the course settings, check whether 
+     * When saving the plugin values in the course settings, check whether
      * a callback method should be called and send it the updated settings
      * @param array The new settings the user just saved
      * @return void
      */
-    function save_course_settings($values) {
+    function save_course_settings($values)
+    {
         $plugin_list = $this->get_installed_plugins();
         foreach ($plugin_list as $plugin_name) {
             $settings = $this->get_plugin_course_settings($plugin_name);
@@ -396,7 +446,7 @@ class AppPlugin {
             }
             if ($i>0) {
                 $plugin_info = $this->get_plugin_info($plugin_name);
-                
+
                 if (isset($plugin_info['plugin_class'])) {
                     $obj = $plugin_info['plugin_class']::create();
                     $obj->course_settings_updated($subvalues);
@@ -404,17 +454,18 @@ class AppPlugin {
             }
         }
     }
-    
+
     /**
      * Gets a nice array of keys for just the plugin's course settings
      * @param string The plugin ID
      * @return array Nice array of keys for course settings
-     */ 
-    public function get_plugin_course_settings($plugin_name) {
+     */
+    public function get_plugin_course_settings($plugin_name)
+    {
         $settings = array();
         if (empty($plugin_name)) { return $settings; }
         $plugin_info = $this->get_plugin_info($plugin_name);
-        
+
         if (isset($plugin_info['plugin_class'])) {
             $obj = $plugin_info['plugin_class']::create();
             if (is_array($obj->course_settings)) {