Merged branch wip-MDL-30521 with conflict resolutions
authorSam Hemelryk <sam@moodle.com>
Sun, 19 Feb 2012 21:32:08 +0000 (10:32 +1300)
committerSam Hemelryk <sam@moodle.com>
Sun, 19 Feb 2012 21:32:08 +0000 (10:32 +1300)
141 files changed:
admin/cli/install.php
admin/settings.php
admin/tool/dbtransfer/locallib.php
admin/tool/uploaduser/index.php
admin/tool/xmldb/actions/create_xml_file/create_xml_file.class.php
admin/webservice/forms.php
admin/webservice/service_functions.php
admin/webservice/service_users.php
blocks/comments/lib.php
blog/lib.php
comment/comment_ajax.php
comment/comment_post.php
comment/index.php
comment/lib.php
comment/locallib.php
course/renderer.php
course/search.php
enrol/category/db/access.php
filter/data/filter.php
filter/mediaplugin/filter.php
grade/export/grade_export_form.php
grade/grading/form/lib.php
grade/grading/form/rubric/lang/en/gradingform_rubric.php
grade/grading/form/rubric/lib.php
grade/grading/form/rubric/preview.php [new file with mode: 0644]
grade/grading/form/rubric/renderer.php
grade/grading/lib.php
grade/report/grader/lib.php
install/lang/rm_surs/moodle.php [new file with mode: 0644]
install/lang/vi/admin.php
lang/en/form.php
lang/en/langconfig.php
lang/en/moodle.php
lib/accesslib.php
lib/adminlib.php
lib/completion/completion_criteria_date.php
lib/datalib.php
lib/db/upgrade.php
lib/ddl/database_manager.php
lib/ddl/mssql_sql_generator.php
lib/ddl/mysql_sql_generator.php
lib/ddl/oracle_sql_generator.php
lib/ddl/postgres_sql_generator.php
lib/ddl/sql_generator.php
lib/ddl/sqlite_sql_generator.php
lib/form/dndupload.js
lib/form/filemanager.js
lib/form/filemanager.php
lib/form/filepicker.js
lib/formslib.php
lib/htmlpurifier/HTMLPurifier/Lexer/PH5P.php
lib/javascript-static.js
lib/moodlelib.php
lib/navigationlib.php
lib/outputrequirementslib.php
lib/portfolio/caller.php
lib/portfolio/constants.php
lib/portfolio/exceptions.php
lib/portfolio/exporter.php
lib/portfolio/formats.php
lib/portfolio/formats/leap2a/lib.php
lib/portfolio/forms.php
lib/portfolio/plugin.php
lib/portfoliolib.php
lib/simpletest/testmoodlelib.php
lib/yui/formslib/formslib.js [new file with mode: 0644]
mod/assignment/db/log.php
mod/assignment/lib.php
mod/chat/db/log.php
mod/choice/db/log.php
mod/choice/renderer.php
mod/data/db/log.php
mod/data/export.php
mod/data/field/file/field.class.php
mod/data/lib.php
mod/feedback/db/log.php
mod/folder/db/log.php
mod/forum/db/log.php
mod/glossary/db/log.php
mod/glossary/lib.php
mod/imscp/db/log.php
mod/label/db/log.php
mod/lesson/backup/moodle2/backup_lesson_stepslib.php
mod/lesson/db/log.php
mod/lesson/pagetypes/branchtable.php
mod/lesson/view.php
mod/lti/db/log.php
mod/lti/lang/en/lti.php
mod/page/db/log.php
mod/quiz/db/log.php
mod/quiz/view.php
mod/resource/db/log.php
mod/resource/lang/en/resource.php
mod/scorm/db/log.php
mod/survey/db/log.php
mod/url/db/log.php
mod/url/lang/en/url.php
mod/wiki/editors/wiki_editor.php
mod/wiki/lang/en/wiki.php
mod/wiki/lib.php
mod/workshop/db/log.php
portfolio/add.php
portfolio/file.php
portfolio/mahara/lang/en/portfolio_mahara.php
question/engine/upgrade/upgradelib.php
report/log/db/access.php
report/log/db/install.php
report/log/graph.php
report/log/index.php
report/log/lang/en/report_log.php
report/log/lib.php
report/log/locallib.php
report/log/settings.php
report/log/user.php
report/log/version.php
report/loglive/db/access.php
report/loglive/index.php
report/loglive/lang/en/report_loglive.php
report/loglive/lib.php
report/loglive/settings.php
report/loglive/version.php
report/stats/graph.php
repository/lib.php
repository/recent/lib.php
repository/upload/lang/en/repository_upload.php
repository/upload/lib.php
tag/coursetags_add.php
tag/coursetags_edit.php
tag/coursetags_more.php
tag/coursetagslib.php
tag/edit.php
tag/edit_form.php
tag/index.php
tag/lib.php
tag/locallib.php
theme/base/style/core.css
theme/styles.php
user/view.php
version.php
webservice/rest/lib.php
webservice/rest/simpleserver.php

index b812aaf..dc65e31 100644 (file)
@@ -109,7 +109,7 @@ if (file_exists($configfile)) {
 
 $olddir = getcwd();
 
-// change directory so that includes bellow work properly
+// change directory so that includes below work properly
 chdir(dirname($_SERVER['argv'][0]));
 
 // Servers should define a default timezone in php.ini, but if they don't then make sure something is defined.
index 3344f35..3f8d2c9 100644 (file)
@@ -131,6 +131,12 @@ if (empty($SITE->fullname)) {
     echo '</form>';
 }
 
-echo $OUTPUT->footer();
-
+$PAGE->requires->yui_module('moodle-core-formslib',
+        'M.core.init_formslib',
+        array(array(
+            'formid' => 'adminsettings'
+        ))
+);
+$PAGE->requires->string_for_js('changesmadereallygoaway', 'moodle');
 
+echo $OUTPUT->footer();
index 62a34ae..f36ceef 100644 (file)
@@ -37,7 +37,7 @@ TODO:
     (user would need file access to dataroot which might prevent various "accidents")
   - implement "Export/import running" notification in lib/setup.php (similar to new upgrade flag in config table)
   - gzip compression when storing xml file - the xml is very verbose and full of repeated tags (zip is not suitable here at all)
-    this could help us keep the files bellow 2G (expected ratio is > 10:1)
+    this could help us keep the files below 2G (expected ratio is > 10:1)
 
 */
 
index a0a69b0..633b5f2 100644 (file)
@@ -239,7 +239,7 @@ if ($formdata = $mform2->is_cancelled()) {
             }
         }
         if (!isset($user->username)) {
-            // prevent warnings bellow
+            // prevent warnings below
             $user->username = '';
         }
 
index 205700f..1cf3969 100644 (file)
@@ -68,6 +68,7 @@ class create_xml_file extends XMLDBAction {
 
         // Get the dir containing the file
         $dirpath = required_param('dir', PARAM_PATH);
+        $plugintype = $this->get_plugin_type($dirpath);
         $dirpath = $CFG->dirroot . $dirpath;
         $file = $dirpath . '/install.xml';
 
@@ -77,6 +78,9 @@ class create_xml_file extends XMLDBAction {
         $xmlcomment = 'XMLDB file for Moodle ' . dirname($xmlpath);
 
         $xmltable = strtolower(basename(dirname($xmlpath)));
+        if ($plugintype && $plugintype != 'mod') {
+            $xmltable = $plugintype.'_'.$xmltable;
+        }
 
         // Initial contents
         $c = '<?xml version="1.0" encoding="UTF-8" ?>' . "\n";
@@ -106,5 +110,23 @@ class create_xml_file extends XMLDBAction {
         // Return ok if arrived here
         return $result;
     }
+
+    /**
+     * From a given path, work out what type of plugin
+     * this belongs to
+     * @param string $dirpath Path to the db file for this plugin
+     * @return string the type of the plugin or null if not found
+     */
+    function get_plugin_type($dirpath) {
+        global $CFG;
+        $dirpath = $CFG->dirroot.$dirpath;
+        $plugintypes = get_plugin_types();
+        foreach ($plugintypes as $plugintype => $pluginbasedir) {
+            if (substr($dirpath, 0, strlen($pluginbasedir)) == $pluginbasedir) {
+                return $plugintype;
+            }
+        }
+        return null;
+    }
 }
 
index dab9a42..5185b9b 100644 (file)
@@ -160,7 +160,7 @@ class external_service_functions_form extends moodleform {
             $functions[$functionid] = $function->name . ':' . $function->description;
         }
 
-        $mform->addElement('searchableselector', 'fid', get_string('name'),
+        $mform->addElement('searchableselector', 'fids', get_string('name'),
                 $functions, array('multiple'));
 
         $mform->addElement('hidden', 'id');
index d4f7da8..fc0e886 100644 (file)
@@ -67,7 +67,7 @@ switch ($action) {
             //add the function to the service then redirect to function list page
             if ($data = $mform->get_data()) {
                 ignore_user_abort(true); // no interruption here!
-                foreach ($data->fid as $fid) {
+                foreach ($data->fids as $fid) {
                     $function = $webservicemanager->get_external_function_by_id(
                             $fid, MUST_EXIST);
                     // make sure the function is not there yet
index 9d62218..12db2b0 100644 (file)
@@ -98,7 +98,7 @@ $usersmissingcaps = $webservicemanager->get_missing_capabilities_by_users($allow
 //add the missing capabilities to the allowed users object to be displayed by renderer
 foreach ($allowedusers as &$alloweduser) {
     if (!is_siteadmin($alloweduser->id) and key_exists($alloweduser->id, $usersmissingcaps)) {
-        $alloweduser->missingcapabilities = implode(',', $usersmissingcaps[$alloweduser->id]);
+        $alloweduser->missingcapabilities = implode(', ', $usersmissingcaps[$alloweduser->id]);
     }
 }
 
index 3f10939..30cca1e 100644 (file)
@@ -28,6 +28,9 @@ defined('MOODLE_INTERNAL') || die();
 /**
  * Validate comment parameter before perform other comments actions
  *
+ * @package  block_comments
+ * @category comment
+ *
  * @param stdClass $comment_param {
  *              context  => context the context object
  *              courseid => int course id
@@ -50,6 +53,9 @@ function block_comments_comment_validate($comment_param) {
 /**
  * Running addtional permission check on plugins
  *
+ * @package  block_comments
+ * @category comment
+ *
  * @param stdClass $args
  * @return array
  */
@@ -60,6 +66,9 @@ function block_comments_comment_permissions($args) {
 /**
  * Validate comment data before displaying comments
  *
+ * @package  block_comments
+ * @category comment
+ *
  * @param stdClass $comment
  * @param stdClass $args
  * @return boolean
index 5a92fb5..080df70 100644 (file)
@@ -1002,6 +1002,9 @@ function blog_get_associated_count($courseid, $cmid=null) {
  * Capability check has been done in comment->check_permissions(), we
  * don't need to do it again here.
  *
+ * @package  core_blog
+ * @category comment
+ *
  * @param stdClass $comment_param {
  *              context  => context the context object
  *              courseid => int course id
@@ -1018,6 +1021,9 @@ function blog_comment_permissions($comment_param) {
 /**
  * Validate comment parameter before perform other comments actions
  *
+ * @package  core_blog
+ * @category comment
+ *
  * @param stdClass $comment {
  *              context  => context the context object
  *              courseid => int course id
index 828d5c8..91b99ca 100644 (file)
 
 /*
  * Handling all ajax request for comments API
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 define('AJAX_SCRIPT', true);
 
index 4e852b4..b7a39a8 100644 (file)
 
 /*
  * Handling new comments from non-js comments interface
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 require_once('../config.php');
 require_once($CFG->dirroot . '/comment/lib.php');
index b9a2abd..ab5daa3 100644 (file)
 
 /*
  * Comments management interface
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 require_once('../config.php');
 require_once($CFG->libdir.'/adminlib.php');
index 99e92f9..171e619 100644 (file)
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Comment is helper class to add/delete comments anywhere in moodle
+ * Functions and classes for commenting
  *
- * @package   comment
- * @copyright 2010 Dongsheng Cai <dongsheng@moodle.com>
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
-
 defined('MOODLE_INTERNAL') || die();
 
+/**
+ * Comment is helper class to add/delete comments anywhere in moodle
+ *
+ * @package   core
+ * @category  comment
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class comment {
-    /**
-     * there may be several comment box in one page
-     * so we need a client_id to recognize them
-     * @var integer
-     */
+    /** @var int there may be several comment box in one page so we need a client_id to recognize them */
     private $cid;
-    /**
-     * commentarea is used to specify different
-     * parts shared the same itemid
-     * @var string
-     */
+    /** @var string commentarea is used to specify different parts shared the same itemid */
     private $commentarea;
-    /**
-     * itemid is used to associate with commenting content
-     * @var integer
-     */
+    /** @var int itemid is used to associate with commenting content */
     private $itemid;
-    /**
-     * this html snippet will be used as a template
-     * to build comment content
-     * @var string
-     */
+    /** @var string this html snippet will be used as a template to build comment content */
     private $template;
-    /**
-     * The context id for comments
-     * @var int
-     */
+    /** @var int The context id for comments */
     private $contextid;
-    /**
-     * The context itself
-     * @var stdClass
-     */
+    /** @var stdClass The context itself */
     private $context;
-    /**
-     * The course id for comments
-     * @var int
-     */
+    /** @var int The course id for comments */
     private $courseid;
-    /**
-     * course module object, only be used to help find pluginname automatically
-     * if pluginname is specified, it won't be used at all
-     * @var stdClass
-     */
+    /** @var stdClass course module object, only be used to help find pluginname automatically */
     private $cm;
-    /**
-     * The component that this comment is for. It is STRONGLY recommended to set this.
-     * @var string
-     */
+    /** @var string The component that this comment is for. It is STRONGLY recommended to set this. */
     private $component;
-    /**
-     * This is calculated by normalising the component
-     * @var string
-     */
+    /** @var string This is calculated by normalising the component */
     private $pluginname;
-    /**
-     * This is calculated by normalising the component
-     * @var string
-     */
+    /** @var string This is calculated by normalising the component */
     private $plugintype;
-    /**
-     * Whether the user has the required capabilities/permissions to view comments.
-     * @var bool
-     */
+    /** @var bool Whether the user has the required capabilities/permissions to view comments. */
     private $viewcap = false;
-    /**
-     * Whether the user has the required capabilities/permissions to post comments.
-     * @var bool
-     */
+    /** @var bool Whether the user has the required capabilities/permissions to post comments. */
     private $postcap = false;
-    /**
-     * to costomize link text
-     * @var string
-     */
+    /** @var string to customize link text */
     private $linktext;
-    /**
-     * If set to true then comment sections won't be able to be opened and closed
-     * instead they will always be visible.
-     * @var bool
-     */
+    /** @var bool If set to true then comment sections won't be able to be opened and closed instead they will always be visible. */
     protected $notoggle = false;
-    /**
-     * If set to true comments are automatically loaded as soon as the page loads.
-     * Normally this happens when the user expands the comment section.
-     * @var bool
-     */
+    /** @var bool If set to true comments are automatically loaded as soon as the page loads. */
     protected $autostart = false;
-    /**
-     * If set to true the total count of comments is displayed when displaying comments.
-     * @var bool
-     */
+    /** @var bool If set to true the total count of comments is displayed when displaying comments. */
     protected $displaytotalcount = false;
-    /**
-     * If set to true a cancel button will be shown on the form used to submit comments.
-     * @var bool
-     */
+    /** @var bool If set to true a cancel button will be shown on the form used to submit comments. */
     protected $displaycancel = false;
-    /**
-     * The number of comments associated with this comments params
-     * @var int
-     */
+    /** @var int The number of comments associated with this comments params */
     protected $totalcommentcount = null;
 
-    /**#@+
-     * static variable will be used by non-js comments UI
-     */
+    /** @var bool Use non-javascript UI */
     private static $nonjs = false;
+    /** @var int comment itemid used in non-javascript UI */
     private static $comment_itemid = null;
+    /** @var int comment context used in non-javascript UI */
     private static $comment_context = null;
+    /** @var string comment area used in non-javascript UI */
     private static $comment_area = null;
+    /** @var string comment page used in non-javascript UI */
     private static $comment_page = null;
+    /** @var string comment itemid component in non-javascript UI */
     private static $comment_component = null;
-    /**#@-*/
 
     /**
      * Construct function of comment class, initialise
      * class members
-     * @param stdClass $options
-     * @param object $options {
+     *
+     * @param stdClass $options {
      *            context => context context to use for the comment [required]
      *            component => string which plugin will comment being added to [required]
      *            itemid  => int the id of the associated item (forum post, glossary item etc) [required]
@@ -301,7 +247,6 @@ class comment {
      * A coding_error is now thrown if code attempts to change the component.
      *
      * @param string $component
-     * @return void
      */
     public function set_component($component) {
         if (!empty($this->component) && $this->component !== $component) {
@@ -443,7 +388,7 @@ class comment {
     /**
      * Prepare comment code in html
      * @param  boolean $return
-     * @return mixed
+     * @return string|void
      */
     public function output($return = true) {
         global $PAGE, $OUTPUT;
@@ -536,7 +481,7 @@ class comment {
      * Return matched comments
      *
      * @param  int $page
-     * @return mixed
+     * @return array
      */
     public function get_comments($page = '') {
         global $DB, $CFG, $USER, $OUTPUT;
@@ -646,7 +591,8 @@ class comment {
      *
      * @global moodle_database $DB
      * @param string $content
-     * @return mixed
+     * @param int $format
+     * @return stdClass
      */
     public function add($content, $format = FORMAT_MOODLE) {
         global $CFG, $DB, $USER, $OUTPUT;
@@ -721,7 +667,7 @@ class comment {
      * Delete a comment
      *
      * @param  int $commentid
-     * @return mixed
+     * @return bool
      */
     public function delete($commentid) {
         global $DB, $USER;
@@ -740,9 +686,9 @@ class comment {
      * Print comments
      *
      * @param int $page
-     * @param boolean $return return comments list string or print it out
-     * @param boolean $nonjs print nonjs comments list or not?
-     * @return mixed
+     * @param bool $return return comments list string or print it out
+     * @param bool $nonjs print nonjs comments list or not?
+     * @return string|void
      */
     public function print_comments($page = 0, $return = true, $nonjs = true) {
         global $DB, $CFG, $PAGE;
@@ -935,5 +881,12 @@ class comment {
     }
 }
 
+/**
+ * Comment exception class
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class comment_exception extends moodle_exception {
 }
index fd62b61..5a8b0d7 100644 (file)
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Functions and classes for comments management
+ *
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+defined('MOODLE_INTERNAL') || die();
+
 /**
  * comment_manager is helper class to manage moodle comments in admin page (Reports->Comments)
  *
- * @package   comment
- * @copyright  2010 Dongsheng Cai <dongsheng@moodle.com>
+ * @package   core
+ * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class comment_manager {
 
-    /**
-     * The number of comments to display per page
-     * @var int
-     */
+    /** @var int The number of comments to display per page */
     private $perpage;
 
     /**
@@ -85,7 +91,6 @@ class comment_manager {
      * @global moodle_page $PAGE
      * @global moodle_database $DB
      * @param int $courseid
-     * @return void
      */
     private function setup_course($courseid) {
         global $PAGE, $DB;
@@ -136,7 +141,7 @@ class comment_manager {
     /**
      * Print comments
      * @param int $page
-     * @return boolean return false if no comments available
+     * @return bool return false if no comments available
      */
     public function print_comments($page = 0) {
         global $OUTPUT, $CFG, $OUTPUT, $DB;
index 3e9898c..1e1d7ad 100644 (file)
@@ -92,8 +92,8 @@ class core_course_renderer extends plugin_renderer_base {
      */
     protected function course_category_tree_category(stdClass $category, $depth=1) {
         $content = '';
-        $hassubcategories = (count($category->categories)>0);
-        $hascourses = (count($category->courses)>0);
+        $hassubcategories = (isset($category->categories) && count($category->categories)>0);
+        $hascourses = (isset($category->courses) && count($category->courses)>0);
         $classes = array('category');
         if ($category->parent != 0) {
             $classes[] = 'subcategory';
index 4433d03..1e191a3 100644 (file)
@@ -42,6 +42,7 @@
     }
     $PAGE->set_url('/course/search.php', $urlparams);
     $PAGE->set_context(get_context_instance(CONTEXT_SYSTEM));
+    $PAGE->set_pagelayout('standard');
 
     if ($CFG->forcelogin) {
         require_login();
@@ -73,7 +74,8 @@
         }
     }
 
-    if (has_capability('moodle/course:create', get_context_instance(CONTEXT_SYSTEM)) && $perpage != 99999) {
+    $capabilities = array('moodle/course:create', 'moodle/category:manage');
+    if (has_any_capability($capabilities, get_context_instance(CONTEXT_SYSTEM)) && ($perpage != 99999)) {
         $perpage = 30;
     }
 
                     JOIN {block_instances} bi ON bi.parentcontextid = ctx.id
                     WHERE ctx.contextlevel = " . CONTEXT_COURSE . " AND bi.blockname = ?)",
                 array($blockname));
+        $totalcount = count($courses);
+        //Keep only chunk of array which you want to display
+        if ($totalcount > $perpage) {
+            $courses = array_chunk($courses, $perpage, true);
+            $courses = $courses[$page];
+        }
         foreach ($courses as $course) {
             $courses[$course->id] = $course;
         }
-        $totalcount = count($courses);
     }
     // get list of courses containing modules if required
     elseif (!empty($modulelist) and confirm_sesskey()) {
             if ($PAGE->user_is_editing()) {
                 $string = get_string("turneditingoff");
                 $edit = "off";
-                $perpage = 30;
             } else {
                 $string = get_string("turneditingon");
                 $edit = "on";
         echo $OUTPUT->heading("$strsearchresults: $totalcount");
         $encodedsearch = urlencode($search);
 
-     ///add the module parameter to the paging bar if they exists
+        // add the module/block parameter to the paging bar if they exists
         $modulelink = "";
         if (!empty($modulelist) and confirm_sesskey()) {
             $modulelink = "&amp;modulelist=".$modulelist."&amp;sesskey=".sesskey();
+        } else if (!empty($blocklist) and confirm_sesskey()) {
+            $modulelink = "&amp;blocklist=".$blocklist."&amp;sesskey=".sesskey();
         }
 
         print_navigation_bar($totalcount, $page, $perpage, $encodedsearch, $modulelink);
             echo "<center><p>";
             echo "<a href=\"search.php?search=$encodedsearch".$modulelink."&amp;perpage=99999\">".get_string("showall", "", $totalcount)."</a>";
             echo "</p></center>";
+        } else if ($perpage === 99999) {
+            $defaultperpage = 10;
+            //If user has course:create or category:manage capability the show 30 records.
+            $capabilities = array('moodle/course:create', 'moodle/category:manage');
+            if (has_any_capability($capabilities, get_context_instance(CONTEXT_SYSTEM))) {
+                $defaultperpage = 30;
+            }
+
+            echo "<center><p>";
+            echo "<a href=\"search.php?search=$encodedsearch".$modulelink."&amp;perpage=".$defaultperpage."\">".get_string("showperpage", "", $defaultperpage)."</a>";
+            echo "</p></center>";
         }
     }
 
index d18e55a..8c24b96 100644 (file)
@@ -28,7 +28,7 @@ defined('MOODLE_INTERNAL') || die();
 
 $capabilities = array(
     // marks roles that have category role assignments synchronised to course enrolments
-    // overrides bellow system context are ignored (for performance reasons).
+    // overrides below system context are ignored (for performance reasons).
     // by default his is not allowed in new installs, admins have to explicitly allow category enrolments
     'enrol/category:synchronised' => array(
         'captype' => 'write',
index 60ca85f..451c1d9 100644 (file)
@@ -71,7 +71,7 @@ class filter_data extends moodle_text_filter {
                       JOIN {data_content} dc ON dc.fieldid = df.id AND dc.recordid = dr.id
                      WHERE d.course ' . $coursesql . '
                        AND df.type = \'text\'
-                       AND ' . $DB->sql_compare_text('df.param1', 1) . ' = 1';
+                       AND ' . $DB->sql_compare_text('df.param1', 1) . " = '1'";
 
             if (!$contents = $DB->get_records_sql($sql, $params)) {
                 $nothingtodo = true;
index e1e61ca..cb4a751 100644 (file)
@@ -74,7 +74,7 @@ class filter_mediaplugin extends moodle_text_filter {
             return $text;
         }
         if (stripos($text, '</a>') === false) {
-            // performance shortcut - all regexes bellow end with the </a> tag,
+            // performance shortcut - all regexes below end with the </a> tag,
             // if not present nothing can match
             return $text;
         }
@@ -281,7 +281,7 @@ function filter_mediaplugin_html5audio_callback(array $link) {
         $sources[] = html_writer::tag('source', '', array('src' => $url, 'type' => $mimetype));
 
         if ($fallbacklink === null) {
-            $fallbacklink = html_writer::link($url.'#', $info); // the extra '#' prevents linking in mp3 filter bellow
+            $fallbacklink = html_writer::link($url.'#', $info); // the extra '#' prevents linking in mp3 filter below
         }
         if ($fallbackurl === null) {
             if ($mimetype === 'audio/mp3' or $mimetype === 'audio/aac') {
@@ -379,7 +379,7 @@ function filter_mediaplugin_html5video_callback(array $link) {
         }
 
         if ($fallbacklink === null) {
-            $fallbacklink = html_writer::link($url.'#', $info); // the extra '#' prevents linking in mp3 filter bellow
+            $fallbacklink = html_writer::link($url.'#', $info); // the extra '#' prevents linking in mp3 filter below
         }
         if ($fallbackurl === null) {
             if ($mimetype === 'video/mp4') {
index 540694c..bd6e396 100644 (file)
@@ -115,7 +115,14 @@ class grade_export_form extends moodleform {
 
         if ($grade_items = $gseq->items) {
             $needs_multiselect = false;
+            $canviewhidden = has_capability('moodle/grade:viewhidden', get_context_instance(CONTEXT_COURSE, $COURSE->id));
+
             foreach ($grade_items as $grade_item) {
+                // Is the grade_item hidden? If so, can the user see hidden grade_items?
+                if ($grade_item->is_hidden() && !$canviewhidden) {
+                    continue;
+                }
+
                 if (!empty($features['idnumberrequired']) and empty($grade_item->idnumber)) {
                     $mform->addElement('advcheckbox', 'itemids['.$grade_item->id.']', $grade_item->get_name(), get_string('noidnumber', 'grades'));
                     $mform->hardFreeze('itemids['.$grade_item->id.']');
@@ -124,7 +131,7 @@ class grade_export_form extends moodleform {
                     $mform->setDefault('itemids['.$grade_item->id.']', 1);
                     $needs_multiselect = true;
                 }
-                }
+            }
 
             if ($needs_multiselect) {
                 $this->add_checkbox_controller(1, null, null, 1); // 1st argument is group name, 2nd is link text, 3rd is attributes and 4th is original value
index 3634d37..5a27b8f 100644 (file)
@@ -202,6 +202,19 @@ abstract class gradingform_controller {
         // do not extend by default
     }
 
+    /**
+     * Extends the module navigation
+     *
+     * This function is called when the context for the page is an activity module with the
+     * FEATURE_ADVANCED_GRADING and there is an area with the active grading method set to the given plugin.
+     *
+     * @param global_navigation $navigation {@link global_navigation}
+     * @param navigation_node $node {@link navigation_node}
+     */
+    public function extend_navigation(global_navigation $navigation, navigation_node $node=null) {
+        // do not extend by default
+    }
+
     /**
      * Returns the grading form definition structure
      *
index d7f605c..527e8fb 100644 (file)
@@ -25,6 +25,7 @@
 defined('MOODLE_INTERNAL') || die();
 
 $string['addcriterion'] = 'Add criterion';
+$string['alwaysshowdefinition'] = 'Allow users to preview rubric used in the module (otherwise rubric will only become visible after grading)';
 $string['backtoediting'] = 'Back to editing';
 $string['confirmdeletecriterion'] = 'Are you sure you want to delete this criterion?';
 $string['confirmdeletelevel'] = 'Are you sure you want to delete this level?';
@@ -42,11 +43,13 @@ $string['err_nodefinition'] = 'Level definition can not be empty';
 $string['err_nodescription'] = 'Criterion description can not be empty';
 $string['err_scoreformat'] = 'Number of points for each level must be a valid non-negative number';
 $string['err_totalscore'] = 'Maximum number of points possible when graded by the rubric must be more than zero';
+$string['gradingof'] = '{$a} grading';
 $string['leveldelete'] = 'Delete level';
 $string['levelempty'] = 'Click to edit level';
 $string['name'] = 'Name';
 $string['needregrademessage'] = 'The rubric definition was changed after this student had been graded. The student can not see this rubric until you check the rubric and update the grade.';
 $string['pluginname'] = 'Rubric';
+$string['previewrubric'] = 'Preview rubric';
 $string['regrademessage1'] = 'You are about to save changes to a rubric that has already been used for grading. Please indicate if existing grades need to be reviewed. If you set this then the rubric will be hidden from students until their item is regraded.';
 $string['regrademessage5'] = 'You are about to save significant changes to a rubric that has already been used for grading. The gradebook value will be unchanged, but the rubric will be hidden from students until their item is regraded.';
 $string['regradeoption0'] = 'Do not mark for regrade';
index ff24e85..98aeaf9 100644 (file)
@@ -37,8 +37,10 @@ class gradingform_rubric_controller extends gradingform_controller {
     const DISPLAY_EDIT_FULL     = 1;
     /** Rubric display mode: Preview the rubric design with hidden fields */
     const DISPLAY_EDIT_FROZEN   = 2;
-    /** Rubric display mode: Preview the rubric design */
+    /** Rubric display mode: Preview the rubric design (for person with manage permission) */
     const DISPLAY_PREVIEW       = 3;
+    /** Rubric display mode: Preview the rubric (for people being graded) */
+    const DISPLAY_PREVIEW_GRADED= 8;
     /** Rubric display mode: For evaluation, enabled (teacher grades a student) */
     const DISPLAY_EVAL          = 4;
     /** Rubric display mode: For evaluation, with hidden fields */
@@ -64,6 +66,27 @@ class gradingform_rubric_controller extends gradingform_controller {
             null, null, new pix_icon('icon', '', 'gradingform_rubric'));
     }
 
+    /**
+     * Extends the module navigation
+     *
+     * This function is called when the context for the page is an activity module with the
+     * FEATURE_ADVANCED_GRADING and there is an area with the active grading method set to the given plugin.
+     *
+     * @param global_navigation $navigation {@link global_navigation}
+     * @param navigation_node $node {@link navigation_node}
+     */
+    public function extend_navigation(global_navigation $navigation, navigation_node $node=null) {
+        if (has_capability('moodle/grade:managegradingforms', $this->get_context())) {
+            // no need for preview if user can manage forms, he will have link to manage.php in settings instead
+            return;
+        }
+        if ($this->is_form_defined() && ($options = $this->get_options()) && !empty($options['alwaysshowdefinition'])) {
+            $node->add(get_string('gradingof', 'gradingform_rubric', get_grading_manager($this->get_areaid())->get_area_title()),
+                    new moodle_url('/grade/grading/form/'.$this->get_method_name().'/preview.php', array('areaid' => $this->get_areaid())),
+                    settings_navigation::TYPE_CUSTOM);
+        }
+    }
+
     /**
      * Saves the rubric definition into the database
      *
@@ -330,14 +353,14 @@ class gradingform_rubric_controller extends gradingform_controller {
     public static function get_default_options() {
         $options = array(
             'sortlevelsasc' => 1,
-            //'showdescriptionteacher' => 1,
-            //'showdescriptionstudent' => 1,
+            'alwaysshowdefinition' => 1,
+            'showdescriptionteacher' => 1,
+            'showdescriptionstudent' => 1,
             'showscoreteacher' => 1,
             'showscorestudent' => 1,
             'enableremarks' => 1,
             'showremarksstudent' => 1
         );
-        // TODO description options
         return $options;
     }
 
@@ -484,8 +507,13 @@ class gradingform_rubric_controller extends gradingform_controller {
         $output = $this->get_renderer($page);
         $criteria = $this->definition->rubric_criteria;
         $options = $this->get_options();
-        $rubric = $output->display_rubric_mapping_explained($this->get_min_max_score());
-        $rubric .= $output->display_rubric($criteria, $options, self::DISPLAY_PREVIEW, 'rubric');
+        $rubric = '';
+        if (has_capability('moodle/grade:managegradingforms', $page->context)) {
+            $rubric .= $output->display_rubric_mapping_explained($this->get_min_max_score());
+            $rubric .= $output->display_rubric($criteria, $options, self::DISPLAY_PREVIEW, 'rubric');
+        } else {
+            $rubric .= $output->display_rubric($criteria, $options, self::DISPLAY_PREVIEW_GRADED, 'rubric');
+        }
 
         return $rubric;
     }
@@ -812,6 +840,9 @@ class gradingform_rubric_instance extends gradingform_instance {
         if ($this->get_data('isrestored') && $haschanges) {
             $html .= html_writer::tag('div', get_string('restoredfromdraft', 'gradingform_rubric'), array('class' => 'gradingform_rubric-restored'));
         }
+        if (!empty($options['showdescriptionteacher'])) {
+            $html .= html_writer::tag('div', $this->get_controller()->get_formatted_description(), array('class' => 'gradingform_rubric-description'));
+        }
         $html .= $this->get_controller()->get_renderer($page)->display_rubric($criteria, $options, $mode, $gradingformelement->getName(), $value);
         return $html;
     }
diff --git a/grade/grading/form/rubric/preview.php b/grade/grading/form/rubric/preview.php
new file mode 100644 (file)
index 0000000..1a71458
--- /dev/null
@@ -0,0 +1,56 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Preview rubric page
+ *
+ * @package    gradingform_rubric
+ * @copyright  2011 Marina Glancy
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+require_once(dirname(dirname(dirname(dirname(dirname(__FILE__))))).'/config.php');
+require_once(dirname(__FILE__).'/lib.php');
+require_once(dirname(__FILE__).'/edit_form.php');
+require_once($CFG->dirroot.'/grade/grading/lib.php');
+
+$areaid = required_param('areaid', PARAM_INT);
+
+$manager = get_grading_manager($areaid);
+
+list($context, $course, $cm) = get_context_info_array($manager->get_context()->id);
+
+require_login($course, true, $cm);
+
+$controller = $manager->get_controller('rubric');
+$options = $controller->get_options();
+
+if (!$controller->is_form_defined() || empty($options['alwaysshowdefinition'])) {
+    throw new moodle_exception('nopermissions', 'error', '', get_string('previewrubric', 'gradingform_rubric'));
+}
+
+$title = get_string('gradingof', 'gradingform_rubric', $manager->get_area_title());
+$PAGE->set_url(new moodle_url('/grade/grading/form/rubric/preview.php', array('areaid' => $areaid)));
+$PAGE->set_title($title);
+$PAGE->set_heading($title);
+
+echo $OUTPUT->header();
+echo $OUTPUT->heading($title);
+if (!empty($options['showdescriptionstudent'])) {
+    echo $OUTPUT->box($controller->get_formatted_description(), 'gradingform_rubric-description');
+}
+echo $controller->render_preview($PAGE);
+echo $OUTPUT->footer();
index f037263..9469e94 100644 (file)
@@ -191,7 +191,7 @@ class gradingform_rubric_renderer extends plugin_renderer_base {
         if (!$options['showscoreteacher'] && in_array($mode, array(gradingform_rubric_controller::DISPLAY_EVAL, gradingform_rubric_controller::DISPLAY_EVAL_FROZEN, gradingform_rubric_controller::DISPLAY_REVIEW))) {
             $displayscore = false;
         }
-        if (!$options['showscorestudent'] && $mode == gradingform_rubric_controller::DISPLAY_VIEW) {
+        if (!$options['showscorestudent'] && in_array($mode, array(gradingform_rubric_controller::DISPLAY_VIEW, gradingform_rubric_controller::DISPLAY_PREVIEW_GRADED))) {
             $displayscore = false;
         }
         if ($displayscore) {
@@ -241,6 +241,7 @@ class gradingform_rubric_renderer extends plugin_renderer_base {
             case gradingform_rubric_controller::DISPLAY_EDIT_FROZEN:
                 $classsuffix = ' editor frozen';  break;
             case gradingform_rubric_controller::DISPLAY_PREVIEW:
+            case gradingform_rubric_controller::DISPLAY_PREVIEW_GRADED:
                 $classsuffix = ' editor preview';  break;
             case gradingform_rubric_controller::DISPLAY_EVAL:
                 $classsuffix = ' evaluate editable'; break;
@@ -277,7 +278,7 @@ class gradingform_rubric_renderer extends plugin_renderer_base {
         if ($mode != gradingform_rubric_controller::DISPLAY_EDIT_FULL
                 && $mode != gradingform_rubric_controller::DISPLAY_EDIT_FROZEN
                 && $mode != gradingform_rubric_controller::DISPLAY_PREVIEW) {
-            // Options are displayed only in edit mode
+            // Options are displayed only for people who can manage
             return;
         }
         $html = html_writer::start_tag('div', array('class' => 'options'));
@@ -431,10 +432,17 @@ class gradingform_rubric_renderer extends plugin_renderer_base {
         $values = $instance->get_rubric_filling();
         if ($cangrade) {
             $mode = gradingform_rubric_controller::DISPLAY_REVIEW;
+            $showdescription = $options['showdescriptionteacher'];
         } else {
             $mode = gradingform_rubric_controller::DISPLAY_VIEW;
+            $showdescription = $options['showdescriptionstudent'];
         }
-        return $this->display_rubric($criteria, $options, $mode, 'rubric'.$idx, $values);
+        $output = '';
+        if ($showdescription) {
+            $output .= $this->box($instance->get_controller()->get_formatted_description(), 'gradingform_rubric-description');
+        }
+        $output .= $this->display_rubric($criteria, $options, $mode, 'rubric'.$idx, $values);
+        return $output;
     }
 
     public function display_regrade_confirmation($elementname, $changelevel, $value) {
index e27a4ec..c6e8186 100644 (file)
@@ -454,6 +454,27 @@ class grading_manager {
         }
     }
 
+    /**
+     * Extends the module navigation with the advanced grading information
+     *
+     * This function is called when the context for the page is an activity module with the
+     * FEATURE_ADVANCED_GRADING.
+     *
+     * @param global_navigation $navigation
+     * @param navigation_node $modulenode
+     */
+    public function extend_navigation(global_navigation $navigation, navigation_node $modulenode=null) {
+        $this->ensure_isset(array('context', 'component'));
+
+        $areas = $this->get_available_areas();
+        foreach ($areas as $areaname => $areatitle) {
+            $this->set_area($areaname);
+            if ($controller = $this->get_active_controller()) {
+                $controller->extend_navigation($navigation, $modulenode);
+            }
+        }
+    }
+
     /**
      * Returns the given method's controller in the gradable area
      *
index bcacf6d..7c9fb38 100644 (file)
@@ -163,7 +163,7 @@ class grade_report_grader extends grade_report {
             $separategroups = true;
             $mygroups = groups_get_user_groups($this->course->id);
             $mygroups = $mygroups[0]; // ignore groupings
-            // reorder the groups fro better perf bellow
+            // reorder the groups fro better perf below
             $current = array_search($this->currentgroup, $mygroups);
             if ($current !== false) {
                 unset($mygroups[$current]);
diff --git a/install/lang/rm_surs/moodle.php b/install/lang/rm_surs/moodle.php
new file mode 100644 (file)
index 0000000..698cf50
--- /dev/null
@@ -0,0 +1,36 @@
+<?php
+
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Automatically generated strings for Moodle 2.3dev installer
+ *
+ * Do not edit this file manually! It contains just a subset of strings
+ * needed during the very first steps of installation. This file was
+ * generated automatically by export-installer.php (which is part of AMOS
+ * {@link http://docs.moodle.org/dev/Languages/AMOS}) using the
+ * list of strings defined in /install/stringnames.txt.
+ *
+ * @package   installer
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+$string['language'] = 'Lungatg';
+$string['next'] = 'Proxim';
+$string['previous'] = 'Precedent';
+$string['reload'] = 'Cargar aunc ina gada';
index 31767ca..54ba3ab 100644 (file)
@@ -30,5 +30,9 @@
 
 defined('MOODLE_INTERNAL') || die();
 
+$string['clianswerno'] = 'n';
+$string['cliansweryes'] = 'y';
+$string['cliincorrectvalueerror'] = 'Lỗi, giá trị không đúng "{$a->value}" for "{$a->option}"';
+$string['cliincorrectvalueretry'] = 'Giá trị không đúng, vui lòng thử lại';
 $string['environmentrequireinstall'] = 'cần phải được cài hay kích hoạt.';
 $string['environmentrequireversion'] = 'Cần phiên bản {$a->needed} trong khi bạn đang dùng {$a->current}';
index b42376e..fbd8c9d 100644 (file)
@@ -55,7 +55,7 @@ $string['security'] = 'Security';
 $string['selectallornone'] = 'Select all/none';
 $string['selected'] = 'Selected';
 $string['showadvanced'] = 'Show advanced';
-$string['somefieldsrequired'] = 'There are required fields in this form marked{$a}.';
+$string['somefieldsrequired'] = 'There are required fields in this form marked {$a}.';
 $string['time'] = 'Time';
 $string['timeunit'] = 'Time unit';
 $string['timing'] = 'Timing';
index 4da2ea8..7905f66 100644 (file)
@@ -39,16 +39,16 @@ $string['parentlanguage'] = '';
 $string['strftimedate'] = '%d %B %Y';
 $string['strftimedatefullshort'] = '%d/%m/%y';
 $string['strftimedateshort'] = '%d %B';
-$string['strftimedatetime'] = '%d %B %Y, %l:%M %p';
+$string['strftimedatetime'] = '%d %B %Y, %I:%M %p';
 $string['strftimedatetimeshort'] = '%d/%m/%y, %H:%M';
 $string['strftimedaydate'] = '%A, %d %B %Y';
-$string['strftimedaydatetime'] = '%A, %d %B %Y, %l:%M %p';
+$string['strftimedaydatetime'] = '%A, %d %B %Y, %I:%M %p';
 $string['strftimedayshort'] = '%A, %d %B';
 $string['strftimedaytime'] = '%a, %H:%M';
 $string['strftimemonthyear'] = '%B %Y';
 $string['strftimerecent'] = '%d %b, %H:%M';
-$string['strftimerecentfull'] = '%a, %d %b %Y, %l:%M %p';
-$string['strftimetime'] = '%l:%M %p';
+$string['strftimerecentfull'] = '%a, %d %b %Y, %I:%M %p';
+$string['strftimetime'] = '%I:%M %p';
 $string['thisdirection'] = 'ltr';
 $string['thisdirectionvertical'] = 'btt';
 $string['thislanguage'] = 'English';
index 0286c52..f9371e3 100644 (file)
@@ -219,6 +219,7 @@ $string['categoryname'] = 'Category name';
 $string['idnumbercoursecategory'] = 'Category ID number';
 $string['idnumbercoursecategory_help'] = 'The ID number of a course category  is only used when matching the category against external systems and is not displayed anywhere on the site. If the category has an official code name it may be entered, otherwise the field can be left blank.';
 $string['categoryupdated'] = 'The category \'{$a}\' was updated';
+$string['changesmadereallygoaway'] = 'You have made changes. Are you sure you want to navigate away and lose your changes?';
 $string['city'] = 'City/town';
 $string['clambroken'] = 'Your administrator has enabled virus checking for file uploads but has misconfigured something.<br />Your file upload was NOT successful. Your administrator has been emailed to notify them so they can fix it.<br />Maybe try uploading this file later.';
 $string['clamdeletedfile'] = 'The file has been deleted';
@@ -463,6 +464,7 @@ $string['downloadfile'] = 'Download file';
 $string['downloadods'] = 'Download in ODS format';
 $string['downloadtext'] = 'Download in text format';
 $string['doyouagree'] = 'Have you read these conditions and understood them?';
+$string['droptoupload'] = 'Drop files here to upload';
 $string['duplicate'] = 'Duplicate';
 $string['duplicateconfirm'] = 'Are you sure you want to duplicate {$a->modtype} \'{$a->modname}\' ?';
 $string['duplicatecontcourse'] = 'Return to the course';
@@ -968,6 +970,7 @@ $string['manageroles'] = 'Roles and permissions';
 $string['markedthistopic'] = 'This topic is highlighted as the current topic';
 $string['markthistopic'] = 'Highlight this topic as the current topic';
 $string['matchingsearchandrole'] = 'Matching \'{$a->search}\' and {$a->role}';
+$string['maxfilesreached'] = 'You are allowed to attach a maximum of {$a} file(s) to this item';
 $string['maximumgrade'] = 'Maximum grade';
 $string['maximumgradex'] = 'Maximum grade: {$a}';
 $string['maximumchars'] = 'Maximum of {$a} characters';
@@ -1772,9 +1775,7 @@ $string['withoutuserdata'] = 'without user data';
 $string['withselectedusers'] = 'With selected users...';
 $string['withselectedusers_help'] = '* Send message - For sending a message to one or more participants
 * Add a new note - For adding a note to a selected participant
-* Add a common note - For adding the same note to more than one participant
-* Extend enrolment (individual) - For extending a selected student\'s access to the course, even when an enrolment period is set
-* Extend enrolment (common) - For extending more than one student\'s access to the course by the same amount';
+* Add a common note - For adding the same note to more than one participant';
 $string['withuserdata'] = 'with user data';
 $string['wordforstudent'] = 'Your word for Student';
 $string['wordforstudenteg'] = 'eg Student, Participant etc';
index 9ca574d..29aac48 100644 (file)
@@ -7208,7 +7208,7 @@ function get_role_context_caps($roleid, context $context) {
         }
     }
 
-    // now go through the contexts bellow given context
+    // now go through the contexts below given context
     $searchcontexts = array_keys($context->get_child_contexts());
     foreach ($searchcontexts as $cid) {
         if ($capabilities = $DB->get_records('role_capabilities', array('roleid'=>$roleid, 'contextid'=>$cid))) {
index 72d6df3..4025f91 100644 (file)
@@ -7575,7 +7575,7 @@ class admin_setting_managewebservicetokens extends admin_setting {
 
                 if (!is_siteadmin($token->userid) and
                         key_exists($token->userid, $usermissingcaps)) {
-                    $missingcapabilities = implode(',',
+                    $missingcapabilities = implode(', ',
                             $usermissingcaps[$token->userid]);
                     if (!empty($missingcapabilities)) {
                         $useratag .= html_writer::tag('div',
index 9bd66a2..dfe1717 100644 (file)
@@ -53,7 +53,7 @@ class completion_criteria_date extends completion_criteria {
     public function config_form_display(&$mform, $data = null)
     {
         $mform->addElement('checkbox', 'criteria_date', get_string('enable'));
-        $mform->addElement('date', 'criteria_date_value', get_string('afterspecifieddate', 'completion'));
+        $mform->addElement('date_selector', 'criteria_date_value', get_string('afterspecifieddate', 'completion'));
 
         // If instance of criteria exists
         if ($this->id) {
@@ -74,8 +74,7 @@ class completion_criteria_date extends completion_criteria {
 
         if (!empty($data->criteria_date)) {
             $this->course = $data->id;
-            $date = $data->criteria_date_value;
-            $this->timeend = strtotime($date['Y'].'-'.$date['M'].'-'.$date['d']);
+            $this->timeend = $data->criteria_date_value;
             $this->insert();
         }
     }
index 7cc195e..9a8d62f 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -23,7 +22,6 @@
  * - moodlelib.php - general-purpose Moodle functions
  *
  * @package    core
- * @subpackage lib
  * @copyright  1999 onwards Martin Dougiamas  {@link http://moodle.com}
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -1649,14 +1647,16 @@ function coursemodule_visible_for_user($cm, $userid=0) {
  * than web server hits, and provide a way to easily reconstruct what
  * any particular student has been doing.
  *
- * @global object
- * @global object
- * @global object
+ * @package core
+ * @category log
+ * @global moodle_database $DB
+ * @global stdClass $CFG
+ * @global stdClass $USER
  * @uses SITEID
  * @uses DEBUG_DEVELOPER
  * @uses DEBUG_ALL
  * @param    int     $courseid  The course id
- * @param    string  $module  The module name - e.g. forum, journal, resource, course, user etc
+ * @param    string  $module  The module name  e.g. forum, journal, resource, course, user etc
  * @param    string  $action  'view', 'update', 'add' or 'delete', possibly followed by another word to clarify.
  * @param    string  $url     The file and parameters used to see the results of the action
  * @param    string  $info    Additional description information
@@ -1723,7 +1723,8 @@ function add_to_log($courseid, $module, $action, $url='', $info='', $cm=0, $user
     try {
         $DB->insert_record_raw('log', $log, false);
     } catch (dml_exception $e) {
-        debugging('Error: Could not insert a new entry to the Moodle log', DEBUG_ALL);
+        debugging('Error: Could not insert a new entry to the Moodle log. '. $e->error, DEBUG_ALL);
+
         // MDL-11893, alert $CFG->supportemail if insert into log failed
         if ($CFG->supportemail and empty($CFG->noemailever)) {
             // email_to_user is not usable because email_to_user tries to write to the logs table,
@@ -1746,12 +1747,14 @@ function add_to_log($courseid, $module, $action, $url='', $info='', $cm=0, $user
 /**
  * Store user last access times - called when use enters a course or site
  *
- * @global object
- * @global object
- * @global object
+ * @package core
+ * @category log
+ * @global stdClass $USER
+ * @global stdClass $CFG
+ * @global moodle_database $DB
  * @uses LASTACCESS_UPDATE_SECS
  * @uses SITEID
- * @param int $courseid, empty means site
+ * @param int $courseid  empty courseid means site
  * @return void
  */
 function user_accesstime_log($courseid=0) {
@@ -1816,16 +1819,16 @@ function user_accesstime_log($courseid=0) {
 /**
  * Select all log records based on SQL criteria
  *
- * @todo Finish documenting this function
- *
- * @global object
+ * @package core
+ * @category log
+ * @global moodle_database $DB
  * @param string $select SQL select criteria
  * @param array $params named sql type params
  * @param string $order SQL order by clause to sort the records returned
- * @param string $limitfrom ?
- * @param int $limitnum ?
+ * @param string $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set)
+ * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set)
  * @param int $totalcount Passed in by reference.
- * @return object
+ * @return array
  */
 function get_logs($select, array $params=null, $order='l.time DESC', $limitfrom='', $limitnum='', &$totalcount) {
     global $DB;
@@ -1860,13 +1863,14 @@ function get_logs($select, array $params=null, $order='l.time DESC', $limitfrom=
 /**
  * Select all log records for a given course and user
  *
- * @todo Finish documenting this function
- *
- * @global object
+ * @package core
+ * @category log
+ * @global moodle_database $DB
  * @uses DAYSECS
  * @param int $userid The id of the user as found in the 'user' table.
  * @param int $courseid The id of the course as found in the 'course' table.
- * @param string $coursestart ?
+ * @param string $coursestart unix timestamp representing course start date and time.
+ * @return array
  */
 function get_logs_usercourse($userid, $courseid, $coursestart) {
     global $DB;
@@ -1891,12 +1895,14 @@ function get_logs_usercourse($userid, $courseid, $coursestart) {
 /**
  * Select all log records for a given course, user, and day
  *
- * @global object
+ * @package core
+ * @category log
+ * @global moodle_database $DB
  * @uses HOURSECS
  * @param int $userid The id of the user as found in the 'user' table.
  * @param int $courseid The id of the course as found in the 'course' table.
- * @param string $daystart ?
- * @return object
+ * @param string $daystart unix timestamp of the start of the day for which the logs needs to be retrived
+ * @return array
  */
 function get_logs_userday($userid, $courseid, $daystart) {
     global $DB;
@@ -1925,7 +1931,7 @@ function get_logs_userday($userid, $courseid, $daystart) {
  * number of accounts.  For non-admins, only the attempts on the given user
  * are shown.
  *
- * @global object
+ * @global moodle_database $DB
  * @uses CONTEXT_SYSTEM
  * @param string $mode Either 'admin' or 'everybody'
  * @param string $username The username we are searching for
index 06652de..0aa4122 100644 (file)
@@ -145,7 +145,7 @@ function xmldb_main_upgrade($oldversion) {
         upgrade_main_savepoint(true, 2012020200.06);
     }
 
-    if ($oldversion < 2012021300.01) {
+    if ($oldversion < 2012021700.01) {
         // Changing precision of field uniquehash on table post to 255
         $table = new xmldb_table('post');
         $field = new xmldb_field('uniquehash', XMLDB_TYPE_CHAR, '255', null, XMLDB_NOTNULL, null, null, 'content');
@@ -154,7 +154,7 @@ function xmldb_main_upgrade($oldversion) {
         $dbman->change_field_precision($table, $field);
 
         // Main savepoint reached
-        upgrade_main_savepoint(true, 2012021300.01);
+        upgrade_main_savepoint(true, 2012021700.01);
     }
 
     return true;
index 13036c9..476b9e1 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
 
 
 /**
- * Database manager instance is responsible for all database structure
- * modifications.
+ * Database manager instance is responsible for all database structure modifications.
  *
  * @package    core
+ * @category   ddl
  * @subpackage ddl
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
 defined('MOODLE_INTERNAL') || die();
 
 /**
- * Database manager instance is responsible for all database structure
- * modifications. It is using db specific generators to find out
- * the correct SQL syntax to do that.
+ * Database manager instance is responsible for all database structure modifications.
+ *
+ * It is using db specific generators to find out the correct SQL syntax to do that.
+ *
+ * @package    core
+ * @category   ddl
+ * @subpackage ddl
+ * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
+ *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
+ *             2008 Petr Skoda                   http://skodak.org
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class database_manager {
 
+    /** @var moodle_database A moodle_database driver speific instance.*/
     protected $mdb;
-    public $generator; // public because XMLDB editor needs to access it
+    /** @var sql_generator A driver specific SQL generator instance. Public because XMLDB editor needs to access it.*/
+    public $generator;
 
     /**
-     * Creates new database manager
-     * @param object moodle_database instance
+     * Creates a new database manager instance.
+     * @param moodle_database $mdb A moodle_database driver specific instance.
+     * @param sql_generator $generator A driver specific SQL generator instance.
      */
     public function __construct($mdb, $generator) {
         global $CFG;
@@ -52,7 +62,7 @@ class database_manager {
     }
 
     /**
-     * Release all resources
+     * Releases all resources
      */
     public function dispose() {
         if ($this->generator) {
@@ -65,10 +75,8 @@ class database_manager {
     /**
      * This function will execute an array of SQL commands.
      *
-     * @exception ddl_exception if error found
-     *
-     * @param array $sqlarr array of sql statements to execute
-     * @return void
+     * @param array $sqlarr Array of sql statements to execute.
+     * @throws ddl_exception This exception is thrown if any error is found.
      */
     protected function execute_sql_arr(array $sqlarr) {
         foreach ($sqlarr as $sql) {
@@ -77,12 +85,10 @@ class database_manager {
     }
 
     /**
-     * Execute a given sql command string
-     *
-     * @exception ddl_exception if error found
+     * Execute a given sql command string.
      *
-     * @param string $command The sql string you wish to be executed.
-     * @return void
+     * @param string $sql The sql string you wish to be executed.
+     * @throws ddl_exception This exception is thrown if any error is found.
      */
     protected function execute_sql($sql) {
         if (!$this->mdb->change_database_structure($sql)) {
@@ -92,10 +98,10 @@ class database_manager {
     }
 
     /**
-     * Given one xmldb_table, check if it exists in DB (true/false)
+     * Given one xmldb_table, check if it exists in DB (true/false).
      *
-     * @param mixed the table to be searched (string name or xmldb_table instance)
-     * @return boolean true/false
+     * @param mixed $table The table to be searched (string name or xmldb_table instance).
+     * @return bool true/false True is a table exists, false otherwise.
      */
     public function table_exists($table) {
         if (!is_string($table) and !($table instanceof xmldb_table)) {
@@ -106,8 +112,8 @@ class database_manager {
 
     /**
      * Reset a sequence to the id field of a table.
-     * @param string $table name of table
-     * @return success
+     * @param string $table Name of table.
+     * @throws ddl_exception|ddl_table_missing_exception Exception thrown upon reset errors.
      */
     public function reset_sequence($table) {
         if (!is_string($table) and !($table instanceof xmldb_table)) {
@@ -127,11 +133,12 @@ class database_manager {
     }
 
     /**
-     * Given one xmldb_field, check if it exists in DB (true/false)
+     * Given one xmldb_field, check if it exists in DB (true/false).
      *
-     * @param mixed the table to be searched (string name or xmldb_table instance)
-     * @param mixed the field to be searched for (string name or xmldb_field instance)
-     * @return boolean true/false
+     * @param mixed $table The table to be searched (string name or xmldb_table instance).
+     * @param mixed $field The field to be searched for (string name or xmldb_field instance).
+     * @return boolean true is exists false otherwise.
+     * @throws ddl_table_missing_exception
      */
     public function field_exists($table, $field) {
     /// Calculate the name of the table
@@ -165,9 +172,10 @@ class database_manager {
      * Given one xmldb_index, the function returns the name of the index in DB
      * of false if it doesn't exist
      *
-     * @param object $xmldb_table table to be searched
-     * @param object $xmldb_index the index to be searched
-     * @return string index name of false
+     * @param xmldb_table $xmldb_table table to be searched
+     * @param xmldb_index $xmldb_index the index to be searched
+     * @return string|bool Index name or false if no indexes are found.
+     * @throws ddl_table_missing_exception Thrown when table is not found.
      */
     public function find_index_name(xmldb_table $xmldb_table, xmldb_index $xmldb_index) {
     /// Calculate the name of the table
@@ -200,11 +208,11 @@ class database_manager {
     }
 
     /**
-     * Given one xmldb_index, check if it exists in DB (true/false)
+     * Given one xmldb_index, check if it exists in DB (true/false).
      *
-     * @param object $xmldb_table the table to be searched
-     * @param object $xmldb_index the index to be searched for
-     * @return boolean true/false
+     * @param xmldb_table $xmldb_table The table to be searched.
+     * @param xmldb_index $xmldb_index The index to be searched for.
+     * @return boolean true id index exists, false otherwise.
      */
     public function index_exists(xmldb_table $xmldb_table, xmldb_index $xmldb_index) {
         if (!$this->table_exists($xmldb_table)) {
@@ -219,11 +227,11 @@ class database_manager {
      * to 1 "enum-like" constraint. So, if more than one is returned, only the first one will be
      * retrieved by this function.
      *
-     * TODO: Moodle 2.1 - Drop find_check_constraint_name()
+     * @todo MDL-31147 Moodle 2.1 - Drop find_check_constraint_name()
      *
-     * @param xmldb_table the table to be searched
-     * @param xmldb_field the field to be searched
-     * @return string check constraint name or false
+     * @param xmldb_table $xmldb_table The table to be searched.
+     * @param xmldb_field $xmldb_field The field to be searched.
+     * @return string|bool check constraint name or false
      */
     public function find_check_constraint_name(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
 
@@ -256,8 +264,8 @@ class database_manager {
      *
      * TODO: Moodle 2.1 - Drop check_constraint_exists()
      *
-     * @param xmldb_table the table
-     * @param xmldb_field the field to be searched for any existing constraint
+     * @param xmldb_table $xmldb_table The table.
+     * @param xmldb_field $xmldb_field The field to be searched for any existing constraint.
      * @return boolean true/false
      */
     public function check_constraint_exists(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -271,9 +279,9 @@ class database_manager {
      * Given one xmldb_key, the function returns the name of the key in DB (if exists)
      * of false if it doesn't exist
      *
-     * @param xmldb_table the table to be searched
-     * @param xmldb_key the key to be searched
-     * @return string key name of false
+     * @param xmldb_table $xmldb_table The table to be searched.
+     * @param xmldb_key $xmldb_key The key to be searched.
+     * @return string key name if found
      */
     public function find_key_name(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
 
@@ -316,7 +324,7 @@ class database_manager {
     /**
      * This function will delete all tables found in XMLDB file from db
      *
-     * @param $file full path to the XML file to be used
+     * @param string $file Full path to the XML file to be used.
      * @return void
      */
     public function delete_tables_from_xmldb_file($file) {
@@ -354,7 +362,7 @@ class database_manager {
      * and all the associated objects (keys, indexes, constraints, sequences, triggers)
      * will be dropped too.
      *
-     * @param xmldb_table table object (just the name is mandatory)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
      * @return void
      */
     public function drop_table(xmldb_table $xmldb_table) {
@@ -399,7 +407,7 @@ class database_manager {
     /**
      * This function will load one entire XMLDB file and call install_from_xmldb_structure.
      *
-     * @param $file full path to the XML file to be used
+     * @param string $file full path to the XML file to be used
      * @return void
      */
     public function install_from_xmldb_file($file) {
@@ -411,8 +419,8 @@ class database_manager {
     /**
      * This function will load one entire XMLDB file and call install_from_xmldb_structure.
      *
-     * @param $file full path to the XML file to be used
-     * @param $tablename the name of the table.
+     * @param string $file full path to the XML file to be used
+     * @param string $tablename the name of the table.
      * @param bool $cachestructures boolean to decide if loaded xmldb structures can be safely cached
      *             useful for testunits loading the enormous main xml file hundred of times (100x)
      */
@@ -445,7 +453,7 @@ class database_manager {
      * This function will generate all the needed SQL statements, specific for each
      * RDBMS type and, finally, it will execute all those statements against the DB.
      *
-     * @param object $structure xmldb_structure object
+     * @param stdClass $xmldb_structure xmldb_structure object.
      * @return void
      */
     public function install_from_xmldb_structure($xmldb_structure) {
@@ -460,7 +468,7 @@ class database_manager {
      * This function will create the table passed as argument with all its
      * fields/keys/indexes/sequences, everything based in the XMLDB object
      *
-     * @param xmldb_table table object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (full specs are required).
      * @return void
      */
     public function create_table(xmldb_table $xmldb_table) {
@@ -482,7 +490,7 @@ class database_manager {
      * If table already exists ddl_exception will be thrown, please make sure
      * the table name does not collide with existing normal table!
      *
-     * @param xmldb_table table object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (full specs are required).
      * @return void
      */
     public function create_temp_table(xmldb_table $xmldb_table) {
@@ -505,7 +513,7 @@ class database_manager {
      *
      * It is recommended to drop temp table when not used anymore.
      *
-     * @param xmldb_table table object
+     * @param xmldb_table $xmldb_table Table object.
      * @return void
      */
     public function drop_temp_table(xmldb_table $xmldb_table) {
@@ -526,8 +534,8 @@ class database_manager {
      * This function will rename the table passed as argument
      * Before renaming the index, the function will check it exists
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param string new name of the index
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param string $newname New name of the index.
      * @return void
      */
     public function rename_table(xmldb_table $xmldb_table, $newname) {
@@ -563,8 +571,8 @@ class database_manager {
     /**
      * This function will add the field to the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function add_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -589,8 +597,8 @@ class database_manager {
     /**
      * This function will drop the field from the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (just the name is mandatory)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function drop_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -614,8 +622,8 @@ class database_manager {
     /**
      * This function will change the type of the field in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function change_field_type(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -639,8 +647,8 @@ class database_manager {
     /**
      * This function will change the precision of the field in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function change_field_precision(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -651,8 +659,8 @@ class database_manager {
     /**
      * This function will change the unsigned/signed of the field in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Field object (full specs are required).
      * @return void
      */
     public function change_field_unsigned(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -663,8 +671,8 @@ class database_manager {
     /**
      * This function will change the nullability of the field in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function change_field_notnull(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -676,8 +684,8 @@ class database_manager {
      * This function will change the default of the field in the table passed as arguments
      * One null value in the default field means delete the default
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function change_field_default(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -703,8 +711,8 @@ class database_manager {
      *
      * TODO: Moodle 2.1 - Drop drop_enum_from_field()
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field field object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
      * @return void
      */
     public function drop_enum_from_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
@@ -733,9 +741,9 @@ class database_manager {
      * This function will rename the field in the table passed as arguments
      * Before renaming the field, the function will check it exists
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_field index object (full specs are required)
-     * @param string new name of the field
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
+     * @param string $newname New name of the field.
      * @return void
      */
     public function rename_field(xmldb_table $xmldb_table, xmldb_field $xmldb_field, $newname) {
@@ -776,7 +784,12 @@ class database_manager {
     /**
      * This function will check, for the given table and field, if there there is any dependency
      * preventing the field to be modified. It's used by all the public methods that perform any
-     * DDL change on fields, throwing one ddl_dependency_exception if dependencies are found
+     * DDL change on fields, throwing one ddl_dependency_exception if dependencies are found.
+     *
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_field $xmldb_field Index object (full specs are required).
+     * @return void
+     * @throws ddl_dependency_exception|ddl_field_missing_exception|ddl_table_missing_exception if dependency not met.
      */
     private function check_field_dependencies(xmldb_table $xmldb_table, xmldb_field $xmldb_field) {
 
@@ -805,8 +818,8 @@ class database_manager {
     /**
      * This function will create the key in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_key index object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_key $xmldb_key Index object (full specs are required).
      * @return void
      */
     public function add_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
@@ -825,8 +838,8 @@ class database_manager {
     /**
      * This function will drop the key in the table passed as arguments
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_key key object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_key $xmldb_key Key object (full specs are required).
      * @return void
      */
     public function drop_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key) {
@@ -845,9 +858,9 @@ class database_manager {
      * This function will rename the key in the table passed as arguments
      * Experimental. Shouldn't be used at all in normal installation/upgrade!
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_key key object (full specs are required)
-     * @param string new name of the key
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_key $xmldb_key key object (full specs are required).
+     * @param string $newname New name of the key.
      * @return void
      */
     public function rename_key(xmldb_table $xmldb_table, xmldb_key $xmldb_key, $newname) {
@@ -869,8 +882,8 @@ class database_manager {
      * This function will create the index in the table passed as arguments
      * Before creating the index, the function will check it doesn't exists
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_index index object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_index $xmldb_intex Index object (full specs are required).
      * @return void
      */
     public function add_index($xmldb_table, $xmldb_intex) {
@@ -896,8 +909,8 @@ class database_manager {
      * This function will drop the index in the table passed as arguments
      * Before dropping the index, the function will check it exists
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_index index object (full specs are required)
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_index $xmldb_intex Index object (full specs are required).
      * @return void
      */
     public function drop_index($xmldb_table, $xmldb_intex) {
@@ -924,9 +937,9 @@ class database_manager {
      * Before renaming the index, the function will check it exists
      * Experimental. Shouldn't be used at all!
      *
-     * @param xmldb_table table object (just the name is mandatory)
-     * @param xmldb_index index object (full specs are required)
-     * @param string new name of the index
+     * @param xmldb_table $xmldb_table Table object (just the name is mandatory).
+     * @param xmldb_index $xmldb_intex Index object (full specs are required).
+     * @param string $newname New name of the index.
      * @return void
      */
     public function rename_index($xmldb_table, $xmldb_intex, $newname) {
index 3c9b41d..fa7cbad 100644 (file)
@@ -20,7 +20,7 @@
  * MSSQL specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
index 3004c76..5f89363 100644 (file)
@@ -20,7 +20,7 @@
  * Mysql specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
index 9450388..80039a5 100644 (file)
@@ -20,7 +20,7 @@
  * Oracle specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
index 5e2a3c8..acde9d2 100644 (file)
@@ -20,7 +20,7 @@
  * PostgreSQL specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
index 203ccf3..f70ab21 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
 
 
 /**
- * This class represent the base generator class where all the
- * needed functions to generate proper SQL are defined.
+ * This class represent the base generator class where all the needed functions to generate proper SQL are defined.
  *
  * The rest of classes will inherit, by default, the same logic.
  * Functions will be overridden as needed to generate correct SQL.
  *
  * @package    core
+ * @category   ddl
  * @subpackage ddl
  * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
  *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
@@ -34,6 +33,13 @@ defined('MOODLE_INTERNAL') || die();
 
 /**
  * Abstract sql generator class, base for all db specific implementations.
+ *
+ * @package    core
+ * @category   ddl
+ * @subpackage ddl
+ * @copyright  1999 onwards Martin Dougiamas     http://dougiamas.com
+ *             2001-3001 Eloy Lafuente (stronk7) http://contiento.com
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class sql_generator {
 
@@ -42,96 +48,146 @@ abstract class sql_generator {
 /// that, by default, inherit this configuration.
 /// To change any of them, do it in extended classes instead.
 
-    public $quote_string = '"';   // String used to quote names
-
-    public $statement_end = ';'; // String to be automatically added at the end of each statement
+    /** @var string Used to quote names. */
+    public $quote_string = '"';
 
-    public $quote_all    = false; // To decide if we want to quote all the names or only the reserved ones
+    /** @var string To be automatically added at the end of each statement. */
+    public $statement_end = ';';
 
-    public $integer_to_number = false;  // To create all the integers as NUMBER(x) (also called DECIMAL, NUMERIC...)
-    public $float_to_number   = false;  // To create all the floats as NUMBER(x) (also called DECIMAL, NUMERIC...)
+    /** @var bool To decide if we want to quote all the names or only the reserved ones. */
+    public $quote_all    = false;
 
-    public $number_type = 'NUMERIC';    // Proper type for NUMBER(x) in this DB
+    /** @var bool To create all the integers as NUMBER(x) (also called DECIMAL, NUMERIC...). */
+    public $integer_to_number = false;
+    /** @var bool To create all the floats as NUMBER(x) (also called DECIMAL, NUMERIC...). */
+    public $float_to_number   = false;
 
-    public $unsigned_allowed = true;    // To define in the generator must handle unsigned information
-    public $default_for_char = null;      // To define the default to set for NOT NULLs CHARs without default (null=do nothing)
+    /** @var string Proper type for NUMBER(x) in this DB. */
+    public $number_type = 'NUMERIC';
 
-    public $drop_default_value_required = false; //To specify if the generator must use some DEFAULT clause to drop defaults
-    public $drop_default_value = ''; //The DEFAULT clause required to drop defaults
+    /** @var bool To define in the generator must handle unsigned information.*/
+    public $unsigned_allowed = true;
+    /** @var string To define the default to set for NOT NULLs CHARs without default (null=do nothing).*/
+    public $default_for_char = null;
 
-    public $default_after_null = true;  //To decide if the default clause of each field must go after the null clause
+    /** @var bool To specify if the generator must use some DEFAULT clause to drop defaults.*/
+    public $drop_default_value_required = false;
+    /** @var string The DEFAULT clause required to drop defaults.*/
+    public $drop_default_value = '';
 
-    public $specify_nulls = false;  //To force the generator if NULL clauses must be specified. It shouldn't be necessary
-                                 //but some mssql drivers require them or everything is created as NOT NULL :-(
+    /** @var bool To decide if the default clause of each field must go after the null clause.*/
+    public $default_after_null = true;
 
-    public $primary_key_name = null; //To force primary key names to one string (null=no force)
+    /**
+     * @var bool To force the generator if NULL clauses must be specified. It shouldn't be necessary.
+     * note: some mssql drivers require them or everything is created as NOT NULL :-(
+     */
+    public $specify_nulls = false;
 
-    public $primary_keys = true;  // Does the generator build primary keys
-    public $unique_keys = false;  // Does the generator build unique keys
-    public $foreign_keys = false; // Does the generator build foreign keys
+    /** @var string To force primary key names to one string (null=no force).*/
+    public $primary_key_name = null;
 
-    public $drop_primary_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME'; // Template to drop PKs
-                               // with automatic replace for TABLENAME and KEYNAME
+    /** @var bool True if the generator builds primary keys.*/
+    public $primary_keys = true;
+    /** @var bool True if the generator builds unique keys.*/
+    public $unique_keys = false;
+    /** @var bool True if the generator builds foreign keys.*/
+    public $foreign_keys = false;
 
-    public $drop_unique_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME'; // Template to drop UKs
-                               // with automatic replace for TABLENAME and KEYNAME
+    /**
+     * @var string Template to drop PKs.
+     * 'TABLENAME' and 'KEYNAME' will be replaced from this template.
+     */
+    public $drop_primary_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME';
 
-    public $drop_foreign_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME'; // Template to drop FKs
-                               // with automatic replace for TABLENAME and KEYNAME
+    /**
+     * @var string Template to drop UKs.
+     * 'TABLENAME' and 'KEYNAME' will be replaced from this template.
+     */
+    public $drop_unique_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME';
 
-    public $sequence_extra_code = true; //Does the generator need to add extra code to generate the sequence fields
-    public $sequence_name = 'auto_increment'; //Particular name for inline sequences in this generator
-    public $sequence_name_small = false; //Different name for small (4byte) sequences or false if same
-    public $sequence_only = false; //To avoid to output the rest of the field specs, leaving only the name and the sequence_name publiciable
+    /** @var string Template to drop FKs.
+     * 'TABLENAME' and 'KEYNAME' will be replaced from this template.
+     */
+    public $drop_foreign_key = 'ALTER TABLE TABLENAME DROP CONSTRAINT KEYNAME';
+
+    /** @var bool True if the generator needs to add extra code to generate the sequence fields.*/
+    public $sequence_extra_code = true;
+    /** @var string The particular name for inline sequences in this generator.*/
+    public $sequence_name = 'auto_increment';
+    /** @var string|bool Different name for small (4byte) sequences or false if same.*/
+    public $sequence_name_small = false;
+    /**
+     * @var bool To avoid outputting the rest of the field specs, leaving only the name and the sequence_name returned.
+     * @see getFieldSQL()
+     */
+    public $sequence_only = false;
 
-    public $add_table_comments  = true;  // Does the generator need to add code for table comments
+    /** @var bool True if the generator needs to add code for table comments.*/
+    public $add_table_comments  = true;
 
-    public $add_after_clause = false; // Does the generator need to add the after clause for fields
+    /** @var bool True if the generator needs to add the after clause for fields.*/
+    public $add_after_clause = false;
 
-    public $prefix_on_names = true; //Does the generator need to prepend the prefix to all the key/index/sequence/trigger/check names
+    /**
+     * @var bool True if the generator needs to prepend the prefix to all the key/index/sequence/trigger/check names.
+     * @see $prefix
+     */
+    public $prefix_on_names = true;
 
-    public $names_max_length = 30; //Max length for key/index/sequence/trigger/check names (keep 30 for all!)
+    /** @var int Maximum length for key/index/sequence/trigger/check names (keep 30 for all!).*/
+    public $names_max_length = 30;
 
-    public $concat_character = '||'; //Characters to be used as concatenation operator. If not defined
-                                  //MySQL CONCAT function will be used
+    /** @var string Characters to be used as concatenation operator.
+     * If not defined, MySQL CONCAT function will be used.
+     */
+    public $concat_character = '||';
 
-    public $rename_table_sql = 'ALTER TABLE OLDNAME RENAME TO NEWNAME'; //SQL sentence to rename one table, both
-                                  //OLDNAME and NEWNAME are dynamically replaced
+    /** @var string SQL sentence to rename one table, both 'OLDNAME' and 'NEWNAME' keywords are dynamically replaced.*/
+    public $rename_table_sql = 'ALTER TABLE OLDNAME RENAME TO NEWNAME';
 
-    public $drop_table_sql = 'DROP TABLE TABLENAME'; //SQL sentence to drop one table
-                                  //TABLENAME is dynamically replaced
+    /** @var string SQL sentence to drop one table where the 'TABLENAME' keyword is dynamically replaced.*/
+    public $drop_table_sql = 'DROP TABLE TABLENAME';
 
-    public $alter_column_sql = 'ALTER TABLE TABLENAME ALTER COLUMN COLUMNSPECS'; //The SQL template to alter columns
+    /** @var string The SQL template to alter columns where the 'TABLENAME' and 'COLUMNSPECS' keywords are dynamically replaced.*/
+    public $alter_column_sql = 'ALTER TABLE TABLENAME ALTER COLUMN COLUMNSPECS';
 
-    public $alter_column_skip_default = false; //The generator will skip the default clause on alter columns
+    /** @var bool The generator will skip the default clause on alter columns.*/
+    public $alter_column_skip_default = false;
 
-    public $alter_column_skip_type = false; //The generator will skip the type clause on alter columns
+    /** @var bool The generator will skip the type clause on alter columns.*/
+    public $alter_column_skip_type = false;
 
-    public $alter_column_skip_notnull = false; //The generator will skip the null/notnull clause on alter columns
+    /** @var bool The generator will skip the null/notnull clause on alter columns.*/
+    public $alter_column_skip_notnull = false;
 
+    /** @var string SQL sentence to rename one column where 'TABLENAME', 'OLDFIELDNAME' and 'NEWFIELDNAME' keywords are dynamically replaced.*/
     public $rename_column_sql = 'ALTER TABLE TABLENAME RENAME COLUMN OLDFIELDNAME TO NEWFIELDNAME';
-                                  ///TABLENAME, OLDFIELDNAME and NEWFIELDNAME are dyanmically replaced
 
-    public $drop_index_sql = 'DROP INDEX INDEXNAME'; //SQL sentence to drop one index
-                                  //TABLENAME, INDEXNAME are dynamically replaced
+    /** @var string SQL sentence to drop one index where 'TABLENAME', 'INDEXNAME' keywords are dynamically replaced.*/
+    public $drop_index_sql = 'DROP INDEX INDEXNAME';
 
-    public $rename_index_sql = 'ALTER INDEX OLDINDEXNAME RENAME TO NEWINDEXNAME'; //SQL sentence to rename one index
-                                  //TABLENAME, OLDINDEXNAME, NEWINDEXNAME are dynamically replaced
+    /** @var string SQL sentence to rename one index where 'TABLENAME', 'OLDINDEXNAME' and 'NEWINDEXNAME' are dynamically replaced.*/
+    public $rename_index_sql = 'ALTER INDEX OLDINDEXNAME RENAME TO NEWINDEXNAME';
 
-    public $rename_key_sql = 'ALTER TABLE TABLENAME CONSTRAINT OLDKEYNAME RENAME TO NEWKEYNAME'; //SQL sentence to rename one key
-                                  //TABLENAME, OLDKEYNAME, NEWKEYNAME are dynamically replaced
+    /** @var string SQL sentence to rename one key 'TABLENAME', 'OLDKEYNAME' and 'NEWKEYNAME' are dynamically replaced.*/
+    public $rename_key_sql = 'ALTER TABLE TABLENAME CONSTRAINT OLDKEYNAME RENAME TO NEWKEYNAME';
 
-    public $prefix;         // Prefix to be used for all the DB objects
+    /** @var string The prefix to be used for all the DB objects.*/
+    public $prefix;
 
-    public $reserved_words; // List of reserved words (in order to quote them properly)
+    /** @var string List of reserved words (in order to quote them properly).*/
+    public $reserved_words;
 
+    /** @var moodle_database The moodle_database instance.*/
     public $mdb;
-
-    protected $temptables; // Control existing temptables
+    /** @var Control existing temptables.*/
+    protected $temptables;
 
     /**
-     * Creates new sql_generator
-     * @param object moodle_database instance
+     * Creates a new sql_generator.
+     * @param moodle_database $mdb The moodle_database object instance.
+     * @param moodle_temptables $temptables The optional moodle_temptables instance, null by default.
      */
     public function __construct($mdb, $temptables = null) {
         $this->prefix         = $mdb->get_prefix();
@@ -141,14 +197,18 @@ abstract class sql_generator {
     }
 
     /**
-     * Release all resources
+     * Releases all resources.
      */
     public function dispose() {
         $this->mdb = null;
     }
 
     /**
-     * Given one string (or one array), ends it with statement_end
+     * Given one string (or one array), ends it with $statement_end .
+     *
+     * @see $statement_end
+     *
+     * @param array|string $input SQL statement(s).
      */
     public function getEndedStatements($input) {
 
@@ -164,9 +224,9 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table, check if it exists in DB (true/false)
+     * Given one xmldb_table, checks if it exists in DB (true/false).
      *
-     * @param mixed the table to be searched (string name or xmldb_table instance)
+     * @param mixed $table The table to be searched (string name or xmldb_table instance).
      * @return boolean true/false
      */
     public function table_exists($table) {
@@ -185,7 +245,11 @@ abstract class sql_generator {
     }
 
     /**
-     * This function will return the SQL code needed to create db tables and statements
+     * This function will return the SQL code needed to create db tables and statements.
+     *
+     * @param xmldb_structure $xmldb_structure An xmldb_structure instance.
+     *
+     * @see xmldb_structure
      */
     public function getCreateStructureSQL($xmldb_structure) {
         $results = array();
@@ -200,11 +264,14 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table, returns it's correct name, depending of all the parametrization
+     * Given one xmldb_table, this returns it's correct name, depending of all the parameterization.
+     * eg: This appends $prefix to the table name.
+     *
+     * @see $prefix
      *
-     * @param xmldb_table table whose name we want
-     * @param boolean to specify if the name must be quoted (if reserved word, only!)
-     * @return string the correct name of the table
+     * @param xmldb_table $xmldb_table The table whose name we want.
+     * @param boolean $quoted To specify if the name must be quoted (if reserved word, only!).
+     * @return string The correct name of the table.
      */
     public function getTableName(xmldb_table $xmldb_table, $quoted=true) {
     /// Get the name
@@ -220,7 +287,11 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_table, returns the SQL statements
-     * to create it (inside one array)
+     * to create it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table An xmldb_table instance.
+     * @return array An array of SQL statements, starting with the table creation SQL followed
+     * by any of its comments, indexes and sequence creation SQL statements.
      */
     public function getCreateTableSQL($xmldb_table) {
 
@@ -345,7 +416,12 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_index, returns the SQL statements
-     * needed to create it (in array)
+     * needed to create it (in array).
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance to create the index on.
+     * @param xmldb_index $xmldb_index The xmldb_index to create.
+     * @return array An array of SQL statements to create the index.
+     * @throws coding_exception Thrown if the xmldb_index does not validate with the xmldb_table.
      */
     public function getCreateIndexSQL($xmldb_table, $xmldb_index) {
         if ($error = $xmldb_index->validateDefinition($xmldb_table)) {
@@ -368,7 +444,17 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one correct xmldb_field, returns the complete SQL line to create it
+     * Given one correct xmldb_field, returns the complete SQL line to create it.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+     * @param string $skip_type_clause The type clause on alter columns, NULL by default.
+     * @param string $skip_default_clause The default clause on alter columns, NULL by default.
+     * @param string $skip_notnull_clause The null/notnull clause on alter columns, NULL by default.
+     * @param string $specify_nulls_clause To force a specific null clause, NULL by default.
+     * @param bool $specify_field_name Flag to specify fieldname in return.
+     * @return string The field generating SQL statement.
+     * @throws coding_exception Thrown when xmldb_field doesn't validate with the xmldb_table.
      */
     public function getFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL, $skip_default_clause = NULL, $skip_notnull_clause = NULL, $specify_nulls_clause = NULL, $specify_field_name = true)  {
         if ($error = $xmldb_field->validateDefinition($xmldb_table)) {
@@ -453,7 +539,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one correct xmldb_key, returns its specs
+     * Given one correct xmldb_key, returns its specs.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+     * @param xmldb_key $xmldb_key The xmldb_key's specifications requested.
+     * @return string SQL statement about the xmldb_key.
      */
     public function getKeySQL($xmldb_table, $xmldb_key) {
 
@@ -492,6 +582,9 @@ abstract class sql_generator {
 
     /**
      * Give one xmldb_field, returns the correct "default value" for the current configuration
+     *
+     * @param xmldb_field $xmldb_field The field.
+     * @return The default value of the field.
      */
     public function getDefaultValue($xmldb_field) {
 
@@ -529,7 +622,10 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_field, returns the correct "default clause" for the current configuration
+     * Given one xmldb_field, returns the correct "default clause" for the current configuration.
+     *
+     * @param xmldb_field $xmldb_field The xmldb_field.
+     * @return The SQL clause for generating the default value as in $xmldb_field.
      */
     public function getDefaultClause($xmldb_field) {
 
@@ -544,7 +640,11 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_table and the new name, returns the SQL statements
-     * to rename it (inside one array)
+     * to rename it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The table to rename.
+     * @param string $newname The new name to rename the table to.
+     * @return array SQL statement(s) to rename the table.
      */
     public function getRenameTableSQL($xmldb_table, $newname) {
 
@@ -566,7 +666,10 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_table and the new name, returns the SQL statements
-     * to drop it (inside one array)
+     * to drop it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The table to drop.
+     * @return array SQL statement(s) for dropping the specified table.
      */
     public function getDropTableSQL($xmldb_table) {
 
@@ -584,7 +687,14 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to add the field to the table
+     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to add the field to the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+     * @param string $skip_type_clause The type clause on alter columns, NULL by default.
+     * @param string $skip_default_clause The default clause on alter columns, NULL by default.
+     * @param string $skip_notnull_clause The null/notnull clause on alter columns, NULL by default.
+     * @return array The SQL statement for adding a field to the table.
      */
     public function getAddFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL, $skip_default_clause = NULL, $skip_notnull_clause = NULL) {
 
@@ -612,7 +722,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop the field from the table
+     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop the field from the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+     * @return array The SQL statement for dropping a field from the table.
      */
     public function getDropFieldSQL($xmldb_table, $xmldb_field) {
 
@@ -629,7 +743,14 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to alter the field in the table
+     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to alter the field in the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to create the SQL from.
+     * @param string $skip_type_clause The type clause on alter columns, NULL by default.
+     * @param string $skip_default_clause The default clause on alter columns, NULL by default.
+     * @param string $skip_notnull_clause The null/notnull clause on alter columns, NULL by default.
+     * @return string The field altering SQL statement.
      */
     public function getAlterFieldSQL($xmldb_table, $xmldb_field, $skip_type_clause = NULL, $skip_default_clause = NULL, $skip_notnull_clause = NULL) {
 
@@ -663,7 +784,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to modify the default of the field in the table
+     * Given one xmldb_table and one xmldb_field, return the SQL statements needed to modify the default of the field in the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to get the modified default value from.
+     * @return array The SQL statement for modifying the default value.
      */
     public function getModifyDefaultSQL($xmldb_table, $xmldb_field) {
 
@@ -685,7 +810,12 @@ abstract class sql_generator {
 
     /**
      * Given one correct xmldb_field and the new name, returns the SQL statements
-     * to rename it (inside one array)
+     * to rename it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_field.
+     * @param xmldb_field $xmldb_field The instance of xmldb_field to get the renamed field from.
+     * @param string $newname The new name to rename the field to.
+     * @return array The SQL statements for renaming the field.
      */
     public function getRenameFieldSQL($xmldb_table, $xmldb_field, $newname) {
 
@@ -717,7 +847,11 @@ abstract class sql_generator {
 
     /**
      * Given one xmldb_table and one xmldb_key, return the SQL statements needed to add the key to the table
-     * note that undelying indexes will be added as parametrised by $xxxx_keys and $xxxx_index parameters
+     * note that undelying indexes will be added as parametrised by $xxxx_keys and $xxxx_index parameters.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+     * @param xmldb_key $xmldb_key The xmldb_key to add.
+     * @return array SQL statement to add the xmldb_key.
      */
     public function getAddKeySQL($xmldb_table, $xmldb_key) {
 
@@ -757,7 +891,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table
+     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table.
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+     * @param xmldb_key $xmldb_key The xmldb_key to drop.
+     * @return array SQL statement to drop the xmldb_key.
      */
     public function getDropKeySQL($xmldb_table, $xmldb_key) {
 
@@ -826,8 +964,12 @@ abstract class sql_generator {
     /**
      * Given one xmldb_table and one xmldb_key, return the SQL statements needed to rename the key in the table
      * Experimental! Shouldn't be used at all!
+     *
+     * @param xmldb_table $xmldb_table The table related to $xmldb_key.
+     * @param xmldb_key $xmldb_key The xmldb_key to rename.
+     * @param string $newname The xmldb_key's new name.
+     * @return array SQL statement to rename the xmldb_key.
      */
-
     public function getRenameKeySQL($xmldb_table, $xmldb_key, $newname) {
 
         $results = array();
@@ -861,7 +1003,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to add the index to the table
+     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to add the index to the table.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance to add the index on.
+     * @param xmldb_index $xmldb_index The xmldb_index to add.
+     * @return array An array of SQL statements to add the index.
      */
     public function getAddIndexSQL($xmldb_table, $xmldb_index) {
 
@@ -870,7 +1016,11 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table
+     * Given one xmldb_table and one xmldb_index, return the SQL statements needed to drop the index from the table.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance to drop the index on.
+     * @param xmldb_index $xmldb_index The xmldb_index to drop.
+     * @return array An array of SQL statements to drop the index.
      */
     public function getDropIndexSQL($xmldb_table, $xmldb_index) {
 
@@ -891,6 +1041,11 @@ abstract class sql_generator {
     /**
      * Given one xmldb_table and one xmldb_index, return the SQL statements needed to rename the index in the table
      * Experimental! Shouldn't be used at all!
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance to rename the index on.
+     * @param xmldb_index $xmldb_index The xmldb_index to rename.
+     * @param string $newname The xmldb_index's new name.
+     * @return array An array of SQL statements to rename the index.
      */
     function getRenameIndexSQL($xmldb_table, $xmldb_index, $newname) {
     /// Some DB doesn't support index renaming (MySQL) so this can be empty
@@ -914,6 +1069,11 @@ abstract class sql_generator {
      *
      * IMPORTANT: This function must be used to CALCULATE NAMES of objects TO BE CREATED,
      *            NEVER TO GUESS NAMES of EXISTING objects!!!
+     *
+     * @param string $tablename The table name.
+     * @param string $fields A list of comma separated fields.
+     * @param string $suffix A suffix for the object name.
+     * @return string Object's name.
      */
     public function getNameForObject($tablename, $fields, $suffix='') {
 
@@ -985,6 +1145,9 @@ abstract class sql_generator {
     /**
      * Given any string (or one array), enclose it by the proper quotes
      * if it's a reserved word
+     *
+     * @param string|array $input String to quote.
+     * @return Quoted string.
      */
     public function getEncQuoted($input) {
 
@@ -1005,7 +1168,10 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one XMLDB Statement, build the needed SQL insert sentences to execute it
+     * Given one XMLDB Statement, build the needed SQL insert sentences to execute it.
+     *
+     * @param string $statement SQL statement.
+     * @return array Array of sentences in the SQL statement.
      */
     function getExecuteInsertSQL($statement) {
 
@@ -1057,9 +1223,14 @@ abstract class sql_generator {
     }
 
     /**
-     * Given one array of elements, build de proper CONCAT expression, based
+     * Given one array of elements, build the proper CONCAT expression, based
      * in the $concat_character setting. If such setting is empty, then
-     * MySQL's CONCAT function will be used instead
+     * MySQL's CONCAT function will be used instead.
+     *
+     * @param array $elements An array of elements to concatenate.
+     * @return mixed Returns the result of moodle_database::sql_concat() or false.
+     * @uses moodle_database::sql_concat()
+     * @uses call_user_func_array()
      */
     public function getConcatSQL($elements) {
 
@@ -1078,18 +1249,27 @@ abstract class sql_generator {
 
     /**
      * Returns the name (string) of the sequence used in the table for the autonumeric pk
-     * Only some DB have this implemented
+     * Only some DB have this implemented.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table instance.
+     * @return bool Returns the sequence from the DB or false.
      */
     public function getSequenceFromDB($xmldb_table) {
         return false;
     }
 
     /**
-     * Given one object name and it's type (pk, uk, fk, ck, ix, uix, seq, trg)
-     * return if such name is currently in use (true) or no (false)
+     * Given one object name and it's type (pk, uk, fk, ck, ix, uix, seq, trg).
+     *
      * (MySQL requires the whole xmldb_table object to be specified, so we add it always)
-     * (invoked from getNameForObject()
-     * Only some DB have this implemented
+     *
+     * This is invoked from getNameForObject().
+     * Only some DB have this implemented.
+     *
+     * @param string $object_name The object's name to check for.
+     * @param string $type The object's type (pk, uk, fk, ck, ix, uix, seq, trg).
+     * @param string $table_name The table's name to check in
+     * @return bool If such name is currently in use (true) or no (false)
      */
     public function isNameInUse($object_name, $type, $table_name) {
         return false; //For generators not implementing introspection,
@@ -1101,30 +1281,46 @@ abstract class sql_generator {
 
     /**
      * Reset a sequence to the id field of a table.
-     * @param string $table name of table
+     *
+     * @param string $tablename name of table.
      * @return success
      */
     public abstract function getResetSequenceSQL($tablename);
 
     /**
      * Given one correct xmldb_table, returns the SQL statements
-     * to create temporary table (inside one array)
+     * to create temporary table (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @return array SQL statements.
      */
     abstract public function getCreateTempTableSQL($xmldb_table);
 
     /**
-     * Given one correct xmldb_table and the new name, returns the SQL statements
-     * to drop it (inside one array)
+     * Given one correct xmldb_table and the new name, returns the SQL statements.
+     * to drop it (inside one array).
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @return array SQL statements.
      */
     abstract public function getDropTempTableSQL($xmldb_table);
 
     /**
-     * Given one XMLDB Type, length and decimals, returns the DB proper SQL type
+     * Given one XMLDB Type, length and decimals, returns the DB proper SQL type.
+     *
+     * @param int $xmldb_type The xmldb_type defined constant. XMLDB_TYPE_INTEGER and other XMLDB_TYPE_* constants.
+     * @param int $xmldb_length The length of that data type.
+     * @param int $xmldb_decimals The decimal places of precision of the data type.
+     * @return string The DB defined data type.
      */
     public abstract function getTypeSQL($xmldb_type, $xmldb_length=null, $xmldb_decimals=null);
 
     /**
-     * Returns the code (array of statements) needed to execute extra statements on field rename
+     * Returns the code (array of statements) needed to execute extra statements on field rename.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     * @return array Array of extra SQL statements to run with a field being renamed.
      */
     public function getRenameFieldExtraSQL($xmldb_table, $xmldb_field) {
         return array();
@@ -1132,19 +1328,30 @@ abstract class sql_generator {
 
     /**
      * Returns the code (array of statements) needed
-     * to create one sequence for the xmldb_table and xmldb_field passes
+     * to create one sequence for the xmldb_table and xmldb_field passed in.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     * @return array Array of SQL statements to create the sequence.
      */
     public function getCreateSequenceSQL($xmldb_table, $xmldb_field) {
         return array();
     }
 
     /**
-     * Returns the code (array of statements) needed to add one comment to the table
+     * Returns the code (array of statements) needed to add one comment to the table.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @return array Array of SQL statements to add one comment to the table.
      */
     public abstract function getCommentSQL($xmldb_table);
 
     /**
-     * Returns the code (array of statements) needed to execute extra statements on table rename
+     * Returns the code (array of statements) needed to execute extra statements on table rename.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param string $newname The new name for the table.
+     * @return array Array of extra SQL statements to rename a table.
      */
     public function getRenameTableExtraSQL($xmldb_table, $newname) {
         return array();
@@ -1152,6 +1359,9 @@ abstract class sql_generator {
 
     /**
      * Returns the code (array of statements) needed to execute extra statements on table drop
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @return array Array of extra SQL statements to drop a table.
      */
     public function getDropTableExtraSQL($xmldb_table) {
         return array();
@@ -1161,7 +1371,12 @@ abstract class sql_generator {
      * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop its enum
      * (usually invoked from getModifyEnumSQL()
      *
-     * TODO: Moodle 2.1 - Drop getDropEnumSQL()
+     * Note that this method may be dropped in future.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     *
+     * @todo MDL-31147 Moodle 2.1 - Drop getDropEnumSQL()
      */
     public abstract function getDropEnumSQL($xmldb_table, $xmldb_field);
 
@@ -1169,7 +1384,12 @@ abstract class sql_generator {
      * Given one xmldb_table and one xmldb_field, return the SQL statements needed to drop its default
      * (usually invoked from getModifyDefaultSQL()
      *
-     * TODO: Moodle 2.1 - Drop getDropDefaultSQL()
+     * Note that this method may be dropped in future.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     *
+     * @todo MDL-31147 Moodle 2.1 - Drop getDropDefaultSQL()
      */
     public abstract function getDropDefaultSQL($xmldb_table, $xmldb_field);
 
@@ -1178,27 +1398,37 @@ abstract class sql_generator {
      * constrainst found for that table (or field). Must exist for each DB supported.
      * (usually invoked from find_check_constraint_name)
      *
-     * TODO: Moodle 2.1 - Drop getCheckConstraintsFromDB
+     * Note that this method may be dropped in future.
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     *
+     * @todo MDL-31147 Moodle 2.1 - Drop getCheckConstraintsFromDB
      */
     public abstract function getCheckConstraintsFromDB($xmldb_table, $xmldb_field=null);
 
     /**
      * Given one xmldb_table and one xmldb_field, return the SQL statements needed to add its default
      * (usually invoked from getModifyDefaultSQL()
+     *
+     * @param xmldb_table $xmldb_table The xmldb_table object instance.
+     * @param xmldb_field $xmldb_field The xmldb_field object instance.
+     * @return array Array of SQL statements to create a field's default.
      */
     public abstract function getCreateDefaultSQL($xmldb_table, $xmldb_field);
 
     /**
      * Returns an array of reserved words (lowercase) for this DB
-     * You MUST provide the real list for each DB inside every XMLDB class
-     * @return array of reserved words
+     * You MUST provide the real list for each DB inside every XMLDB class.
+     * @return array An array of database specific reserved words.
+     * @throws coding_exception Thrown if not implemented for the specific DB.
      */
     public static function getReservedWords() {
         throw new coding_exception('getReservedWords() method needs to be overridden in each subclass of sql_generator');
     }
 
     /**
-     * Returns all reserved works in supported databases.
+     * Returns all reserved words in supported databases.
      * Reserved words should be lowercase.
      * @return array ('word'=>array(databases))
      */
@@ -1219,6 +1449,11 @@ abstract class sql_generator {
         return $reserved_words;
     }
 
+    /**
+     * Adds slashes to string.
+     * @param string $s
+     * @return string The escaped string.
+     */
     public function addslashes($s) {
         // do not use php addslashes() because it depends on PHP quote settings!
         $s = str_replace('\\','\\\\',$s);
index d2ba790..d190d07 100644 (file)
@@ -20,7 +20,7 @@
  * Experimental SQLite specific SQL code generator.
  *
  * @package    core
- * @subpackage ddl
+ * @subpackage ddl_generator
  * @copyright  2008 Andrei Bautu
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
index 0ece5f0..b09e1a5 100644 (file)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
-M.form_dndupload = {
-    // YUI object.
-    Y: null,
-    // URL for upload requests
-    url: M.cfg.wwwroot + '/repository/repository_ajax.php?action=upload',
-    // itemid used for repository upload
-    itemid: null,
-    // accepted filetypes accepted by this form passed to repository
-    acceptedtypes: [],
-    // maximum number of files this form allows
-    maxfiles: 0,
-    // maximum size of files allowed in this form
-    maxbytes: 0,
-    // unqiue id of this form field used for html elements
-    clientid: '',
-    // upload repository id, used for upload
-    repositoryid: 0,
-    // container which holds the node which recieves drag events
-    container: null,
-    // filemanager element we are working with
-    filemanager: null,
-    // callback  to filepicker element to refesh when uploaded
-    callback: null,
-    // Nasty hack to distinguish between dragenter(first entry),
-    // dragenter+dragleave(moving between child elements) and dragleave (leaving element)
-    entercount: 0,
-
-
-    /**
-     * Initalise the drag and drop upload interface
-     * Note: one and only one of options.filemanager and options.formcallback must be defined
-     *
-     * @param Y the YUI object
-     * @param object options {
-     *            itemid: itemid used for repository upload in this form
-     *            acceptdtypes: accepted filetypes by this form
-     *            maxfiles: maximum number of files this form allows
-     *            maxbytes: maximum size of files allowed in this form
-     *            clientid: unqiue id of this form field used for html elements
-     *            containerprefix: prefix of htmlid of container
-     *            repositories: array of repository objects passed from filepicker
-     *            filemanager: filemanager element we are working with
-     *            callback: callback  to filepicker element to refesh when uploaded
-     *          }
-     */
-    init: function(Y, options) {
-        this.Y = Y;
-
-        if (!this.browser_supported()) {
-            return; // Browser does not support the required functionality
-        }
+M.form_dndupload = {}
+
+M.form_dndupload.init = function(Y, options) {
+    var dnduploadhelper = {
+        // YUI object.
+        Y: null,
+        // URL for upload requests
+        url: M.cfg.wwwroot + '/repository/repository_ajax.php?action=upload',
+        // itemid used for repository upload
+        itemid: null,
+        // accepted filetypes accepted by this form passed to repository
+        acceptedtypes: [],
+        // maximum number of files this form allows
+        maxfiles: 0,
+        // maximum size of files allowed in this form
+        maxbytes: 0,
+        // unqiue id of this form field used for html elements
+        clientid: '',
+        // upload repository id, used for upload
+        repositoryid: 0,
+        // container which holds the node which recieves drag events
+        container: null,
+        // filemanager element we are working with
+        filemanager: null,
+        // callback  to filepicker element to refesh when uploaded
+        callback: null,
+        // Nasty hack to distinguish between dragenter(first entry),
+        // dragenter+dragleave(moving between child elements) and dragleave (leaving element)
+        entercount: 0,
+        pageentercount: 0,
+
+        /**
+         * Initalise the drag and drop upload interface
+         * Note: one and only one of options.filemanager and options.formcallback must be defined
+         *
+         * @param Y the YUI object
+         * @param object options {
+         *            itemid: itemid used for repository upload in this form
+         *            acceptdtypes: accepted filetypes by this form
+         *            maxfiles: maximum number of files this form allows
+         *            maxbytes: maximum size of files allowed in this form
+         *            clientid: unqiue id of this form field used for html elements
+         *            containerprefix: prefix of htmlid of container
+         *            repositories: array of repository objects passed from filepicker
+         *            filemanager: filemanager element we are working with
+         *            callback: callback  to filepicker element to refesh when uploaded
+         *          }
+         */
+        init: function(Y, options) {
+            this.Y = Y;
+
+            if (!this.browser_supported()) {
+                return; // Browser does not support the required functionality
+            }
 
-        // try and retrieve enabled upload repository
-        this.repositoryid = this.get_upload_repositoryid(options.repositories);
+            // try and retrieve enabled upload repository
+            this.repositoryid = this.get_upload_repositoryid(options.repositories);
 
-        if (!this.repositoryid) {
-            return; // no upload repository is enabled to upload to
-        }
+            if (!this.repositoryid) {
+                return; // no upload repository is enabled to upload to
+            }
 
-        this.acceptedtypes = options.acceptedtypes;
-        this.clientid = options.clientid;
-        this.maxfiles = options.maxfiles;
-        this.maxbytes = options.maxbytes;
-        this.itemid = options.itemid;
-        this.container = this.Y.one(options.containerprefix + this.clientid);
-
-        if (options.filemanager) {
-            // Needed to tell the filemanager to redraw when files uploaded
-            // and to check how many files are already uploaded
-            this.filemanager = options.filemanager;
-        } else if (options.formcallback) {
-
-            // Needed to tell the filepicker to update when a new
-            // file is uploaded
-            this.callback = options.formcallback;
-        } else {
-            if (M.cfg.developerdebug) {
-                alert('dndupload: Need to define either options.filemanager or options.callback');
+            this.acceptedtypes = options.acceptedtypes;
+            this.clientid = options.clientid;
+            this.maxfiles = options.maxfiles;
+            this.maxbytes = options.maxbytes;
+            this.itemid = options.itemid;
+            this.container = this.Y.one(options.containerprefix + this.clientid);
+
+            if (options.filemanager) {
+                // Needed to tell the filemanager to redraw when files uploaded
+                // and to check how many files are already uploaded
+                this.filemanager = options.filemanager;
+            } else if (options.formcallback) {
+
+                // Needed to tell the filepicker to update when a new
+                // file is uploaded
+                this.callback = options.formcallback;
+            } else {
+                if (M.cfg.developerdebug) {
+                    alert('dndupload: Need to define either options.filemanager or options.callback');
+                }
+                return;
             }
-            return;
-        }
 
-        this.init_events();
-        this.Y.one('#dndenabled-'+this.clientid).setStyle('display', 'inline');
-    },
+            this.init_events();
+            this.init_page_events();
+            this.Y.one('#dndenabled-'+this.clientid).setStyle('display', 'inline');
+        },
 
-    /**
-     * Check the browser has the required functionality
-     * @return true if browser supports drag/drop upload
-     */
-    browser_supported: function() {
+        /**
+         * Check the browser has the required functionality
+         * @return true if browser supports drag/drop upload
+         */
+        browser_supported: function() {
+
+            if (typeof FileReader == 'undefined') {
+                return false;
+            }
+            if (typeof FormData == 'undefined') {
+                return false;
+            }
+            return true;
+        },
+
+        /**
+         * Get upload repoistory from array of enabled repositories
+         *
+         * @param array repositories repository objects passed from filepicker
+         * @param returns int id of upload repository or false if not found
+         */
+        get_upload_repositoryid: function(repositories) {
+            for (var i in repositories) {
+                if (repositories[i].type == "upload") {
+                    return repositories[i].id;
+                }
+            }
 
-        if (typeof FileReader == 'undefined') {
-            return false;
-        }
-        if (typeof FormData == 'undefined') {
-            return false;
-        }
-        return true;
-    },
-
-    /**
-     * Get upload repoistory from array of enabled repositories
-     *
-     * @param array repositories repository objects passed from filepicker
-     * @param returns int id of upload repository or false if not found
-     */
-    get_upload_repositoryid: function(repositories) {
-         for (var i in repositories) {
-             if (repositories[i].type == "upload") {
-                 return repositories[i].id;
-             }
-         }
-
-         return false;
-    },
-
-    /**
-     * Initialise drag events on node container, all events need
-     * to be processed for drag and drop to work
-     */
-    init_events: function() {
-        this.Y.on('dragenter', this.drag_enter, this.container, this);
-        this.Y.on('dragleave', this.drag_leave, this.container, this);
-        this.Y.on('dragover',  this.drag_over,  this.container, this);
-        this.Y.on('drop',      this.drop,      this.container, this);
-    },
-
-    /**
-     * Check if the drag contents are valid and then call
-     * preventdefault / stoppropagation to let the browser know
-     * we will handle this drag/drop
-     *
-     * @param e event object
-     * @return boolean true if a valid file drag event
-     */
-    check_drag: function(e) {
-        if (!this.has_files(e)) {
             return false;
-        }
+        },
+
+        /**
+         * Initialise drag events on node container, all events need
+         * to be processed for drag and drop to work
+         */
+        init_events: function() {
+            this.Y.on('dragenter', this.drag_enter, this.container, this);
+            this.Y.on('dragleave', this.drag_leave, this.container, this);
+            this.Y.on('dragover',  this.drag_over,  this.container, this);
+            this.Y.on('drop',      this.drop,      this.container, this);
+        },
+
+        /**
+         * Initialise whole-page events (to show / hide the 'drop files here'
+         * message)
+         */
+        init_page_events: function() {
+            this.Y.on('dragenter', this.drag_enter_page, 'body', this);
+            this.Y.on('dragleave', this.drag_leave_page, 'body', this);
+        },
+
+        /**
+         * Show the 'drop files here' message when file(s) are dragged
+         * onto the page
+         */
+        drag_enter_page: function(e) {
+            if (!this.has_files(e) || this.reached_maxfiles()) {
+                return false;
+            }
 
-        e.preventDefault();
-        e.stopPropagation();
+            this.pageentercount++;
+            if (this.pageentercount >= 2) {
+                this.pageentercount = 2;
+                return false;
+            }
+
+            this.show_drop_target();
 
-        if (this.reached_maxfiles()) {
             return false;
-        }
+        },
+
+        /**
+         * Hide the 'drop files here' message when file(s) are dragged off
+         * the page again
+         */
+        drag_leave_page: function(e) {
+            this.pageentercount--;
+            if (this.pageentercount == 1) {
+                return false;
+            }
+            this.pageentercount = 0;
 
-        return true;
-    },
+            this.hide_drop_target();
 
-    /**
-     * Handle a dragenter event, highlight the destination node
-     * when a suitable drag event occurs
-     */
-    drag_enter: function(e) {
-        if (!this.check_drag(e)) {
-            return true;
-        }
-
-        this.entercount++;
-        if (this.entercount >= 2) {
-            this.entercount = 2; // Just moved over a child element - nothing to do
             return false;
-        }
+        },
+
+        /**
+         * Check if the drag contents are valid and then call
+         * preventdefault / stoppropagation to let the browser know
+         * we will handle this drag/drop
+         *
+         * @param e event object
+         * @return boolean true if a valid file drag event
+         */
+        check_drag: function(e, maxfilesalert) {
+            if (!this.has_files(e)) {
+                return false;
+            }
 
-        this.show_upload_ready();
-        return false;
-    },
+            e.preventDefault();
+            e.stopPropagation();
+
+            if (this.reached_maxfiles()) {
+                if (typeof(maxfilesalert) != 'undefined' && maxfilesalert) {
+                    alert(M.util.get_string('maxfilesreached', 'moodle', this.maxfiles));
+                }
+                return false;
+            }
 
-    /**
-     * Handle a dragleave event, Remove the highlight if dragged from
-     * node
-     */
-    drag_leave: function(e) {
-        if (!this.check_drag(e)) {
             return true;
-        }
+        },
+
+        /**
+         * Handle a dragenter event, highlight the destination node
+         * when a suitable drag event occurs
+         */
+        drag_enter: function(e) {
+            if (!this.check_drag(e)) {
+                return true;
+            }
 
-        this.entercount--;
-        if (this.entercount == 1) {
-            return false; // Just moved over a child element - nothing to do
-        }
+            this.entercount++;
+            if (this.entercount >= 2) {
+                this.entercount = 2; // Just moved over a child element - nothing to do
+                return false;
+            }
 
-        this.entercount = 0;
-        this.hide_upload_ready();
-        return false;
-    },
-
-    /**
-     * Handle a dragover event. Required to intercept to prevent the browser from
-     * handling the drag and drop event as normal
-     */
-    drag_over: function(e) {
-        if (!this.check_drag(e)) {
-            return true;
-        }
+            // These lines are needed if the user has dragged something directly
+            // from application onto the 'fileupload' box, without crossing another
+            // part of the page first
+            this.pageentercount = 2;
+            this.show_drop_target();
 
-        return false;
-    },
+            this.show_upload_ready();
+            return false;
+        },
+
+        /**
+         * Handle a dragleave event, Remove the highlight if dragged from
+         * node
+         */
+        drag_leave: function(e) {
+            if (!this.check_drag(e)) {
+                return true;
+            }
 
-    /**
-     * Handle a drop event.  Remove the highlight and then upload each
-     * of the files (until we reach the file limit, or run out of files)
-     */
-    drop: function(e) {
-        if (!this.check_drag(e)) {
-            return true;
-        }
+            this.entercount--;
+            if (this.entercount == 1) {
+                return false; // Just moved over a child element - nothing to do
+            }
+
+            this.entercount = 0;
+            this.hide_upload_ready();
+            return false;
+        },
+
+        /**
+         * Handle a dragover event. Required to intercept to prevent the browser from
+         * handling the drag and drop event as normal
+         */
+        drag_over: function(e) {
+            if (!this.check_drag(e)) {
+                return true;
+            }
 
-        this.entercount = 0;
-        this.hide_upload_ready();
-        this.show_progress_spinner();
+            return false;
+        },
+
+        /**
+         * Handle a drop event.  Remove the highlight and then upload each
+         * of the files (until we reach the file limit, or run out of files)
+         */
+        drop: function(e) {
+            if (!this.check_drag(e, true)) {
+                return true;
+            }
 
-        var files = e._event.dataTransfer.files;
-        if (this.filemanager) {
-            var currentfilecount = this.filemanager.filecount;
-            for (var i=0, f; f=files[i]; i++) {
-                if (currentfilecount >= this.maxfiles && this.maxfiles != -1) {
-                    break;
+            this.entercount = 0;
+            this.pageentercount = 0;
+            this.hide_upload_ready();
+            this.hide_drop_target();
+            this.show_progress_spinner();
+
+            var files = e._event.dataTransfer.files;
+            if (this.filemanager) {
+                var currentfilecount = this.filemanager.filecount;
+                for (var i=0, f; f=files[i]; i++) {
+                    if (currentfilecount >= this.maxfiles && this.maxfiles != -1) {
+                        alert(M.util.get_string('maxfilesreached', 'moodle', this.maxfiles));
+                        break;
+                    }
+                    if (this.upload_file(f)) {
+                        currentfilecount++;
+                    }
                 }
-                if (this.upload_file(f)) {
-                    currentfilecount++;
+            } else {
+                if (files.length >= 1) {
+                    this.upload_file(files[0]);
                 }
             }
-        } else {
-            if (files.length >= 1) {
-                this.upload_file(files[0]);
-            }
-        }
 
-        return false;
-    },
-
-    /**
-     * Check to see if the drag event has any files in it
-     *
-     * @param e event object
-     * @return boolean true if event has files
-     */
-    has_files: function(e) {
-        var types = e._event.dataTransfer.types;
-        for (var i=0; i<types.length; i++) {
-            if (types[i] == 'Files') {
-                return true;
+            return false;
+        },
+
+        /**
+         * Check to see if the drag event has any files in it
+         *
+         * @param e event object
+         * @return boolean true if event has files
+         */
+        has_files: function(e) {
+            var types = e._event.dataTransfer.types;
+            for (var i=0; i<types.length; i++) {
+                if (types[i] == 'Files') {
+                    return true;
+                }
             }
-        }
-        return false;
-    },
-
-    /**
-     * Check if reached the maximumum number of allowed files
-     *
-     * @return boolean true if reached maximum number of files
-     */
-    reached_maxfiles: function() {
-        if (this.filemanager) {
-            if (this.filemanager.filecount >= this.maxfiles && this.maxfiles != -1) {
-                return true;
+            return false;
+        },
+
+        /**
+         * Check if reached the maximumum number of allowed files
+         *
+         * @return boolean true if reached maximum number of files
+         */
+        reached_maxfiles: function() {
+            if (this.filemanager) {
+                if (this.filemanager.filecount >= this.maxfiles && this.maxfiles != -1) {
+                    return true;
+                }
             }
-        }
-        return false;
-    },
-
-    /**
-     * Highlight the destination node
-     */
-    show_upload_ready: function() {
-        this.container.addClass('dndupload-over');
-    },
-
-    /**
-     * Remove highlight on destination node
-     */
-    hide_upload_ready: function() {
-        this.container.removeClass('dndupload-over');
-    },
-
-    /**
-     * Display a progress spinner in the destination node
-     */
-    show_progress_spinner: function() {
-        // add a loading spinner to show something is happening
-        var loadingspinner = this.Y.Node.create('<div id="dndprogresspinner-'+this.clientid+'" style="text-align: center">');
-        loadingspinner.append('<img src="'+M.util.image_url('i/loading_small')+'" />');
-        this.container.append(loadingspinner);
-    },
-
-    /**
-     * Remove progress spinner in the destination node
-     */
-    hide_progress_spinner: function() {
-        this.Y.one('#dndprogresspinner-'+this.clientid).remove();
-    },
-
-    /**
-     * Tell the attached filemanager element (if any) to refresh on file
-     * upload
-     */
-    update_filemanager: function() {
-        if (this.filemanager) {
-            // update the filemanager that we've uploaded the files
-            this.filemanager.filepicker_callback();
-        }
-    },
-
-    /**
-     * Upload a single file via an AJAX call to the 'upload' repository
-     */
-    upload_file: function(file) {
-        if (file.size > this.maxbytes && this.maxbytes > 0) {
-            // Check filesize before attempting to upload
-            this.hide_progress_spinner();
-            alert(M.util.get_string('uploadformlimit', 'moodle')+"\n'"+file.name+"'");
             return false;
-        }
+        },
+
+        /**
+         * Highlight the area where files could be dropped
+         */
+        show_drop_target: function() {
+            this.Y.one('#filemanager-uploadmessage'+this.clientid).setStyle('display', 'block');
+        },
+
+        hide_drop_target: function() {
+            this.Y.one('#filemanager-uploadmessage'+this.clientid).setStyle('display', 'none');
+        },
+
+        /**
+         * Highlight the destination node (ready to drop)
+         */
+        show_upload_ready: function() {
+            this.container.addClass('dndupload-over');
+        },
+
+        /**
+         * Remove highlight on destination node
+         */
+        hide_upload_ready: function() {
+            this.container.removeClass('dndupload-over');
+        },
+
+        /**
+         * Display a progress spinner in the destination node
+         */
+        show_progress_spinner: function() {
+            // add a loading spinner to show something is happening
+            var loadingspinner = this.Y.Node.create('<div id="dndprogresspinner-'+this.clientid+'" style="text-align: center">');
+            loadingspinner.append('<img src="'+M.util.image_url('i/loading_small')+'" />');
+            this.container.append(loadingspinner);
+        },
+
+        /**
+         * Remove progress spinner in the destination node
+         */
+        hide_progress_spinner: function() {
+            var spinner = this.Y.one('#dndprogresspinner-'+this.clientid);
+            if (spinner) {
+                spinner.remove();
+            }
+        },
+
+        /**
+         * Tell the attached filemanager element (if any) to refresh on file
+         * upload
+         */
+        update_filemanager: function() {
+            if (this.filemanager) {
+                // update the filemanager that we've uploaded the files
+                this.filemanager.filepicker_callback();
+            }
+        },
+
+        /**
+         * Upload a single file via an AJAX call to the 'upload' repository
+         */
+        upload_file: function(file) {
+            if (file.size > this.maxbytes && this.maxbytes > 0) {
+                // Check filesize before attempting to upload
+                this.hide_progress_spinner();
+                alert(M.util.get_string('uploadformlimit', 'moodle')+"\n'"+file.name+"'");
+                return false;
+            }
 
-        // This would be an ideal place to use the Y.io function
-        // however, this does not support data encoded using the
-        // FormData object, which is needed to transfer data from
-        // the DataTransfer object into an XMLHTTPRequest
-        // This can be converted when the YUI issue has been integrated:
-        // http://yuilibrary.com/projects/yui3/ticket/2531274
-        var xhr = new XMLHttpRequest();
-        var self = this;
-        xhr.onreadystatechange = function() { // Process the server response
-            if (xhr.readyState == 4) {
-                self.hide_progress_spinner();
-                if (xhr.status == 200) {
-                    var result = JSON.parse(xhr.responseText);
-                    if (result) {
-                        if (result.error) {
-                            alert(result.error);
-                        } else if (self.callback) {
-                            // Only update the filepicker if there were no errors
-                            if (result.event == 'fileexists') {
-                                // Do not worry about this, as we only care about the last
-                                // file uploaded, with the filepicker
-                                result.file = result.newfile.filename;
-                                result.url = result.newfile.url;
+            // This would be an ideal place to use the Y.io function
+            // however, this does not support data encoded using the
+            // FormData object, which is needed to transfer data from
+            // the DataTransfer object into an XMLHTTPRequest
+            // This can be converted when the YUI issue has been integrated:
+            // http://yuilibrary.com/projects/yui3/ticket/2531274
+            var xhr = new XMLHttpRequest();
+            var self = this;
+            xhr.onreadystatechange = function() { // Process the server response
+                if (xhr.readyState == 4) {
+                    self.hide_progress_spinner();
+                    if (xhr.status == 200) {
+                        var result = JSON.parse(xhr.responseText);
+                        if (result) {
+                            if (result.error) {
+                                alert(result.error);
+                            } else if (self.callback) {
+                                // Only update the filepicker if there were no errors
+                                if (result.event == 'fileexists') {
+                                    // Do not worry about this, as we only care about the last
+                                    // file uploaded, with the filepicker
+                                    result.file = result.newfile.filename;
+                                    result.url = result.newfile.url;
+                                }
+                                result.client_id = self.clientid;
+                                self.callback(result);
+                            } else {
+                                self.update_filemanager();
                             }
-                            result.client_id = self.clientid;
-                            self.callback(result);
-                        } else {
-                            self.update_filemanager();
                         }
+                    } else {
+                        alert(M.util.get_string('serverconnection', 'error'));
                     }
-                } else {
-                    alert(M.util.get_string('serverconnection', 'error'));
                 }
+            };
+
+            // Prepare the data to send
+            var formdata = new FormData();
+            formdata.append('repo_upload_file', file); // The FormData class allows us to attach a file
+            formdata.append('sesskey', M.cfg.sesskey);
+            formdata.append('repo_id', this.repositoryid);
+            formdata.append('itemid', this.itemid);
+            if (this.filemanager) { // Filepickers do not have folders
+                formdata.append('savepath', this.filemanager.currentpath);
             }
-        };
-
-        // Prepare the data to send
-        var formdata = new FormData();
-        formdata.append('repo_upload_file', file); // The FormData class allows us to attach a file
-        formdata.append('sesskey', M.cfg.sesskey);
-        formdata.append('repo_id', this.repositoryid);
-        formdata.append('itemid', this.itemid);
-        if (this.filemanager) { // Filepickers do not have folders
-            formdata.append('savepath', this.filemanager.currentpath);
-        }
 
-        if (this.acceptedtypes.constructor == Array) {
-            for (var i=0; i<this.acceptedtypes.length; i++) {
-                formdata.append('accepted_types[]', this.acceptedtypes[i]);
+            if (this.acceptedtypes.constructor == Array) {
+                for (var i=0; i<this.acceptedtypes.length; i++) {
+                    formdata.append('accepted_types[]', this.acceptedtypes[i]);
+                }
+            } else {
+                formdata.append('accepted_types[]', this.acceptedtypes);
             }
-        } else {
-            formdata.append('accepted_types[]', this.acceptedtypes);
+
+            // Send the file & required details
+            xhr.open("POST", this.url, true);
+            xhr.send(formdata);
+            return true;
         }
+    };
 
-        // Send the file & required details
-        xhr.open("POST", this.url, true);
-        xhr.send(formdata);
-        return true;
-    }
+    dnduploadhelper.init(Y, options);
 };
index 18d3842..de89ff3 100644 (file)
@@ -144,6 +144,7 @@ M.form_filemanager.init = function(Y, options) {
             this.filecount++;
             this.check_buttons();
             this.refresh(this.currentpath);
+            M.util.set_form_changed();
         },
         check_buttons: function() {
             var button_addfile  = Y.one("#btnadd-"+this.client_id);
@@ -213,6 +214,7 @@ M.form_filemanager.init = function(Y, options) {
                                 scope.mkdir_dialog.hide();
                                 scope.refresh(filepath);
                                 Y.one('#fm-newname').set('value', '');
+                                M.util.set_form_changed();
                             }
                         });
                     }
@@ -262,7 +264,13 @@ M.form_filemanager.init = function(Y, options) {
             }, this);
         },
         empty_filelist: function(container) {
-            container.set('innerHTML', '<div class="mdl-align">'+M.str.repository.nofilesattached+'</div>');
+            container.set('innerHTML', '<div class="mdl-align">'+M.str.repository.nofilesattached+'</div>'+this.upload_message());
+        },
+        upload_message: function() {
+            var div = '<div id="filemanager-uploadmessage'+this.client_id+'" style="display:none" class="dndupload-target">';
+            div += M.util.get_string('droptoupload', 'moodle');
+            div += '</div>';
+            return div;
         },
         render: function() {
             var options = this.options;
@@ -413,6 +421,7 @@ M.form_filemanager.init = function(Y, options) {
                 var filelist = Y.Node.create('<ul id="draftfiles-'+this.client_id+'"></ul>');
                 container.appendChild(filelist);
             }
+            listhtml += this.upload_message();
             Y.one('#draftfiles-'+this.client_id).set('innerHTML', listhtml);
 
             // click normal file menu
@@ -559,6 +568,7 @@ M.form_filemanager.init = function(Y, options) {
                         callback: function(id, obj, args) {
                             scope.filecount--;
                             scope.refresh(obj.filepath);
+                            M.util.set_form_changed();
                             if (scope.filecount < scope.maxfiles && scope.maxfiles!=-1) {
                                 var button_addfile  = Y.one("#btnadd-"+scope.client_id);
                                 button_addfile.setStyle('display', 'inline');
@@ -606,6 +616,7 @@ M.form_filemanager.init = function(Y, options) {
                                 alert(M.str.repository.fileexists);
                             } else {
                                 scope.refresh(obj.filepath);
+                                M.util.set_form_changed();
                             }
                             Y.one('#fm-rename-input').set('value', '');
                             scope.rename_dialog.hide();
@@ -683,6 +694,7 @@ M.form_filemanager.init = function(Y, options) {
                             }
                             dialog.cancel();
                             scope.refresh(p);
+                            M.util.set_form_changed();
                         }
                     });
                 }
index 1d93585..7d42d81 100644 (file)
@@ -288,7 +288,7 @@ $icon_progress
         <span> $maxsize </span>
         <span id="dndenabled-{$client_id}" style="display: none"> - $strdndenabled </span>
     </div>
-    <div class="filemanager-container" id="filemanager-{$client_id}">
+    <div class="filemanager-container" id="filemanager-{$client_id}" style="position: relative" >
         <ul id="draftfiles-{$client_id}" class="fm-filelist">
             <li>Loading...</li>
         </ul>
index 51d8ef6..4c99ea8 100644 (file)
@@ -6,6 +6,7 @@ M.form_filepicker.instances = [];
 M.form_filepicker.callback = function(params) {
     var html = '<a href="'+params['url']+'">'+params['file']+'</a>';
     document.getElementById('file_info_'+params['client_id']).innerHTML = html;
+    M.form_filepicker.add_upload_message(params['client_id']);
     //When file is added then set status of global variable to true
     var elementname = M.core_filepicker.instances[params['client_id']].options.elementname;
     M.form_filepicker.instances[elementname].fileadded = true;
@@ -13,6 +14,15 @@ M.form_filepicker.callback = function(params) {
     M.form_filepicker.Y.one('#id_'+elementname).simulate('change');
 };
 
+M.form_filepicker.add_upload_message = function(client_id) {
+    var div = '<div id="filemanager-uploadmessage'+client_id+'" style="display:none" class="dndupload-target">';
+    div += M.util.get_string('droptoupload', 'moodle');
+    div += '</div>';
+    var iteminfo = document.getElementById('file_info_'+client_id);
+    iteminfo.innerHTML += div;
+    iteminfo.style.position = 'relative';
+}
+
 /**
  * This fucntion is called for each file picker on page.
  */
@@ -42,6 +52,7 @@ M.form_filepicker.init = function(Y, options) {
     item = document.getElementById('filepicker-wrapper-'+options.client_id);
     if (item) {
         item.style.display = '';
+        this.add_upload_message(options.client_id);
     }
 
     var dndoptions = {
index 0f06fcf..371c2b0 100644 (file)
@@ -2255,6 +2255,7 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{
      * @param object $form MoodleQuickForm
      */
     function startForm(&$form){
+        global $PAGE;
         $this->_reqHTML = $form->getReqHTML();
         $this->_elementTemplates = str_replace('{req}', $this->_reqHTML, $this->_elementTemplates);
         $this->_advancedHTML = $form->getAdvancedHTML();
@@ -2267,7 +2268,13 @@ class MoodleQuickForm_Renderer extends HTML_QuickForm_Renderer_Tableless{
             $this->_hiddenHtml .= $form->_pageparams;
         }
 
-
+        $PAGE->requires->yui_module('moodle-core-formslib',
+                'M.core.init_formslib',
+                array(array(
+                    'formid' => $form->getAttribute('id')
+                ))
+        );
+        $PAGE->requires->string_for_js('changesmadereallygoaway', 'moodle');
     }
 
     /**
index faf00b8..6f3a137 100644 (file)
@@ -1113,7 +1113,7 @@ class HTML5 {
                 $entity = $this->character($start, $this->char);
                 $cond = strlen($e_name) > 0;
 
-                // The rest of the parsing happens bellow.
+                // The rest of the parsing happens below.
             break;
 
             // Anything else
@@ -1140,7 +1140,7 @@ class HTML5 {
                 }
 
                 $cond = isset($entity);
-                // The rest of the parsing happens bellow.
+                // The rest of the parsing happens below.
             break;
         }
 
index 07f8cfc..452be34 100644 (file)
@@ -1752,4 +1752,72 @@ M.util.load_flowplayer = function() {
         fileref.onreadystatechange = embed_function;
         document.getElementsByTagName('head')[0].appendChild(fileref);
     }
+};
+
+/**
+ * Set the form changed state to true
+ */
+M.util.set_form_changed = function() {
+    M.cfg.form_changed = 1;
+};
+
+/**
+ * Set the form submitted state to true
+ */
+M.util.set_form_submitted = function() {
+    M.cfg.form_submitted = 1;
 }
+
+/**
+ * Attempt to determine whether the form has been modified in any way and
+ * is thus 'dirty'
+ *
+ * @return Integer 1 is the form is dirty; 0 if not
+ */
+M.util.get_form_dirty_state = function() {
+    // If the form was submitted, then return a non-dirty state
+    if (M.cfg.form_submitted) {
+        return 0;
+    }
+
+    // If any fields have been marked dirty, return a dirty state
+    if (M.cfg.form_changed) {
+        return 1;
+    }
+
+    // Handle TinyMCE editor instances
+    // We can't add a listener in the initializer as the editors may not have been created by that point
+    // so we do so here instead
+    if (typeof tinyMCE != 'undefined') {
+        for (var editor in tinyMCE.editors) {
+            if (tinyMCE.editors[editor].isDirty()) {
+                return 1;
+            }
+        }
+    }
+
+    // If we reached here, then the form hasn't met any of the dirty conditions
+    return 0;
+};
+
+/**
+ * Return a suitable message if changes have been made to a form
+ */
+M.util.report_form_dirty_state = function(e) {
+    if (!M.util.get_form_dirty_state()) {
+        // the form is not dirty, so don't display any message
+        return;
+    }
+
+    // This is the error message that we'll show to browsers which support it
+    var returnValue = M.util.get_string('changesmadereallygoaway', 'moodle');
+
+    // Most browsers are happy with the returnValue being set on the event
+    // But some browsers do not consistently pass the event
+    if (e) {
+        e.returnValue = returnValue;
+    }
+
+    // But some require it to be returned instead
+    return returnValue;
+};
index 9d249dd..5c14a6e 100644 (file)
@@ -1945,9 +1945,10 @@ function make_timestamp($year, $month=1, $day=1, $hour=0, $minute=0, $second=0,
  *        {@link http://docs.moodle.org/dev/Time_API#Timezone}
  * @param bool $fixday If true (default) then the leading zero from %d is removed.
  *        If false then the leading zero is maintained.
+ * @param bool $fixhour If true (default) then the leading zero from %I is removed.
  * @return string the formatted date/time.
  */
-function userdate($date, $format = '', $timezone = 99, $fixday = true) {
+function userdate($date, $format = '', $timezone = 99, $fixday = true, $fixhour = true) {
 
     global $CFG;
 
@@ -1960,6 +1961,19 @@ function userdate($date, $format = '', $timezone = 99, $fixday = true) {
     } else if ($fixday) {
         $formatnoday = str_replace('%d', 'DD', $format);
         $fixday = ($formatnoday != $format);
+        $format = $formatnoday;
+    }
+
+    // Note: This logic about fixing 12-hour time to remove unnecessary leading
+    // zero is required because on Windows, PHP strftime function does not
+    // support the correct 'hour without leading zero' parameter (%l).
+    if (!empty($CFG->nofixhour)) {
+        // Config.php can force %I not to be fixed.
+        $fixhour = false;
+    } else if ($fixhour) {
+        $formatnohour = str_replace('%I', 'HH', $format);
+        $fixhour = ($formatnohour != $format);
+        $format = $formatnohour;
     }
 
     //add daylight saving offset for string timezones only, as we can't get dst for
@@ -1971,21 +1985,25 @@ function userdate($date, $format = '', $timezone = 99, $fixday = true) {
     $timezone = get_user_timezone_offset($timezone);
 
     if (abs($timezone) > 13) {   /// Server time
+        $datestring = strftime($format, $date);
         if ($fixday) {
-            $datestring = strftime($formatnoday, $date);
             $daystring  = ltrim(str_replace(array(' 0', ' '), '', strftime(' %d', $date)));
             $datestring = str_replace('DD', $daystring, $datestring);
-        } else {
-            $datestring = strftime($format, $date);
+        }
+        if ($fixhour) {
+            $hourstring = ltrim(str_replace(array(' 0', ' '), '', strftime(' %I', $date)));
+            $datestring = str_replace('HH', $hourstring, $datestring);
         }
     } else {
         $date += (int)($timezone * 3600);
+        $datestring = gmstrftime($format, $date);
         if ($fixday) {
-            $datestring = gmstrftime($formatnoday, $date);
             $daystring  = ltrim(str_replace(array(' 0', ' '), '', gmstrftime(' %d', $date)));
             $datestring = str_replace('DD', $daystring, $datestring);
-        } else {
-            $datestring = gmstrftime($format, $date);
+        }
+        if ($fixhour) {
+            $hourstring = ltrim(str_replace(array(' 0', ' '), '', gmstrftime(' %I', $date)));
+            $datestring = str_replace('HH', $hourstring, $datestring);
         }
     }
 
@@ -1999,8 +2017,6 @@ function userdate($date, $format = '', $timezone = 99, $fixday = true) {
        }
     }
 
-    // When using the %l (12-hour time with no leading zero), it adds unwanted spaces
-    $datestring = trim(str_replace('  ', ' ', $datestring));
     return $datestring;
 }
 
@@ -7580,7 +7596,6 @@ function get_core_subsystems() {
             'license'     => NULL,
             'mathslib'    => NULL,
             'message'     => 'message',
-            'message'     => 'message',
             'mimetypes'   => NULL,
             'mnet'        => 'mnet',
             'moodle.org'  => NULL, // the dot is nasty, watch out! should be renamed to moodleorg
@@ -7915,7 +7930,7 @@ function plugin_callback($type, $name, $feature, $action, $params = null, $defau
  * @return mixed
  */
 function component_callback($component, $function, array $params = array(), $default = null) {
-    global $CFG; // this is needed for require_once() bellow
+    global $CFG; // this is needed for require_once() below
 
     $cleancomponent = clean_param($component, PARAM_COMPONENT);
     if (empty($cleancomponent)) {
index 600298b..8fe1042 100644 (file)
@@ -1854,6 +1854,7 @@ class global_navigation extends navigation_node {
             $cm = $modinfo->get_cm($cm->id);
         }
 
+        $activity->nodetype = navigation_node::NODETYPE_LEAF;
         $activity->make_active();
         $file = $CFG->dirroot.'/mod/'.$cm->modname.'/lib.php';
         $function = $cm->modname.'_extend_navigation';
@@ -1863,11 +1864,18 @@ class global_navigation extends navigation_node {
             if (function_exists($function)) {
                 $activtyrecord = $DB->get_record($cm->modname, array('id' => $cm->instance), '*', MUST_EXIST);
                 $function($activity, $course, $activtyrecord, $cm);
-                return true;
             }
         }
-        $activity->nodetype = navigation_node::NODETYPE_LEAF;
-        return false;
+
+        // Allow the active advanced grading method plugin to append module navigation
+        $featuresfunc = $cm->modname.'_supports';
+        if (function_exists($featuresfunc) && $featuresfunc(FEATURE_ADVANCED_GRADING)) {
+            require_once($CFG->dirroot.'/grade/grading/lib.php');
+            $gradingman = get_grading_manager($cm->context, $cm->modname);
+            $gradingman->extend_navigation($this, $activity);
+        }
+
+        return $activity->has_children();
     }
     /**
      * Loads user specific information into the navigation in the appropriate place.
@@ -1943,7 +1951,8 @@ class global_navigation extends navigation_node {
                 return false;
             }
             // Add a branch for the current user
-            $usernode = $usersnode->add(fullname($user, true), $userviewurl, self::TYPE_USER, null, $user->id);
+            $canseefullname = has_capability('moodle/site:viewfullnames', $coursecontext);
+            $usernode = $usersnode->add(fullname($user, $canseefullname), $userviewurl, self::TYPE_USER, null, $user->id);
 
             if ($this->page->context->contextlevel == CONTEXT_USER && $user->id == $this->page->context->instanceid) {
                 $usernode->make_active();
index 56fbe20..2737fe5 100644 (file)
@@ -468,7 +468,7 @@ class page_requirements_manager {
                     $module = array('name'     => 'core_dndupload',
                                     'fullpath' => '/lib/form/dndupload.js',
                                     'requires' => array('node', 'event', 'json'),
-                                    'strings'  => array(array('uploadformlimit', 'moodle')));
+                                    'strings'  => array(array('uploadformlimit', 'moodle'), array('droptoupload', 'moodle'), array('maxfilesreached', 'moodle')));
                     break;
             }
 
index 7990978..1a3fd3e 100644 (file)
@@ -1,86 +1,74 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
+ * This file contains the base classes that are extended to create portfolio export functionality.
  *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * For places in moodle that want to
+ * add export functionality to subclass from {@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page}
  *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This file contains the base classes for places in moodle that want to
- * add export functionality to subclass from.
- * See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>, Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
-* base class for callers
-*
-* See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page
-* {@see also portfolio_module_caller_base}
-*/
+ * Base class for callers
+ *
+ * @link See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page
+ * @see also portfolio_module_caller_base
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 abstract class portfolio_caller_base {
 
-    /**
-    * stdclass object
-    * course that was active during the caller
-    */
+    /** @var stdClass course active during the call */
     protected $course;
 
-    /**
-    * named array of export config
-    * use{@link  set_export_config} and {@link get_export_config} to access
-    */
+    /** @var array configuration used for export. Use set_export_config and get_export_config to access */
     protected $exportconfig = array();
 
-    /**
-    * stdclass object
-    * user currently exporting content
-    */
+    /** @var stdclass user currently exporting content */
     protected $user;
 
-    /**
-    * a reference to the exporter object
-    */
+    /** @var stdClass a reference to the exporter object */
     protected $exporter;
 
-    /**
-    * this can be overridden in subclasses constructors if they want
-    */
+    /** @var array can be optionally overridden by subclass constructors */
     protected $supportedformats;
 
-    /**
-    * set this for single file exports
-    */
+    /** @var stored_file single file exports configuration*/
     protected $singlefile;
 
-    /**
-    * set this for multi file exports
-    */
+    /** @var stored_file|object set this for multi file exports */
     protected $multifiles;
 
-    /**
-     * set this for generated-file exports
-     */
+    /** @var string set this for generated-file exports */
     protected $intendedmimetype;
 
+    /**
+     * Create portfolio_caller object
+     *
+     * @param array $callbackargs argument properties
+     */
     public function __construct($callbackargs) {
         $expected = call_user_func(array(get_class($this), 'expected_callbackargs'));
         foreach ($expected as $key => $required) {
@@ -96,51 +84,49 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * if this caller wants any additional config items
-    * they should be defined here.
-    *
-    * @param array $mform moodleform object (passed by reference) to add elements to
-    * @param object $instance subclass of portfolio_plugin_base
-    * @param integer $userid id of user exporting content
-    */
+     * If this caller wants any additional config items,
+     * they should be defined here.
+     *
+     * @param moodleform $mform passed by reference, add elements to it.
+     * @param portfolio_plugin_base $instance subclass of portfolio_plugin_base
+     */
     public function export_config_form(&$mform, $instance) {}
 
 
     /**
-    * whether this caller wants any additional
-    * config during export (eg options or metadata)
-    *
-    * @return boolean
-    */
+     * Whether this caller wants any additional
+     * config during export (eg options or metadata)
+     *
+     * @return bool
+     */
     public function has_export_config() {
         return false;
     }
 
     /**
-    * just like the moodle form validation function
-    * this is passed in the data array from the form
-    * and if a non empty array is returned, form processing will stop.
-    *
-    * @param array $data data from form.
-    * @return array keyvalue pairs - form element => error string
-    */
+     * Just like the moodle form validation function,
+     * this is passed in the data array from the form
+     * and if a non empty array is returned, form processing will stop.
+     *
+     * @param array $data data from form.
+     */
     public function export_config_validation($data) {}
 
     /**
-    * how long does this reasonably expect to take..
-    * should we offer the user the option to wait..
-    * this is deliberately nonstatic so it can take filesize into account
-    * the portfolio plugin can override this.
-    * (so for example even if a huge file is being sent,
-    * the download portfolio plugin doesn't care )
-    *
-    * @return string (see PORTFOLIO_TIME_* constants)
-    */
+     * How long does this reasonably expect to take..
+     * Should we offer the user the option to wait..?
+     * This is deliberately nonstatic so it can take filesize into account
+     * the portfolio plugin can override this.
+     * (so for example even if a huge file is being sent,
+     * the download portfolio plugin doesn't care )
+     */
     public abstract function expected_time();
 
     /**
-    * helper method to calculate expected time for multi or single file exports
-    */
+     * Helper method to calculate expected time for multi or single file exports
+     *
+     * @return string file time expectation
+     */
     public function expected_time_file() {
         if ($this->multifiles) {
             return portfolio_expected_time_file($this->multifiles);
@@ -152,25 +138,20 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * used for displaying the navigation during the export screens.
-    *
-    * this function must be implemented, but can really return anything.
-    * an Exporting.. string will be added on the end.
-    * @return array of $extranav and $cm
-    *
-    * to pass to build_navigation
-    *
-    */
+     * Function to build navigation
+     */
     public abstract function get_navigation();
 
     /**
-    *
-    */
+     * Helper function to get sha1
+     */
     public abstract function get_sha1();
 
     /**
-    * helper function to calculate the sha1 for multi or single file exports
-    */
+     * Helper function to calculate the sha1 for multi or single file exports
+     *
+     * @return string sha1 file exports
+     */
     public function get_sha1_file() {
         if (empty($this->singlefile) && empty($this->multifiles)) {
             throw new portfolio_caller_exception('invalidsha1file', 'portfolio', $this->get_return_url());
@@ -186,11 +167,15 @@ abstract class portfolio_caller_base {
         return sha1(implode('', $sha1s));
     }
 
-    /*
-    * generic getter for properties belonging to this instance
-    * <b>outside</b> the subclasses
-    * like name, visible etc.
-    */
+    /**
+     * Generic getter for properties belonging to this instance
+     * <b>outside</b> the subclasses
+     * like name, visible etc.
+     *
+     * @param string $field property's name
+     * @return mixed
+     * @throws portfolio_export_exception
+     */
     public function get($field) {
         if (property_exists($this, $field)) {
             return $this->{$field};
@@ -200,11 +185,15 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * generic setter for properties belonging to this instance
-    * <b>outside</b> the subclass
-    * like name, visible, etc.
-    *
-    */
+     * Generic setter for properties belonging to this instance
+     * <b>outside</b> the subclass
+     * like name, visible, etc.
+     *
+     * @param string $field property's name
+     * @param mixed $value property's value
+     * @return bool
+     * @throws moodle_exception
+     */
     public final function set($field, &$value) {
         if (property_exists($this, $field)) {
             $this->{$field} =& $value;
@@ -216,12 +205,12 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * stores the config generated at export time.
-    * subclasses can retrieve values using
-    * {@link get_export_config}
-    *
-    * @param array $config formdata
-    */
+     * Stores the config generated at export time.
+     * Subclasses can retrieve values using
+     * @see get_export_config
+     *
+     * @param array $config formdata
+     */
     public final function set_export_config($config) {
         $allowed = array_merge(
             array('wait', 'hidewait', 'format', 'hideformat'),
@@ -237,11 +226,12 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * returns a particular export config value.
-    * subclasses shouldn't need to override this
-    *
-    * @param string key the config item to fetch
-    */
+     * Returns a particular export config value.
+     * Subclasses shouldn't need to override this
+     *
+     * @param string $key the config item to fetch
+     * @return null|mixed of export configuration
+     */
     public final function get_export_config($key) {
         $allowed = array_merge(
             array('wait', 'hidewait', 'format', 'hideformat'),
@@ -258,47 +248,50 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * Similar to the other allowed_config functions
-    * if you need export config, you must provide
-    * a list of what the fields are.
-    *
-    * even if you want to store stuff during export
-    * without displaying a form to the user,
-    * you can use this.
-    *
-    * @return array array of allowed keys
-    */
+     * Similar to the other allowed_config functions
+     * if you need export config, you must provide
+     * a list of what the fields are.
+     * Even if you want to store stuff during export
+     * without displaying a form to the user,
+     * you can use this.
+     *
+     * @return array array of allowed keys
+     */
     public function get_allowed_export_config() {
         return array();
     }
 
     /**
-    * after the user submits their config
-    * they're given a confirm screen
-    * summarising what they've chosen.
-    *
-    * this function should return a table of nice strings => values
-    * of what they've chosen
-    * to be displayed in a table.
-    *
-    * @return array array of config items.
-    */
+     * After the user submits their config,
+     * they're given a confirm screen
+     * summarising what they've chosen.
+     * This function should return a table of nice strings => values
+     * of what they've chosen
+     * to be displayed in a table.
+     *
+     * @return bool
+     */
     public function get_export_summary() {
         return false;
     }
 
     /**
-    * called before the portfolio plugin gets control
-    * this function should copy all the files it wants to
-    * the temporary directory, using {@see copy_existing_file}
-    * or {@see write_new_file}
-    */
+     * Called before the portfolio plugin gets control.
+     * This function should copy all the files it wants to
+     * the temporary directory, using copy_existing_file
+     * or write_new_file
+     *
+     * @see copy_existing_file()
+     * @see write_new_file()
+     */
     public abstract function prepare_package();
 
     /**
-    * helper function to copy files into the temp area
-    * for single or multi file exports.
-    */
+     * Helper function to copy files into the temp area
+     * for single or multi file exports.
+     *
+     * @return stored_file|bool
+     */
     public function prepare_package_file() {
         if (empty($this->singlefile) && empty($this->multifiles)) {
             throw new portfolio_caller_exception('invalidpreparepackagefile', 'portfolio', $this->get_return_url());
@@ -312,15 +305,10 @@ abstract class portfolio_caller_base {
     }
 
     /**
-    * array of formats this caller supports
-    * the intersection of what this function returns
-    * and what the selected portfolio plugin supports
-    * will be used
-    * use the constants PORTFOLIO_FORMAT_*
-    *
-    * @return array list of formats
-    *
-    */
+     * Array of formats this caller supports.
+     *
+     * @return array list of formats
+     */
     public final function supported_formats() {
         $basic = $this->base_supported_formats();
         if (empty($this->supportedformats)) {
@@ -334,45 +322,51 @@ abstract class portfolio_caller_base {
         return portfolio_most_specific_formats($specific, $basic);
     }
 
+    /**
+     * Base supported formats
+     *
+     * @throws coding_exception
+     */
     public static function base_supported_formats() {
         throw new coding_exception('base_supported_formats() method needs to be overridden in each subclass of portfolio_caller_base');
     }
 
     /**
-    * this is the "return to where you were" url
-    *
-    * @return string url
-    */
+     * This is the "return to where you were" url
+     */
     public abstract function get_return_url();
 
     /**
-    * callback to do whatever capability checks required
-    * in the caller (called during the export process
-    */
+     * Callback to do whatever capability checks required
+     * in the caller (called during the export process
+     */
     public abstract function check_permissions();
 
     /**
-    * nice name to display to the user about this caller location
-    */
+     * Clean name to display to the user about this caller location
+     */
     public static function display_name() {
         throw new coding_exception('display_name() method needs to be overridden in each subclass of portfolio_caller_base');
     }
 
     /**
-    * return a string to put at the header summarising this export
-    * by default, just the display name (usually just 'assignment' or something unhelpful
-    *
-    * @return string
-    */
+     * Return a string to put at the header summarising this export.
+     * By default, it just display the name (usually just 'assignment' or something unhelpful
+     *
+     * @return string
+     */
     public function heading_summary() {
         return get_string('exportingcontentfrom', 'portfolio', $this->display_name());
     }
 
+    /**
+     * Load data
+     */
     public abstract function load_data();
 
     /**
-     * set up the required files for this export.
-     * this supports either passing files directly
+     * Set up the required files for this export.
+     * This supports either passing files directly
      * or passing area arguments directly through
      * to the files api using file_storage::get_area_files
      *
@@ -381,12 +375,7 @@ abstract class portfolio_caller_base {
      *                   - single stored_file object
      *                   - array of file ids or stored_file objects
      *                   - null
-     * @param int    $contextid   (optional), passed to {@link see file_storage::get_area_files}
-     * @param string $component   (optional), passed to {@link see file_storage::get_area_files}
-     * @param string $filearea    (optional), passed to {@link see file_storage::get_area_files}
-     * @param int    $itemid      (optional), passed to {@link see file_storage::get_area_files}
-     * @param string $sort        (optional), passed to {@link see file_storage::get_area_files}
-     * @param bool   $includedirs (optional), passed to {@link see file_storage::get_area_files}
+     * @return void
      */
     public function set_file_and_format_data($ids=null /* ..pass arguments to area files here. */) {
         $args = func_get_args();
@@ -426,10 +415,12 @@ abstract class portfolio_caller_base {
     }
 
     /**
-     * the button-location always knows best
+     * The button-location always knows best
      * what the formats are... so it should be trusted.
      *
+     * @todo MDL-31298 - re-analyze set_formats_from_button comment
      * @param array $formats array of PORTFOLIO_FORMAT_XX
+     * @return void
      */
     public function set_formats_from_button($formats) {
         $base = $this->base_supported_formats();
@@ -445,12 +436,11 @@ abstract class portfolio_caller_base {
     }
 
     /**
-     * adds a new format to the list of supported formats.
-     * handles removing conflicting and less specific
+     * Adds a new format to the list of supported formats.
+     * This functions also handles removing conflicting and less specific
      * formats at the same time.
      *
      * @param string $format one of PORTFOLIO_FORMAT_XX
-     *
      * @return void
      */
     protected function add_format($format) {
@@ -460,6 +450,11 @@ abstract class portfolio_caller_base {
         $this->supportedformats = portfolio_most_specific_formats(array($format), $this->supportedformats);
     }
 
+    /**
+     * Gets mimetype
+     *
+     * @return string
+     */
     public function get_mimetype() {
         if ($this->singlefile instanceof stored_file) {
             return $this->singlefile->get_mimetype();
@@ -469,15 +464,13 @@ abstract class portfolio_caller_base {
     }
 
     /**
-     * array of arguments the caller expects to be passed through to it
-     * this must be keyed on the argument name, and the array value is a boolean,
+     * Array of arguments the caller expects to be passed through to it.
+     * This must be keyed on the argument name, and the array value is a boolean,
      * whether it is required, or just optional
      * eg array(
      *     id            => true,
-     *     somethingelse => false,
+     *     somethingelse => false
      * )
-     *
-     * @return array
      */
     public static function expected_callbackargs() {
         throw new coding_exception('expected_callbackargs() method needs to be overridden in each subclass of portfolio_caller_base');
@@ -485,66 +478,69 @@ abstract class portfolio_caller_base {
 
 
     /**
-     * return the context for this export. used for $PAGE->set_context
+     * Return the context for this export. used for $PAGE->set_context
      *
-     * @return stdclass
+     * @param moodle_page $PAGE global page object
      */
     public abstract function set_context($PAGE);
 }
 
 /**
-* base class for module callers
-* this just implements a few of the abstract functions
-* from portfolio_caller_base so that caller authors
-* don't need to.
-*
-* See http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page
-* {@see also portfolio_caller_base}
-*/
+ * Base class for module callers.
+ *
+ * This just implements a few of the abstract functions
+ * from portfolio_caller_base so that caller authors
+ * don't need to.
+ * {@link http://docs.moodle.org/dev/Adding_a_Portfolio_Button_to_a_page}
+ * @see also portfolio_caller_base
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 abstract class portfolio_module_caller_base extends portfolio_caller_base {
 
-    /**
-    * coursemodule object
-    * set this in the constructor like
-    * $this->cm = get_coursemodule_from_instance('forum', $this->forum->id);
-    */
+    /** @var object coursemodule object. set this in the constructor like $this->cm = get_coursemodule_from_instance('forum', $this->forum->id); */
     protected $cm;
 
-    /**
-    *
-    * int cmid
-    */
+    /** @var int cmid */
     protected $id;
 
-    /**
-    * stdclass course object
-    */
+    /** @var stdclass course object */
     protected $course;
 
     /**
-    * navigation passed to print_header
-    * override this to do something more specific than the module view page
-    */
+     * Navigation passed to print_header.
+     * Override this to do something more specific than the module view page
+     *
+     * @return array
+     */
     public function get_navigation() {
         $extranav = array('name' => $this->cm->name, 'link' => $this->get_return_url());
         return array($extranav, $this->cm);
     }
 
     /**
-    * the url to return to after export or on cancel
-    * defaults to the module 'view' page
-    * override this if it's deeper inside the module
-    */
+     * The url to return to after export or on cancel.
+     * Defaults value is set to the module 'view' page.
+     * Override this if it's deeper inside the module.
+     *
+     * @return string
+     */
     public function get_return_url() {
         global $CFG;
         return $CFG->wwwroot . '/mod/' . $this->cm->modname . '/view.php?id=' . $this->cm->id;
     }
 
     /**
-    * override the parent get function
-    * to make sure when we're asked for a course
-    * we retrieve the object from the database as needed
-    */
+     * Override the parent get function
+     * to make sure when we're asked for a course,
+     * We retrieve the object from the database as needed.
+     *
+     * @param string $key the name of get function
+     * @return stdClass
+     */
     public function get($key) {
         if ($key != 'course') {
             return parent::get($key);
@@ -557,16 +553,20 @@ abstract class portfolio_module_caller_base extends portfolio_caller_base {
     }
 
     /**
-    * return a string to put at the header summarising this export
-    * by default, just the display name and the module instance name
-    * override this to do something more specific
-    */
+     * Return a string to put at the header summarising this export.
+     * by default, this function just display the name and module instance name.
+     * Override this to do something more specific
+     *
+     * @return string
+     */
     public function heading_summary() {
         return get_string('exportingcontentfrom', 'portfolio', $this->display_name() . ': ' . $this->cm->name);
     }
 
     /**
-     * overridden to return the course module context
+     * Overridden to return the course module context
+     *
+     * @param moodle_page $PAGE global PAGE
      */
     public function set_context($PAGE) {
         $PAGE->set_cm($this->cm);
index f7565b5..04e5965 100644 (file)
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains all the defined constants to do with portfolios.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>, Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
-// ************************************************** //
-// EXPORT STAGE CONSTANTS
-// ************************************************** //
+//EXPORT STAGE CONSTANTS
+
 
 /**
-* display a form to the user
-* this one might not be used if neither
-* the plugin, or the caller has any config.
-*/
+ * PORTFOLIO_STAGE_CONFIG - display a form to the user this one might not be
+ *                          used if neither the plugin, or the caller has any config.
+ */
 define('PORTFOLIO_STAGE_CONFIG', 1);
 
 /**
-* summarise the form and ask for confirmation
-* if we skipped PORTFOLIO_STAGE_CONFIG,
-* just confirm the send.
-*/
+ * PORTFOLIO_STAGE_CONFIRM - summarise the form and ask for confirmation
+ *                           if we skipped PORTFOLIO_STAGE_CONFIG,
+ *                           just confirm the send.
+ */
 define('PORTFOLIO_STAGE_CONFIRM', 2);
 
 /**
-* either queue the event and skip to PORTFOLIO_STAGE_FINISHED
-* or continue to PORTFOLIO_STAGE_PACKAGE
-*/
-
+ * PORTFOLIO_STAGE_QUEUEORWAIT - either queue the event and skip to PORTFOLIO_STAGE_FINISHED
+ */
 define('PORTFOLIO_STAGE_QUEUEORWAIT', 3);
 
 /**
-* package up the various bits
-* during this stage both the caller
-* and the plugin get their package methods called
-*/
+ * PORTFOLIO_STAGE_PACKAGE - package up the various bits during this stage both the caller
+ *                           and the plugin get their package methods called
+ */
 define('PORTFOLIO_STAGE_PACKAGE', 4);
 
-/*
-* the portfolio plugin must send the file
-*/
+/**
+ * PORTFOLIO_STAGE_SEND - the portfolio plugin must send the file
+ */
 define('PORTFOLIO_STAGE_SEND', 5);
 
 /**
-* cleanup the temporary area
-*/
+ * PORTFOLIO_STAGE_CLEANUP - cleanup the temporary area
+ */
 define('PORTFOLIO_STAGE_CLEANUP', 6);
 
 /**
-* display the "finished notification"
-*/
+ * PORTFOLIO_STAGE_FINISHED - display the "finished notification"
+ */
 define('PORTFOLIO_STAGE_FINISHED', 7);
 
 
 
-// ************************************************** //
+
 // EXPORT FORMAT CONSTANTS
-// these should always correspond to a string
-// in the portfolio module, called format_{$value}
-// ************************************************** //
+// These should always correspond to a string in the portfolio module, called format_{$value}
 
 
 /**
-* file - the most basic fallback format.
-* this should always be supported
-* in remote system.s
-*/
+ * PORTFOLIO_FORMAT_FILE - the most basic fallback format. this should always be supported
+ *                         in remote system.s
+ */
 define('PORTFOLIO_FORMAT_FILE', 'file');
 
 /**
-* moodle backup - the plugin needs to be able to write a complete backup
-* the caller need to be able to export the particular XML bits to insert
-* into moodle.xml (?and the file bits if necessary)
-*/
+ * PORTFOLIO_FORMAT_MBKP - the plugin needs to be able to write a complete backup
+ *                         the caller need to be able to export the particular XML bits to insert
+ *                         into moodle.xml (?and the file bits if necessary)
+ */
 define('PORTFOLIO_FORMAT_MBKP', 'mbkp');
 
 /**
-* richhtml - like html but with attachments.
-*/
+ * PORTFOLIO_FORMAT_RICHHTML - like html but with attachments.
+ */
 define('PORTFOLIO_FORMAT_RICHHTML', 'richhtml');
 
-
 /**
-* plainhtml - a single html representation - no attachments
-*/
+ * PORTFOLIO_FORMAT_PLAINHTML - a single html representation - no attachments
+ */
 define('PORTFOLIO_FORMAT_PLAINHTML', 'plainhtml');
 
 /**
-* image - subtype of file
-*/
+ * PORTFOLIO_FORMAT_IMAGE - subtype of file
+ */
 define('PORTFOLIO_FORMAT_IMAGE', 'image');
 
 /**
-* video - subtype of file
-*/
+ * PORTFOLIO_FORMAT_VIDEO - subtype of file
+ */
 define('PORTFOLIO_FORMAT_VIDEO', 'video');
 
 /**
-* text - subtype of file
-*/
+ * PORTFOLIO_FORMAT_TEXT - subtype of file
+ */
 define('PORTFOLIO_FORMAT_TEXT', 'text');
 
 /**
-* pdf - subtype of file
-*/
+ * PORTFOLIO_FORMAT_PDF - subtype of file
+ */
 define('PORTFOLIO_FORMAT_PDF', 'pdf');
 
 /**
-* document - subtype of file
-*/
+ * PORTFOLIO_FORMAT_DOCUMENT - subtype of file
+ */
 define('PORTFOLIO_FORMAT_DOCUMENT', 'document');
 
 /**
-* document - subtype of file
-*/
+ * PORTFOLIO_FORMAT_SPREADSHEET - subtype of file
+ */
 define('PORTFOLIO_FORMAT_SPREADSHEET', 'spreadsheet');
 
 /**
-* document - subtype of file
-*/
+ * PORTFOLIO_FORMAT_PRESENTATION - subtype of file
+ */
 define('PORTFOLIO_FORMAT_PRESENTATION', 'presentation');
 
 /**
- * abstract - just used to say, "we support all these"
+ * PORTFOLIO_FORMAT_RICH - just used to say, "we support all these"
  */
 define('PORTFOLIO_FORMAT_RICH', 'rich');
 
 /**
- * leap2a http://wiki.cetis.ac.uk/LEAP_2.0
- * supported by mahara and and others
+ * PORTFOLIO_FORMAT_LEAP2A - supported by mahara and and others {http://wiki.cetis.ac.uk/LEAP_2.0}
  */
 define('PORTFOLIO_FORMAT_LEAP2A', 'leap2a');
 
-// ************************************************** //
-//  EXPORT TIME LEVELS
-// these should correspond to a string
-// in the portfolio module, called time_{$value}
-// ************************************************** //
-
+// EXPORT TIME LEVELS
+// These should correspond to a string in the portfolio module, called time_{$value}
 
 /**
-* no delay. don't even offer the user the option
-* of not waiting for the transfer
-*/
+ * PORTFOLIO_TIME_LOW - no delay. don't even offer the user the option
+ *                      of not waiting for the transfer
+ */
 define('PORTFOLIO_TIME_LOW', 'low');
 
 /**
-* a small delay. user can still easily opt to
-* watch this transfer and wait.
-*/
+ * PORTFOLIO_TIME_MODERATE - a small delay. user can still easily opt to
+ *                           watch this transfer and wait.
+ */
 define('PORTFOLIO_TIME_MODERATE', 'moderate');
 
 /**
-* slow. the user really should not be given the option
-* to choose this.
-*/
+ * PORTFOLIO_TIME_HIGH - slow. the user really should not be given the option
+ *                       to choose this.
+ */
 define('PORTFOLIO_TIME_HIGH', 'high');
 
 /**
-* very slow, or immediate transfers not supported
-*/
+ * PORTFOLIO_TIME_FORCEQUEUE - very slow, or immediate transfers not supported
+ */
 define('PORTFOLIO_TIME_FORCEQUEUE', 'queue');
 
-// ************************************************** //
-// BUTTON FORMATS
-// available ways to add the portfolio export to a page
-// ************************************************** //
+ // BUTTON FORMATS
+ // Available ways to add the portfolio export to a page
 
 /**
-* a whole form, containing a drop down menu (where necessary)
-* and a submit button
-*/
+ * PORTFOLIO_ADD_FULL_FORM - a whole form, containing a drop down menu (where necessary)
+ *                           and a submit button
+ */
 define('PORTFOLIO_ADD_FULL_FORM', 1);
 
 
 /**
-* a whole form, containing a drop down menu (where necessary)
-* but has an icon instead of a button to submit
-*/
+ * PORTFOLIO_ADD_ICON_FORM - a whole form, containing a drop down menu (where necessary)
+ *                           but has an icon instead of a button to submit
+ */
 define('PORTFOLIO_ADD_ICON_FORM', 2);
 
 /**
-* just an icon with a link around it (yuk, as will result in a long url
-* only use where necessary)
-*/
+ * PORTFOLIO_ADD_ICON_LINK - just an icon with a link around it (yuk, as will result in a long url
+ *                           only use where necessary)
+ */
 define('PORTFOLIO_ADD_ICON_LINK', 3);
 
 /**
-* just some text with a link around it (yuk, as will result in a long url
-* only use where necessary)
-*/
+ * PORTFOLIO_ADD_TEXT_LINK - just some text with a link around it (yuk, as will result in a long url
+ * only use where necessary)
+ */
 define('PORTFOLIO_ADD_TEXT_LINK', 4);
 
 /**
- * hacky way to turn the button class into a url to redirect to
- * this replaces the old portfolio_fake_add_url function
+ * PORTFOLIO_ADD_FAKE_URL - hacky way to turn the button class into a url to redirect to
+ *                          this replaces the old portfolio_fake_add_url function
  */
 define('PORTFOLIO_ADD_FAKE_URL', 5);
index d39e6d5..ba2ca56 100644 (file)
@@ -1,52 +1,61 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains all the portfolio exception classes.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,  Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
-* top level portfolio exception.
-* sometimes caught and rethrown as {@see portfolio_export_exception}
-*/
+ * Top level portfolio exception.
+ *
+ * Sometimes caught and re-thrown as portfolio_export_exception
+ * @see portfolio_export_exception
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_exception extends moodle_exception {}
 
 /**
-* exception to throw during an export - will clean up session and tempdata
-*/
+ * Exception to throw during an export - will clean up session and tempdata
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_export_exception extends portfolio_exception {
 
     /**
-    * constructor.
-    * @param object $exporter instance of portfolio_exporter (will handle null case)
-    * @param string $errorcode language string key
-    * @param string $module language string module (optional, defaults to moodle)
-    * @param string $continue url to continue to (optional, defaults to wwwroot)
-    * @param mixed $a language string data (optional, defaults to  null)
-    */
+     * Constructor.
+     *
+     * @param portfolio_exporter $exporter instance of portfolio_exporter (will handle null case)
+     * @param string $errorcode language string key
+     * @param string $module language string module (optional, defaults to moodle)
+     * @param string $continue url to continue to (optional, defaults to wwwroot)
+     * @param object $a language string data (optional, defaults to  null)
+     */
     public function __construct($exporter, $errorcode, $module=null, $continue=null, $a=null) {
         global $CFG;
         // This static variable is necessary because sometimes the code below
@@ -82,23 +91,47 @@ class portfolio_export_exception extends portfolio_exception {
 }
 
 /**
-* exception for callers to throw when they have a problem.
-* usually caught and rethrown as {@see portfolio_export_exception}
-*/
+ * Exception for callers to throw when they have a problem.
+ *
+ * Usually caught and rethrown as portfolio_export_exception
+ * @see portfolio_export_exception
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_caller_exception extends portfolio_exception {}
 
 /**
-* exception for portfolio plugins to throw when they have a problem.
-* usually caught and rethrown as {@see portfolio_export_exception}
-*/
+ * Exception for portfolio plugins to throw when they have a problem.
+ *
+ * Usually caught and rethrown as portfolio_export_exception
+ * @see portfolio_export_exception
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_plugin_exception extends portfolio_exception {}
 
 /**
-* exception for interacting with the button class
-*/
+ * Exception for interacting with the button class
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_button_exception extends portfolio_exception {}
 
 /**
- * leap2a exception - for invalid api calls
+ * Leap2a exception - for invalid api calls
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class portfolio_format_leap2a_exception extends portfolio_exception {}
index 9a836bc..81727f5 100644 (file)
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains the class definition for the exporter object.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ *            Martin Dougiamas  <http://dougiamas.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
-* The class that handles the various stages of the actual export
-* and the communication between the caller and the portfolio plugin.
-* this is stored in the database between page requests in serialized base64 encoded form
-* also contains helper methods for the plugin and caller to use (at the end of the file)
-* {@see get_base_filearea} - where to write files to
-* {@see write_new_file} - write some content to a file in the export filearea
-* {@see copy_existing_file} - copy an existing file into the export filearea
-* {@see get_tempfiles} - return list of all files in the export filearea
-*/
+ * The class that handles the various stages of the actual export
+ * and the communication between the caller and the portfolio plugin.
+ *
+ * This is stored in the database between page requests in serialized base64 encoded form
+ * also contains helper methods for the plugin and caller to use (at the end of the file)
+ * @see get_base_filearea - where to write files to
+ * @see write_new_file - write some content to a file in the export filearea
+ * @see copy_existing_file - copy an existing file into the export filearea
+ * @see get_tempfiles - return list of all files in the export filearea
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>
+ *            Martin Dougiamas  <http://dougiamas.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_exporter {
 
-    /**
-    * the caller object used during the export
-    */
+    /** @var portfolio_caller_base the caller object used during the export */
     private $caller;
 
-    /** the portfolio plugin instanced used during the export
-    */
+    /** @var portfolio_plugin_base the portfolio plugin instanced used during the export */
     private $instance;
 
-    /**
-    * if there has been no config form displayed to the user
-    */
+    /** @var bool if there has been no config form displayed to the user */
     private $noexportconfig;
 
     /**
-    * the user currently exporting content
-    * always $USER, but more conveniently placed here
-    */
+     * @var stdClass the user currently exporting content always $USER,
+     *               but more conveniently placed here
+     */
     private $user;
 
-    /** the file to include that contains the class defintion
-    * of the portfolio instance plugin
-    * used to re-waken the object after sleep
-    */
+    /**
+     * @var string the file to include that contains the class defintion of
+     *             the portfolio instance plugin used to re-waken the object after sleep
+     */
     public $instancefile;
 
     /**
-    * the file to include that contains the class definition
-    * of the caller object
-    * used to re-waken the object after sleep
-    */
+     * @var string the file to include that contains the class definition of
+     *             the caller object used to re-waken the object after sleep
+     */
     public $callerfile;
 
-    /**
-    * the current stage of the export
-    */
+    /** @var int the current stage of the export */
     private $stage;
 
-    /**
-    * whether something (usually the portfolio plugin)
-    * has forced queuing
-    */
+    /** @var bool whether something (usually the portfolio plugin) has forced queuing */
     private $forcequeue;
 
     /**
-    * id of this export
-    * matches record in portfolio_tempdata table
-    * and used for itemid for file storage.
-    */
+     * @var int id of this export matches record in portfolio_tempdata table
+     *          and used for itemid for file storage.
+     */
     private $id;
 
-    /**
-    * array of stages that have had the portfolio plugin already steal control from them
-    */
+    /** @var array of stages that have had the portfolio plugin already steal control from them */
     private $alreadystolen;
 
     /**
-    * files that the exporter has written to this temp area
-    * keep track of this in case of duplicates within one export
-    * see MDL-16390
-    */
+     * @var stored_file files that the exporter has written to this temp area keep track of
+     *                  this in case of duplicates within one export see MDL-16390
+     */
     private $newfilehashes;
 
     /**
-    * selected exportformat
-    * this is also set in export_config in the portfolio and caller classes
-    */
+     * @var string selected exportformat this is also set in
+     *             export_config in the portfolio and caller classes
+     */
     private $format;
 
-    /**
-     * queued - this is set after the event is triggered
-     */
+    /** @var bool queued - this is set after the event is triggered */
     private $queued = false;
 
-    /**
-     * expiry time - set the first time the object is saved out
-     */
+    /** @var int expiry time - set the first time the object is saved out */
     private $expirytime;
 
     /**
-     * deleted - this is set during the cleanup routine
-     * so that subsequent save() calls can detect it
+     * @var bool deleted - this is set during the cleanup routine so
+     *           that subsequent save() calls can detect it
      */
     private $deleted = false;
 
     /**
-    * construct a new exporter for use
-    *
-    * @param portfolio_plugin_base subclass $instance portfolio instance (passed by reference)
-    * @param portfolio_caller_base subclass $caller portfolio caller (passed by reference)
-    * @param string $callerfile path to callerfile (relative to dataroot)
-    */
+     * Construct a new exporter for use
+     *
+     * @param portfolio_plugin_base $instance portfolio instance (passed by reference)
+     * @param portfolio_caller_base $caller portfolio caller (passed by reference)
+     * @param string $callerfile path to callerfile (relative to dataroot)
+     */
     public function __construct(&$instance, &$caller, $callerfile) {
         $this->instance =& $instance;
         $this->caller =& $caller;
@@ -146,11 +131,13 @@ class portfolio_exporter {
         $this->newfilehashes = array();
     }
 
-    /*
-    * generic getter for properties belonging to this instance
-    * <b>outside</b> the subclasses
-    * like name, visible etc.
-    */
+    /**
+     * Generic getter for properties belonging to this instance
+     * <b>outside</b> the subclasses like name, visible etc.
+     *
+     * @param string $field property's name
+     * @return portfolio_format|mixed
+     */
     public function get($field) {
         if ($field == 'format') {
             return portfolio_format_object($this->format);
@@ -165,10 +152,14 @@ class portfolio_exporter {
     }
 
     /**
-    * generic setter for properties belonging to this instance
-    * <b>outside</b> the subclass
-    * like name, visible, etc.
-    */
+     * Generic setter for properties belonging to this instance
+     * <b>outside</b> the subclass like name, visible, etc.
+     *
+     * @param string $field property's name
+     * @param mixed $value property's value
+     * @return bool
+     * @throws portfolio_export_exception
+     */
     public function set($field, &$value) {
         if (property_exists($this, $field)) {
             $this->{$field} =& $value;
@@ -185,23 +176,22 @@ class portfolio_exporter {
     }
 
     /**
-    * sets this export to force queued
-    * sometimes plugins need to set this randomly
-    * if an external system changes its mind
-    * about what's supported
-    */
+     * Sets this export to force queued.
+     * Sometimes plugins need to set this randomly
+     * if an external system changes its mind
+     * about what's supported
+     */
     public function set_forcequeue() {
         $this->forcequeue = true;
     }
 
     /**
-    * process the given stage calling whatever functions are necessary
-    *
-    * @param int $stage (see PORTFOLIO_STAGE_* constants)
-    * @param boolean $alreadystolen used to avoid letting plugins steal control twice.
-    *
-    * @return boolean whether or not to process the next stage. this is important as the function is called recursively.
-    */
+     * Process the given stage calling whatever functions are necessary
+     *
+     * @param int $stage (see PORTFOLIO_STAGE_* constants)
+     * @param bool $alreadystolen used to avoid letting plugins steal control twice.
+     * @return bool whether or not to process the next stage. this is important as the function is called recursively.
+     */
     public function process_stage($stage, $alreadystolen=false) {
         $this->set('stage', $stage);
         if ($alreadystolen) {
@@ -259,28 +249,28 @@ class portfolio_exporter {
     }
 
     /**
-    * helper function to return the portfolio instance
-    *
-    * @return  portfolio_plugin_base subclass
-    */
+     * Helper function to return the portfolio instance
+     *
+     * @return portfolio_plugin_base subclass
+     */
     public function instance() {
         return $this->instance;
     }
 
     /**
-    * helper function to return the caller object
-    *
-    * @return portfolio_caller_base subclass
-    */
+     * Helper function to return the caller object
+     *
+     * @return portfolio_caller_base subclass
+     */
     public function caller() {
         return $this->caller;
     }
 
     /**
-    * processes the 'config' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'config' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_config() {
         global $OUTPUT, $CFG;
         $pluginobj = $callerobj = null;
@@ -368,10 +358,10 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'confirm' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'confirm' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_confirm() {
         global $CFG, $DB, $OUTPUT;
 
@@ -433,10 +423,10 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'queueornext' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'queueornext' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_queueorwait() {
         $wait = $this->instance->get_export_config('wait');
         if (empty($wait)) {
@@ -448,10 +438,11 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'package' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'package' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     * @throws portfolio_export_exception
+     */
     public function process_stage_package() {
         // now we've agreed on a format,
         // the caller is given control to package it up however it wants
@@ -477,12 +468,12 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'cleanup' stage of the export
-    *
-    * @param boolean $pullok normally cleanup is deferred for pull plugins until after the file is requested from portfolio/file.php
-    *                        if you want to clean up earlier, pass true here (defaults to false)
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'cleanup' stage of the export
+     *
+     * @param bool $pullok normally cleanup is deferred for pull plugins until after the file is requested from portfolio/file.php
+     *                        if you want to clean up earlier, pass true here (defaults to false)
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_cleanup($pullok=false) {
         global $CFG, $DB;
 
@@ -501,10 +492,10 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'send' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'send' stage of the export
+     *
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_send() {
         // send the file
         try {
@@ -523,10 +514,11 @@ class portfolio_exporter {
     }
 
     /**
-    * log the transfer
-    * this should only be called after the file has been sent
-    * either via push, or sent from a pull request.
-    */
+     * Log the transfer
+     *
+     * this should only be called after the file has been sent
+     * either via push, or sent from a pull request.
+     */
     public function log_transfer() {
         global $DB;
         $l = array(
@@ -544,8 +536,10 @@ class portfolio_exporter {
     }
 
     /**
-     * in some cases (mahara) we need to update this after the log has been done
+     * In some cases (mahara) we need to update this after the log has been done
      * because of MDL-20872
+     *
+     * @param string $url link to be recorded to portfolio log
      */
     public function update_log_url($url) {
         global $DB;
@@ -553,10 +547,11 @@ class portfolio_exporter {
     }
 
     /**
-    * processes the 'finish' stage of the export
-    *
-    * @return boolean whether or not to process the next stage. this is important as the control function is called recursively.
-    */
+     * Processes the 'finish' stage of the export
+     *
+     * @param bool $queued let the process to be queued
+     * @return bool whether or not to process the next stage. this is important as the control function is called recursively.
+     */
     public function process_stage_finished($queued=false) {
         global $OUTPUT;
         $returnurl = $this->caller->get_return_url();
@@ -578,10 +573,12 @@ class portfolio_exporter {
 
 
     /**
-    * local print header function to be reused across the export
-    *
-    * @param string $headerstring full language string
-    */
+     * Local print header function to be reused across the export
+     *
+     * @param string $headingstr full language string
+     * @param bool $summary (optional) to print summary, default is set to true
+     * @return void
+     */
     public function print_header($headingstr, $summary=true) {
         global $OUTPUT, $PAGE;
         $titlestr = get_string('exporting', 'portfolio');
@@ -609,9 +606,13 @@ class portfolio_exporter {
     }
 
     /**
-    * cancels a potfolio request and cleans up the tempdata
-    * and redirects the user back to where they started
-    */
+     * Cancels a potfolio request and cleans up the tempdata
+     * and redirects the user back to where they started
+     *
+     * @param bool $logreturn options to return to porfolio log or caller return page
+     * @return void
+     * @uses exit
+     */
     public function cancel_request($logreturn=false) {
         global $CFG;
         if (!isset($this)) {
@@ -626,8 +627,10 @@ class portfolio_exporter {
     }
 
     /**
-    * writes out the contents of this object and all its data to the portfolio_tempdata table and sets the 'id' field.
-    */
+     * Writes out the contents of this object and all its data to the portfolio_tempdata table and sets the 'id' field.
+     *
+     * @return void
+     */
     public function save() {
         global $DB;
         if (empty($this->id)) {
@@ -654,13 +657,12 @@ class portfolio_exporter {
     }
 
     /**
-    * rewakens the data from the database given the id
-    * makes sure to load the required files with the class definitions
-    *
-    * @param int $id id of data
-    *
-    * @return portfolio_exporter
-    */
+     * Rewakens the data from the database given the id.
+     * Makes sure to load the required files with the class definitions
+     *
+     * @param int $id id of data
+     * @return portfolio_exporter
+     */
     public static function rewaken_object($id) {
         global $DB, $CFG;
         require_once($CFG->libdir . '/filelib.php');
@@ -692,12 +694,15 @@ class portfolio_exporter {
     }
 
     /**
-    * helper function to create the beginnings of a file_record object
-    * to create a new file in the portfolio_temporary working directory
-    * use {@see write_new_file} or {@see copy_existing_file} externally
-    *
-    * @param string $name filename of new record
-    */
+     * Helper function to create the beginnings of a file_record object
+     * to create a new file in the portfolio_temporary working directory.
+     * Use write_new_file or copy_existing_file externally
+     * @see write_new_file
+     * @see copy_existing_file
+     *
+     * @param string $name filename of new record
+     * @return object
+     */
     private function new_file_record_base($name) {
         return (object)array_merge($this->get_base_filearea(), array(
             'filepath' => '/',
@@ -706,15 +711,12 @@ class portfolio_exporter {
     }
 
     /**
-    * verifies a rewoken object
-    *
-    * checks to make sure it belongs to the same user and session as is currently in use.
-    *
-    * @param boolean $readonly if we're reawakening this for a user to just display in the log view, don't verify the sessionkey
-    *                          when continuing transfers, you must pass false here.
-    *
-    * @throws portfolio_exception
-    */
+     * Verifies a rewoken object.
+     * Checks to make sure it belongs to the same user and session as is currently in use.
+     *
+     * @param bool $readonly if we're reawakening this for a user to just display in the log view, don't verify the sessionkey
+     * @throws portfolio_exception
+     */
     public function verify_rewaken($readonly=false) {
         global $USER, $CFG;
         if ($this->get('user')->id != $USER->id) { // make sure it belongs to the right user
@@ -735,13 +737,13 @@ class portfolio_exporter {
         }
     }
     /**
-    * copies a file from somewhere else in moodle
-    * to the portfolio temporary working directory
-    * associated with this export
-    *
-    * @param $oldfile stored_file object
-    * @return stored_file new file object
-    */
+     * Copies a file from somewhere else in moodle
+     * to the portfolio temporary working directory
+     * associated with this export
+     *
+     * @param stored_file $oldfile existing stored file object
+     * @return stored_file|bool new file object
+     */
     public function copy_existing_file($oldfile) {
         if (array_key_exists($oldfile->get_contenthash(), $this->newfilehashes)) {
             return $this->newfilehashes[$oldfile->get_contenthash()];
@@ -761,15 +763,15 @@ class portfolio_exporter {
     }
 
     /**
-    * writes out some content to a file in the
-    * portfolio temporary working directory
-    * associated with this export
-    *
-    * @param string $content content to write
-    * @param string $name filename to use
-    * @param bool $maifest whether this is the main file or an secondary file (eg attachment)
-    * @return stored_file new file object
-    */
+     * Writes out some content to a file
+     * in the portfolio temporary working directory
+     * associated with this export.
+     *
+     * @param string $content content to write
+     * @param string $name filename to use
+     * @param bool $manifest whether this is the main file or an secondary file (eg attachment)
+     * @return stored_file
+     */
     public function write_new_file($content, $name, $manifest=true) {
         $fs = get_file_storage();
         $file_record = $this->new_file_record_base($name);
@@ -780,13 +782,12 @@ class portfolio_exporter {
     }
 
     /**
-    * zips all files in the temporary directory
-    *
-    * @param string $filename name of resulting zipfile (optional, defaults to portfolio-export.zip
-    * @param string $filepath subpath in the filearea (optional, defaults to final)
-    *
-    * @return stored_file resulting stored_file object
-    */
+     * Zips all files in the temporary directory
+     *
+     * @param string $filename name of resulting zipfile (optional, defaults to portfolio-export.zip)
+     * @param string $filepath subpath in the filearea (optional, defaults to final)
+     * @return stored_file|bool resulting stored_file object, or false
+     */
     public function zip_tempfiles($filename='portfolio-export.zip', $filepath='/final/') {
         $zipper = new zip_packer();
 
@@ -799,12 +800,13 @@ class portfolio_exporter {
     }
 
     /**
-    * returns an arary of files in the temporary working directory
-    * for this export
-    * always use this instead of the files api directly
-    *
-    * @return array of stored_file objects keyed by name
-    */
+     * Returns an arary of files in the temporary working directory
+     * for this export.
+     * Always use this instead of the files api directly
+     *
+     * @param string $skipfile name of the file to be skipped
+     * @return array of stored_file objects keyed by name
+     */
     public function get_tempfiles($skipfile='portfolio-export.zip') {
         $fs = get_file_storage();
         $files = $fs->get_area_files(SYSCONTEXTID, 'portfolio', 'exporter', $this->id, '', false);
@@ -822,14 +824,14 @@ class portfolio_exporter {
     }
 
     /**
-    * returns the context, filearea, and itemid
-    * parts of a filearea (not filepath) to be used by
-    * plugins if they want to do things like zip up the contents of
-    * the temp area to here, or something that can't be done just using
-    * write_new_file,  copy_existing_file or get_tempfiles
-    *
-    * @return array contextid, filearea, itemid are the keys.
-    */
+     * Returns the context, filearea, and itemid.
+     * Parts of a filearea (not filepath) to be used by
+     * plugins if they want to do things like zip up the contents of
+     * the temp area to here, or something that can't be done just using
+     * write_new_file, copy_existing_file or get_tempfiles
+     *
+     * @return array contextid, filearea, itemid are the keys.
+     */
     public function get_base_filearea() {
         return array(
             'contextid' => SYSCONTEXTID,
@@ -839,11 +841,13 @@ class portfolio_exporter {
         );
     }
 
-    /** wrapper function to print a friendly error to users
-    *
-    * this is generally caused by them hitting an expired transfer
-    * through the usage of the backbutton
-    */
+    /**
+     * Wrapper function to print a friendly error to users
+     * This is generally caused by them hitting an expired transfer
+     * through the usage of the backbutton
+     *
+     * @uses exit
+     */
     public static function print_expired_export() {
         global $CFG, $OUTPUT, $PAGE;
         $title = get_string('exportexpired', 'portfolio');
@@ -857,6 +861,13 @@ class portfolio_exporter {
         exit;
     }
 
+    /**
+     * Wrapper function to print a friendly error to users
+     *
+     * @param stdClass $log portfolio_log object
+     * @param portfolio_plugin_base $instance portfolio instance
+     * @uses exit
+     */
     public static function print_cleaned_export($log, $instance=null) {
         global $CFG, $OUTPUT, $PAGE;
         if (empty($instance) || !$instance instanceof portfolio_plugin_base) {
@@ -874,6 +885,13 @@ class portfolio_exporter {
         exit;
     }
 
+    /**
+     * Wrapper function to print continue and/or return link
+     *
+     * @param string $returnurl link to previos page
+     * @param string $continueurl continue to next page
+     * @param array $extras (optional) other links to be display.
+     */
     public static function print_finish_info($returnurl, $continueurl, $extras=null) {
         if ($returnurl) {
             echo '<a href="' . $returnurl . '">' . get_string('returntowhereyouwere', 'portfolio') . '</a><br />';
index c462daa..56f6ece 100644 (file)
@@ -1,75 +1,93 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@catalyst.net.nz>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
  * This file contains all the class definitions of the export formats.
+ *
  * They are implemented in php classes rather than just a simpler hash
  * Because it provides an easy way to do subtyping using php inheritance.
+ *
+ * @package core_portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
+ *                 Martin Dougiamas <http://dougiamas.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
- * base class to inherit from
- * do not use this anywhere in supported_formats
+ * Base class to inherit from.
+ *
+ * Do not use this anywhere in supported_formats
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach <penny@catalyst.net.nz>,
+ *                 Martin Dougiamas <http://dougiamas.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
  */
 abstract class portfolio_format {
 
     /**
-     * array of mimetypes this format supports
+     * Array of mimetypes this format supports
+     *
+     * @throws coding_exception
      */
     public static function mimetypes() {
         throw new coding_exception('mimetypes() method needs to be overridden in each subclass of portfolio_format');
     }
 
     /**
-     * for multipart formats, eg html with attachments,
-     * we need to have a directory to place associated files in
-     * inside the zip file. this is the name of that directory
+     * For multipart formats, eg html with attachments,
+     * we need to have a directory to place associated files from
+     * inside the zip file. This is the name of that directory
+     *
+     * @throws coding_exception
      */
     public static function get_file_directory() {
         throw new coding_exception('get_file_directory() method needs to be overridden in each subclass of portfolio_format');
     }
 
     /**
-     * given a file, return a snippet of markup in whatever format
+     * Given a file, return a snippet of markup in whatever format
      * to link to that file.
-     * usually involves the path given by {@link get_file_directory}
-     * this is not supported in subclasses of portfolio_format_file
+     * Usually involves the path given by get_file_directory.
+     * This is not supported in subclasses of portfolio_format_file
      * since they're all just single files.
+     * @see get_file_directory
      *
-     * @param stored_file $file
-     * @param array       $options array of options to pass. can contain:
+     * @param stored_file $file file information object
+     * @param array $options array of options to pass. can contain:
      *              attributes => hash of existing html attributes (eg title, height, width, etc)
-     *                    and whatever the sub class adds into this list
      *
-     * @return string some html or xml or whatever
+     * @throws coding_exception
      */
     public static function file_output($file, $options=null) {
         throw new coding_exception('file_output() method needs to be overridden in each subclass of portfolio_format');
     }
 
+    /**
+     * Create portfolio tag
+     *
+     * @param stored_file $file file information object
+     * @param string $path file path
+     * @param array $attributes portfolio attributes
+     * @return string
+     */
     public static function make_tag($file, $path, $attributes) {
         $srcattr = 'href';
         $tag     = 'a';
@@ -97,23 +115,21 @@ abstract class portfolio_format {
     }
 
     /**
-     * whether this format conflicts with the given format
-     * this is used for the case where an export location
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
      * "generally" supports something like FORMAT_PLAINHTML
-     * but then in a specific export case, must add attachments
-     * which means that FORMAT_RICHHTML is supported in that case
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
      * which implies removing support for FORMAT_PLAINHTML.
      * Note that conflicts don't have to be bi-directional
      * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
      * but not the other way around) and things within the class hierarchy
      * are resolved automatically anyway.
-     *
      * This is really just between subclasses of format_rich
      * and subclasses of format_file.
      *
      * @param string $format one of the FORMAT_XX constants
-     *
-     * @return boolean
+     * @return bool
      */
     public static function conflicts($format) {
         return false;
@@ -121,34 +137,87 @@ abstract class portfolio_format {
 }
 
 /**
-* the most basic type - pretty much everything is a subtype
-*/
+ * The most basic type - pretty much everything is a subtype
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach <penny@catalyst.net.nz>, Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_file extends portfolio_format {
 
+    /**
+     * Array of mimetypes this format supports
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array();
     }
 
+    /**
+     * For multipart formats, eg html with attachments,
+     * we need to have a directory to place associated files from
+     * inside the zip file. This is the name of that directory
+     *
+     * @return bool
+     */
     public static function get_file_directory() {
         return false;
     }
 
+    /**
+     * Given a file, return a snippet of markup in whatever format
+     * to link to that file.
+     * Usually involves the path given by get_file_directory.
+     * This is not supported in subclasses of portfolio_format_file
+     * since they're all just single files.
+     * @see get_file_directory
+     *
+     * @param stored_file $file informations object
+     * @param array $options array of options to pass. can contain:
+     *              attributes => hash of existing html attributes (eg title, height, width, etc)
+     */
     public static function file_output($file, $options=null) {
         throw new portfolio_exception('fileoutputnotsupported', 'portfolio');
     }
 }
 
 /**
-* image format, subtype of file.
-*/
+ * Image format, subtype of file.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_image extends portfolio_format_file {
     /**
-     * return all mimetypes that use image.gif (eg all images)
+     * Return all mimetypes that use image.gif (eg all images)
+     *
+     * @return string
      */
     public static function mimetypes() {
         return mimeinfo_from_icon('type', 'image', true);
     }
 
+    /**
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
+     * "generally" supports something like FORMAT_PLAINHTML
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
+     * which implies removing support for FORMAT_PLAINHTML.
+     * Note that conflicts don't have to be bi-directional
+     * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
+     * but not the other way around) and things within the class hierarchy
+     * are resolved automatically anyway.
+     * This is really just between subclasses of format_rich
+     * and subclasses of format_file.
+     *
+     * @param string $format one of the FORMAT_XX constants
+     * @return bool
+     */
     public static function conflicts($format) {
         return ($format == PORTFOLIO_FORMAT_RICHHTML
             || $format == PORTFOLIO_FORMAT_PLAINHTML);
@@ -156,16 +225,43 @@ class portfolio_format_image extends portfolio_format_file {
 }
 
 /**
-* html format - could be used for an external cms or something
-*
-* in case we want to be really specific.
-*/
+ * HTML format
+ *
+ * Could be used for an external cms or something in case we want to be really specific.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_plainhtml extends portfolio_format_file {
 
+    /**
+     * Return html mimetype
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array('text/html');
     }
 
+    /**
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
+     * "generally" supports something like FORMAT_PLAINHTML
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
+     * which implies removing support for FORMAT_PLAINHTML.
+     * Note that conflicts don't have to be bi-directional
+     * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
+     * but not the other way around) and things within the class hierarchy
+     * are resolved automatically anyway.
+     * This is really just between subclasses of format_rich
+     * and subclasses of format_file.
+     *
+     * @param string $format one of the FORMAT_XX constants
+     * @return bool
+     */
     public static function conflicts($format) {
         return ($format == PORTFOLIO_FORMAT_RICHHTML
             || $format == PORTFOLIO_FORMAT_FILE);
@@ -173,11 +269,22 @@ class portfolio_format_plainhtml extends portfolio_format_file {
 }
 
 /**
-* video format, subtype of file.
-*
-* for portfolio plugins that support videos specifically
-*/
+ * Video format
+ *
+ * For portfolio plugins that support videos specifically
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_video extends portfolio_format_file {
+
+     /**
+      * Return video mimetypes
+      *
+      * @return array
+      */
     public static function mimetypes() {
         return array_merge(
             mimeinfo_from_icon('type', 'video', true),
@@ -187,14 +294,44 @@ class portfolio_format_video extends portfolio_format_file {
 }
 
 /**
-* class for plain text format.. not sure why we would need this yet
-* but since resource module wants to export it... we can
-*/
+ * Class for plain text format.
+ *
+ * Not sure why we would need this yet,
+ * but since resource module wants to export it... we can
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2008 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_text extends portfolio_format_file {
+
+    /**
+     * Return plain text mimetypes
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array('text/plain');
     }
 
+    /**
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
+     * "generally" supports something like FORMAT_PLAINHTML
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
+     * which implies removing support for FORMAT_PLAINHTML.
+     * Note that conflicts don't have to be bi-directional
+     * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
+     * but not the other way around) and things within the class hierarchy
+     * are resolved automatically anyway.
+     * This is really just between subclasses of format_rich
+     * and subclasses of format_file.
+     *
+     * @param string $format one of the FORMAT_XX constants
+     * @return bool
+     */
     public static function conflicts($format ) {
         return ($format == PORTFOLIO_FORMAT_PLAINHTML
             || $format == PORTFOLIO_FORMAT_RICHHTML);
@@ -202,11 +339,22 @@ class portfolio_format_text extends portfolio_format_file {
 }
 
 /**
- * base class for rich formats.
- * these are multipart - eg things with attachments
+ * Base class for rich formats.
+ *
+ * These are multipart - eg things with attachments
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class portfolio_format_rich extends portfolio_format {
 
+    /**
+     * Return rich text mimetypes
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array();
     }
@@ -214,13 +362,42 @@ abstract class portfolio_format_rich extends portfolio_format {
 }
 
 /**
- * most commonly used rich format - richhtml - html with attachments
+ * Richhtml - html with attachments.
+ *
+ * The most commonly used rich format
  * eg inline images
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class portfolio_format_richhtml extends portfolio_format_rich {
+
+    /**
+     * For multipart formats, eg html with attachments,
+     * we need to have a directory to place associated files from
+     * inside the zip file. this is the name of that directory
+     *
+     * @return string
+     */
     public static function get_file_directory() {
         return 'site_files/';
     }
+
+    /**
+     * Given a file, return a snippet of markup in whatever format
+     * to link to that file.
+     * Usually involves the path given by get_file_directory.
+     * This is not supported in subclasses of portfolio_format_file
+     * since they're all just single files.
+     * @see get_file_directory
+     *
+     * @param stored_file $file information for existing file
+     * @param array $options array of options to pass. can contain:
+     *              attributes => hash of existing html attributes (eg title, height, width, etc)
+     * @return string
+     */
     public static function file_output($file, $options=null) {
         $path = self::get_file_directory() . $file->get_filename();
         $attributes = array();
@@ -229,28 +406,68 @@ class portfolio_format_richhtml extends portfolio_format_rich {
         }
         return self::make_tag($file, $path, $attributes);
     }
+
+    /**
+     * Whether this format conflicts with the given format.
+     * This is used for the case where an export location
+     * "generally" supports something like FORMAT_PLAINHTML
+     * but then in a specific export case, must add attachments,
+     * which means that FORMAT_RICHHTML is supported in that case,
+     * which implies removing support for FORMAT_PLAINHTML.
+     * Note that conflicts don't have to be bi-directional
+     * (eg FORMAT_PLAINHTML conflicts with FORMAT_RICHHTML
+     * but not the other way around) and things within the class hierarchy
+     * are resolved automatically anyway.
+     * This is really just between subclasses of format_rich
+     * and subclasses of format_file.
+     *
+     * @todo MDL-31305 - revisit the conflict with file, since we zip here
+     * @param string $format one of the FORMAT_XX constants
+     * @return bool
+     */
     public static function conflicts($format) { // TODO revisit the conflict with file, since we zip here
         return ($format == PORTFOLIO_FORMAT_PLAINHTML || $format == PORTFOLIO_FORMAT_FILE);
     }
 
 }
 
+/**
+ * Class used for leap2a format
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_leap2a extends portfolio_format_rich {
 
+    /**
+     * For multipart formats, eg html with attachments,
+     * we need to have a directory to place associated files from
+     * inside the zip file. this is the name of that directory
+     *
+     * @return string
+     */
     public static function get_file_directory() {
         return 'files/';
     }
 
+    /**
+     * Return the file prefix
+     *
+     * @return string
+     */
     public static function file_id_prefix() {
         return 'storedfile';
     }
 
     /**
-     * return the link to a file
+     * Return the link to a file
      *
-     * @param stored_file $file
-     * @param array       $options can contain the same as normal, with the addition of:
-     *             entry => whether the file is a LEAP2A entry or just a bundled file (default true)
+     * @param stored_file $file information for existing file
+     * @param array $options array of options to pass. can contain:
+     *              attributes => hash of existing html attributes (eg title, height, width, etc)
+     * @return string
      */
     public static function file_output($file, $options=null) {
         $id = '';
@@ -273,6 +490,12 @@ class portfolio_format_leap2a extends portfolio_format_rich {
         return self::make_tag($file, $path, $attributes);
     }
 
+    /**
+     * Generate portfolio_format_leap2a
+     *
+     * @param stdclass $user user information object
+     * @return portfolio_format_leap2a_writer
+     */
     public static function leap2a_writer(stdclass $user=null) {
         global $CFG;
         if (empty($user)) {
@@ -283,35 +506,60 @@ class portfolio_format_leap2a extends portfolio_format_rich {
         return new portfolio_format_leap2a_writer($user);
     }
 
+    /**
+     * Return the manifest name
+     *
+     * @return string
+     */
     public static function manifest_name() {
         return 'leap2a.xml';
     }
 }
 
 
-/**
-* later.... a moodle plugin might support this.
-* it's commented out in portfolio_supported_formats so cannot currently be used.
-*/
+// later.... a moodle plugin might support this.
+// it's commented out in portfolio_supported_formats so cannot currently be used.
 //class portfolio_format_mbkp extends portfolio_format_rich {}
 
 /**
-* 'PDF format', subtype of file.
-*
-* for portfolio plugins that support PDFs specifically
-*/
+ * 'PDF format', subtype of file.
+ *
+ * For portfolio plugins that support PDFs specifically.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Dan Poltawski
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_pdf extends portfolio_format_file {
+
+    /**
+     * Return pdf mimetypes
+     *
+     * @return array
+     */
     public static function mimetypes() {
         return array('application/pdf');
     }
 }
 
 /**
-* 'Document format', subtype of file.
-*
-* for portfolio plugins that support documents specifically
-*/
+ * 'Document format', subtype of file.
+ *
+ * For portfolio plugins that support documents specifically.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Dan Poltawski
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_document extends portfolio_format_file {
+
+    /**
+     * Return documents mimetypes
+     *
+     * @return array of documents mimetypes
+     */
     public static function mimetypes() {
         return array_merge(
             array('text/plain', 'text/rtf'),
@@ -323,11 +571,22 @@ class portfolio_format_document extends portfolio_format_file {
 }
 
 /**
-* 'Spreadsheet format', subtype of file.
-*
-* for portfolio plugins that support spreadsheets specifically
-*/
+ * 'Spreadsheet format', subtype of file.
+ *
+ * For portfolio plugins that support spreadsheets specifically.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Dan Poltawski
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_spreadsheet extends portfolio_format_file {
+
+    /**
+     * Return spreadsheet spreadsheet mimetypes
+     *
+     * @return array of documents mimetypes
+     */
     public static function mimetypes() {
         return array_merge(
             mimeinfo_from_icon('type', 'excel', true),
@@ -338,11 +597,22 @@ class portfolio_format_spreadsheet extends portfolio_format_file {
 }
 
 /**
-* 'Presentation format', subtype of file.
-*
-* for portfolio plugins that support presentation specifically
-*/
+ * 'Presentation format', subtype of file.
+ *
+ * For portfolio plugins that support presentation specifically.
+ *
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Dan Poltawski
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class portfolio_format_presentation extends portfolio_format_file {
+
+    /**
+     * Return presentation documents mimetypes
+     *
+     * @return array presentation document mimetypes
+     */
     public static function mimetypes() {
         return mimeinfo_from_icon('type', 'powerpoint', true);
     }
index f705b67..c1da6ab 100644 (file)
@@ -1,37 +1,34 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
 /**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- *          http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * This file contains the LEAP2a writer used by portfolio_format_leap2a
  *
- * @package    core
- * @subpackage portfolio
- * @author     Penny Leach <penny@liip.ch>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright  (C) 1999 onwards Martin Dougiamas  http://dougiamas.com
+ * @package core_portfolio
+ * @copyright 2009 Penny Leach (penny@liip.ch), Martin Dougiamas
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  *
- * This file contains the LEAP2a writer used by portfolio_format_leap2a
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
- * object to encapsulate the writing of leap2a.
- * should be used like:
+ * Object to encapsulate the writing of leap2a.
  *
+ * Should be used like:
  * $writer = portfolio_format_leap2a::leap2a_writer($USER);
  * $entry = new portfolio_format_leap2a_entry('forumpost6', $title, 'leap2', 'somecontent')
  * $entry->add_link('something', 'has_part')->add_link('somethingelse', 'has_part');
@@ -39,26 +36,34 @@ defined('MOODLE_INTERNAL') || die();
  * $writer->add_entry($entry);
  * $xmlstr = $writer->to_xml();
  *
- * @TODO find a way to ensure that all referenced files are included
+ * @todo MDL-31287 - find a way to ensure that all referenced files are included
+ * @package core_portfolio
+ * @category portfolio
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class portfolio_format_leap2a_writer {
 
-    /** the domdocument object used to create elements */
+    /** @var DomDocument the domdocument object used to create elements */
     private $dom;
-    /** the top level feed element */
+
+    /** @var DOMElement the top level feed element */
     private $feed;
-    /** the user exporting data */
+
+    /** @var stdClass the user exporting data */
     private $user;
-    /** the id of the feed - this is unique to the user and date and used for portfolio ns as well as feed id */
+
+    /** @var string the id of the feed - this is unique to the user and date and used for portfolio ns as well as feed id */
     private $id;
-    /** the entries for the feed - keyed on id */
+
+    /** @var array the entries for the feed - keyed on id */
     private $entries = array();
 
     /**
-     * constructor - usually generated from portfolio_format_leap2a::leap2a_writer($USER);
+     * Constructor - usually generated from portfolio_format_leap2a::leap2a_writer($USER);
      *
+     * @todo MDL-31302 - add exporter and format
    &