From 714ec903c7d326534faa17c8aa3b218037c855c2 Mon Sep 17 00:00:00 2001 From: Ankit Agarwal Date: Tue, 29 Jul 2014 15:54:08 +0800 Subject: [PATCH] MDL-46567 gradereport_history: Basic codestyle, phpdocs and other minor cleanups Part of MDL-46191 This commit includes following changes:- - Fix codestyle issues - Remove readme file - Fix and add file headers - Fix and add missing phpdocs --- grade/report/history/README.md | 26 ----- grade/report/history/ajax.php | 2 +- grade/report/history/classes/filter_form.php | 24 ++-- grade/report/history/classes/user_button.php | 17 ++- grade/report/history/index.php | 4 +- .../history/lang/en/gradereport_history.php | 2 +- grade/report/history/lib.php | 106 ++++++++++++++---- grade/report/history/renderer.php | 50 +++++++-- grade/report/history/settings.php | 4 +- grade/report/history/version.php | 6 +- 10 files changed, 161 insertions(+), 80 deletions(-) delete mode 100644 grade/report/history/README.md diff --git a/grade/report/history/README.md b/grade/report/history/README.md deleted file mode 100644 index 1d1d5eac7b8..00000000000 --- a/grade/report/history/README.md +++ /dev/null @@ -1,26 +0,0 @@ -#Grade History report -This report allows grading staff to view a history of what happened to grades in their courses. This is especially useful for courses that have multiple graders and it's necessary to see if a grade or grades from one grader got altered by another. - -##Install -### Using Moodle -You can install the plugin from the Moodle plugin repository from within your Moodle installation. -### Using a downloaded zip file -You can download a zip of this module from: https://github.com/netspotau/moodle-gradereport_history/zipball/master -Unzip it to your grade/report/ folder and rename the extracted folder to 'history'. -### Using Git -To install using git, run the following command from the root of your moodle installation: -git clone git://github.com/netspotau/moodle-gradereport_history.git grade/report/history - -Then add grade/report/history to your gitignore. - -##Credits -The Grade History report was developed by NetSpot Pty Ltd (http://www.netspot.com.au). - -**Code:** Adam Olley (adam.olley@netspot.com.au) -**Concept, Design & Testing:** Consortium for gradebook enhancement - -- University of Canberra (http://www.canberra.edu.au) -- University of New South Wales (http://www.unsw.edu.au) -- Macquarie University (http://www.mq.edu.au) - -**Project Management:** Kim Edgar (kim.edgar@netspot.com.au) diff --git a/grade/report/history/ajax.php b/grade/report/history/ajax.php index b0d7c5126ce..245a521f51d 100644 --- a/grade/report/history/ajax.php +++ b/grade/report/history/ajax.php @@ -25,7 +25,7 @@ define('AJAX_SCRIPT', true); -require_once('../../../config.php'); +require_once(__DIR__ . '/../../../config.php'); require_once($CFG->dirroot.'/grade/report/history/lib.php'); $id = required_param('id', PARAM_INT); // Course id. diff --git a/grade/report/history/classes/filter_form.php b/grade/report/history/classes/filter_form.php index 48905a01264..52e77507ca2 100644 --- a/grade/report/history/classes/filter_form.php +++ b/grade/report/history/classes/filter_form.php @@ -17,6 +17,7 @@ /** * Form for grade history filters * + * @package gradereport_history * @copyright 2013 NetSpot Pty Ltd (https://www.netspot.com.au) * @author Adam Olley * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -26,10 +27,21 @@ defined('MOODLE_INTERNAL') || die; require_once($CFG->libdir.'/formslib.php'); +/** + * Form for grade history filters + * + * @since Moodle 2.8 + * @package gradereport_history + * @copyright 2013 NetSpot Pty Ltd (https://www.netspot.com.au) + * @author Adam Olley + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class gradereport_history_filter_form extends moodleform { + /** + * Definition of the Mform for filters displayed in the report. + */ public function definition() { - global $USER, $CFG; $mform =& $this->_form; $course = $this->_customdata['course']; @@ -38,8 +50,6 @@ class gradereport_history_filter_form extends moodleform { $userbutton = $this->_customdata['userbutton']; $names = html_writer::span('', 'selectednames'); - $context = context_course::instance($course->id); - $mform->addElement('static', 'userselect', get_string('selectuser', 'gradereport_history'), $userbutton); $mform->addElement('static', 'selectednames', get_string('selectedusers', 'gradereport_history'), $names); @@ -72,6 +82,9 @@ class gradereport_history_filter_form extends moodleform { $mform->closeHeaderBefore('buttonar'); } + /** + * This method implements changes to the form that need to be made once the form data is set. + */ public function definition_after_data() { $mform =& $this->_form; @@ -80,9 +93,4 @@ class gradereport_history_filter_form extends moodleform { } } - public function validation($data, $files) { - return parent::validation($data, $files); - } - } - diff --git a/grade/report/history/classes/user_button.php b/grade/report/history/classes/user_button.php index c8cfd7d5784..e73bc28a7ac 100644 --- a/grade/report/history/classes/user_button.php +++ b/grade/report/history/classes/user_button.php @@ -17,6 +17,7 @@ /** * User button. Adapted from core_select_user_button. * + * @package gradereport_history * @copyright 2013 NetSpot Pty Ltd (https://www.netspot.com.au) * @author Adam Olley * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -26,6 +27,12 @@ defined('MOODLE_INTERNAL') || die; /** * A button that is used to select users for a form. + * + * @since Moodle 2.8 + * @package gradereport_history + * @copyright 2013 NetSpot Pty Ltd (https://www.netspot.com.au) + * @author Adam Olley + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class gradereport_history_user_button extends single_button { @@ -48,15 +55,14 @@ class gradereport_history_user_button extends single_button { protected $jsstrings = array(); /** - * Initialises the new select_user_button + * Initialises the new select_user_button. * - * @staticvar int $count The number of select user buttons already created * @param moodle_url $url * @param string $label The text to display in the button * @param string $method Either post or get */ public function __construct(moodle_url $url, $label, $method = 'post') { - static $count = 0; + static $count = 0; // The number of select user buttons already created. $count ++; parent::__construct($url, $label, $method); $this->class = 'singlebutton selectusersbutton'; @@ -102,7 +108,7 @@ class gradereport_history_user_button extends single_button { /** * Requires strings for JS that will be loaded when the button is used. * - * @param type $identifiers + * @param array|stdClass $identifiers * @param string $component * @param mixed $a */ @@ -115,7 +121,7 @@ class gradereport_history_user_button extends single_button { } /** - * Initialises the JS that is required by this button + * Initialises the JS that is required by this button. * * @param moodle_page $page */ @@ -131,4 +137,3 @@ class gradereport_history_user_button extends single_button { } } } - diff --git a/grade/report/history/index.php b/grade/report/history/index.php index 3c359bbdd55..cf5205355f3 100644 --- a/grade/report/history/index.php +++ b/grade/report/history/index.php @@ -23,7 +23,7 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ -require_once('../../../config.php'); +require_once(__DIR__ . '/../../../config.php'); require_once($CFG->libdir.'/gradelib.php'); require_once($CFG->dirroot.'/user/renderer.php'); require_once($CFG->dirroot.'/grade/lib.php'); @@ -93,8 +93,6 @@ if ($data = $mform->get_data()) { ); } - - $report = new grade_report_history($courseid, $gpr, $context, $filters, $page, $sortitemid); $report->load_users(); diff --git a/grade/report/history/lang/en/gradereport_history.php b/grade/report/history/lang/en/gradereport_history.php index 0ed68a509d5..1d7b0d1f7ce 100644 --- a/grade/report/history/lang/en/gradereport_history.php +++ b/grade/report/history/lang/en/gradereport_history.php @@ -15,7 +15,7 @@ // along with Moodle. If not, see . /** - * Strings for component 'gradereport_grader', language 'en' + * Strings for component 'gradereport_history', language 'en' * * @package gradereport_history * @copyright 2013 NetSpot Pty Ltd (https://www.netspot.com.au) diff --git a/grade/report/history/lib.php b/grade/report/history/lib.php index 34e644718fb..e6dca8f031e 100644 --- a/grade/report/history/lib.php +++ b/grade/report/history/lib.php @@ -15,7 +15,7 @@ // along with Moodle. If not, see . /** - * Definition of the history report class + * Definition of the history report class. * * @package gradereport_history * @copyright 2013 NetSpot Pty Ltd (https://www.netspot.com.au) @@ -23,52 +23,75 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ +defined('MOODLE_INTERNAL') || die; require_once($CFG->dirroot . '/grade/report/lib.php'); require_once($CFG->libdir.'/tablelib.php'); -require_once($CFG->dirroot.'/grade/report/history/classes/filter_form.php'); -require_once($CFG->dirroot.'/grade/report/history/classes/user_button.php'); +/** + * Definition of the history report class. + * + * @since Moodle 2.8 + * @package gradereport_history + * @copyright 2013 NetSpot Pty Ltd (https://www.netspot.com.au) + * @author Adam Olley + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class grade_report_history extends grade_report { + /** + * @var array This doesn't seem to be used but set only. + */ private $fieldorder = array(); + + /** + * @var array List of filters selected. + */ private $filters = array(); + + /** + * @var array Raw data of the html table. + */ private $tabledata = array(); + + /** + * @var array Raw dump of records from the grade history table. + */ private $history; + + /** + * @var array Generates a mapping that lists all history entries for a given grade item grouped by userids. + */ private $itemidmap = array(); /** - * Current page (for paging). - * @var int $page + * @var int $page Current page (for paging). */ public $page = 0; /** - * Number of history rows per page. - * @var string $perpage + * @var string Number of history rows per page. */ public $perpage = 50; /** - * Total number of history rows. - * @var string $numrows + * @var string Total number of history rows. */ public $numrows = 0; /** - * The id of the grade_item by which this report will be sorted. - * @var int $sortitemid + * @var int The id of the grade_item by which this report will be sorted. */ public $sortitemid; /** - * Sortorder used in the SQL selections. - * @var int $sortorder + * @var int Sortorder used in the SQL selections. */ public $sortorder; /** * Constructor. + * * @param int $courseid * @param object $gpr grade plugin return tracking object * @param string $context @@ -81,9 +104,9 @@ class grade_report_history extends grade_report { * revisedonly : only show revised grades (default: false) * format : page | csv | excel (default: page) * @param int $page The current page being viewed (when report is paged) + * @param int $sortitemid The id of the grade_item by which this report will be sorted. */ public function __construct($courseid, $gpr, $context, $filters = array(), $page = null, $sortitemid = null) { - global $CFG; parent::__construct($courseid, $gpr, $context, $page); $this->baseurl = new moodle_url('index.php', array('id' => $this->courseid)); @@ -108,7 +131,13 @@ class grade_report_history extends grade_report { } /** + * Get history of grades. + * * @param bool $count If we just want the total count or not. + * + * @return array + * @throws coding_exception + * @throws dml_exception */ public function get_history($count = false) { global $DB; @@ -119,7 +148,8 @@ class grade_report_history extends grade_report { ggh.source, ggh.overridden, ggh.locked, ggh.excluded, ggh.feedback, gi.itemtype, gi.itemmodule, gi.iteminstance, gi.itemnumber'; - if ($this->sortitemid == 'firstname' || $this->sortitemid == 'lastname' || $this->sortitemid == 'username' || $this->sortitemid == 'email') { + if ($this->sortitemid == 'firstname' || $this->sortitemid == 'lastname' + || $this->sortitemid == 'username' || $this->sortitemid == 'email') { $sortitemid = 'u.' . $this->sortitemid; $fields .= ', u.' . $this->sortitemid; } else if ($this->sortitemid == 'grader') { @@ -210,6 +240,11 @@ class grade_report_history extends grade_report { return $this->history; } + /** + * Returns raw table data for the report. + * + * @return array raw table data without any formatting. + */ public function get_table_data() { $list = array(); @@ -242,7 +277,7 @@ class grade_report_history extends grade_report { * @return array empty array if success, array of warnings if something fails. */ public function process_data($data) { - global $DB; + $warnings = array(); return $warnings; @@ -307,6 +342,11 @@ class grade_report_history extends grade_report { } } + /** + * Returns a list of selected users. + * + * @return array returns an array in the format $userid => $userid + */ public function get_selected_users() { $list = array(); if (!empty($this->filters['userids'])) { @@ -323,9 +363,15 @@ class grade_report_history extends grade_report { /** * We're interested in anyone that had a grade history in this course. + * + * @param string $search the text to search for (empty string = find all) + * @param int $page page number, defaults to 0. (This is not used) + * @param int $perpage Number of entries to display per page, defaults to 0.(This is not used) + * + * @return array */ public function load_users($search = '', $page = 0, $perpage = 0) { - global $CFG, $DB; + global $DB; if (!empty($this->users)) { return; @@ -353,7 +399,13 @@ class grade_report_history extends grade_report { return $this->users; } - + /** + * Method to return html for the whole html table to be displayed to user as a report. + * + * This method sets up an instance of html_table, populates it and returns html to display it. + * + * @return string HTML to display the table. + */ public function get_history_table() { global $OUTPUT; $extrafields = get_extra_user_fields($this->context); @@ -379,7 +431,7 @@ class grade_report_history extends grade_report { $row->cells[] = $record->prevgrade; $row->cells[] = $record->finalgrade; foreach ($extrafields as $field) { - // BASE-445 - do not show an additional username column + // Do not show an additional username column. if ($field == 'username') { continue; } @@ -411,6 +463,11 @@ class grade_report_history extends grade_report { return $OUTPUT->container($html, 'gradeparent'); } + /** + * Return the header for the html table. + * + * @return html_table_row The header row. + */ public function get_table_headings() { $extrafields = get_extra_user_fields($this->context); $arrows = $this->get_sort_arrows($extrafields); @@ -433,7 +490,7 @@ class grade_report_history extends grade_report { } foreach ($extrafields as $field) { - // BASE-445 - do not show an additional username column + // Do not show an additional username column. if ($field == 'username') { continue; } @@ -519,7 +576,6 @@ class grade_report_history extends grade_report { $strexcluded = $this->get_lang_string('excluded', 'gradereport_history'); $strfeedback = $this->get_lang_string('feedbacktext', 'gradereport_history'); - $iconasc = $OUTPUT->pix_icon('t/sort_asc', $strsortasc, '', array('class' => 'iconsmall sorticon')); $icondesc = $OUTPUT->pix_icon('t/sort_desc', $strsortdesc, '', array('class' => 'iconsmall sorticon')); @@ -588,6 +644,14 @@ class grade_report_history extends grade_report { return $arrows; } + /** + * Get an instance of the user select button {@link gradereport_history_user_button}. + * + * @param int $courseid course id + * @param array $currentusers List of currently selected users. + * + * @return gradereport_history_user_button the user select button. + */ public static function get_user_select_button($courseid, $currentusers = array()) { global $PAGE; $button = new gradereport_history_user_button($PAGE->url, get_string('selectuser', 'gradereport_history'), 'get'); diff --git a/grade/report/history/renderer.php b/grade/report/history/renderer.php index 177bcd25038..756f58f54e0 100644 --- a/grade/report/history/renderer.php +++ b/grade/report/history/renderer.php @@ -14,8 +14,35 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . +/** + * Renderer for history grade report. + * + * @package gradereport_history + * @copyright 2013 NetSpot Pty Ltd (https://www.netspot.com.au) + * @author Adam Olley + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die; + +/** + * Renderer for history grade report. + * + * @since Moodle 2.8 + * @package gradereport_history + * @copyright 2013 NetSpot Pty Ltd (https://www.netspot.com.au) + * @author Adam Olley + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class gradereport_history_renderer extends plugin_renderer_base { + /** + * Render for the select user button. + * + * @param gradereport_history_user_button $button instance of gradereport_history_user_button to render + * + * @return string HTML to display + */ public function render_select_user_button(gradereport_history_user_button $button) { $attributes = array('type' => 'button', 'class' => 'selectortrigger', @@ -32,10 +59,10 @@ class gradereport_history_renderer extends plugin_renderer_base { } $button->initialise_js($this->page); - // first the input element + // First the input element. $output = html_writer::empty_tag('input', $attributes); - // then hidden fields + // Then hidden fields. $params = $button->url->params(); if ($button->method === 'post') { $params['sesskey'] = sesskey(); @@ -44,27 +71,34 @@ class gradereport_history_renderer extends plugin_renderer_base { $output .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => $var, 'value' => $val)); } - // then div wrapper for xhtml strictness + // Then div wrapper for xhtml strictness. $output = html_writer::tag('div', $output); - // now the form itself around it + // Now the form itself around it. if ($button->method === 'get') { - $url = $button->url->out_omit_querystring(true); // url without params, the anchor part allowed + $url = $button->url->out_omit_querystring(true); // Url without params, the anchor part allowed. } else { - $url = $button->url->out_omit_querystring(); // url without params, the anchor part not allowed + $url = $button->url->out_omit_querystring(); // Url without params, the anchor part not allowed. } if ($url === '') { - $url = '#'; // there has to be always some action + $url = '#'; // There has to be always some action. } $attributes = array('method' => $button->method, 'action' => $url, 'id' => $button->formid); $output = html_writer::tag('div', $output, $attributes); - // and finally one more wrapper with class + // Finally one more wrapper with class. return html_writer::tag('div', $output, array('class' => $button->class)); } + /** + * Title to display on the report page. + * + * @param array $users list of selected users. + * + * @return string HTML to display + */ public function report_title($users = array()) { $name = get_string('pluginname', 'gradereport_history'); if (empty($users)) { diff --git a/grade/report/history/settings.php b/grade/report/history/settings.php index ca57af4a404..51b20d66fb9 100644 --- a/grade/report/history/settings.php +++ b/grade/report/history/settings.php @@ -26,8 +26,8 @@ defined('MOODLE_INTERNAL') || die; if ($ADMIN->fulltree) { - /// Add settings for this module to the $settings object (it's already defined) + // Add settings for this module to the $settings object (it's already defined). $settings->add(new admin_setting_configtext('grade_report_historyperpage', get_string('historyperpage', 'gradereport_history'), - get_string('historyperpage_help', 'gradereport_history'), 50)); + get_string('historyperpage_help', 'gradereport_history'), 50)); } diff --git a/grade/report/history/version.php b/grade/report/history/version.php index edcbbc89d7c..683cff76fa7 100644 --- a/grade/report/history/version.php +++ b/grade/report/history/version.php @@ -25,8 +25,6 @@ defined('MOODLE_INTERNAL') || die(); -$plugin->version = 2014070900; -$plugin->requires = 2013051402; +$plugin->version = 2014072900; +$plugin->requires = 2014072400; $plugin->component = 'gradereport_history'; -$plugin->maturity = MATURITY_RC; -$plugin->release = 'v2.5.1.0';