MDL-66074 gradingform_guide: Documentation and selectors
authorMathew May <mathewm@hotmail.co.nz>
Mon, 28 Oct 2019 04:55:01 +0000 (12:55 +0800)
committerMathew May <mathewm@hotmail.co.nz>
Wed, 30 Oct 2019 02:23:41 +0000 (10:23 +0800)
16 files changed:
grade/grading/form/guide/amd/build/grades/grader/gradingpanel.min.js.map
grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments.min.js
grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments.min.js.map
grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments/selectors.min.js [new file with mode: 0644]
grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments/selectors.min.js.map [new file with mode: 0644]
grade/grading/form/guide/amd/src/grades/grader/gradingpanel.js
grade/grading/form/guide/amd/src/grades/grader/gradingpanel/comments.js
grade/grading/form/guide/amd/src/grades/grader/gradingpanel/comments/selectors.js [new file with mode: 0644]
grade/grading/form/guide/classes/grades/grader/gradingpanel/external/fetch.php
grade/grading/form/guide/classes/grades/grader/gradingpanel/external/store.php
grade/grading/form/guide/db/services.php
grade/grading/form/guide/lib.php
grade/grading/form/guide/templates/grades/grader/gradingpanel.mustache
grade/grading/form/guide/tests/coverage.php
grade/grading/form/guide/tests/grades_grader_gradingpanel_guide_external_fetch_test.php
grade/grading/form/guide/tests/grades_grader_gradingpanel_guide_external_store_test.php

index c8e52e6..93c1615 100644 (file)
Binary files a/grade/grading/form/guide/amd/build/grades/grader/gradingpanel.min.js.map and b/grade/grading/form/guide/amd/build/grades/grader/gradingpanel.min.js.map differ
index 8939228..de22d4d 100644 (file)
Binary files a/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments.min.js and b/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments.min.js differ
index 8d6f2a9..5f60005 100644 (file)
Binary files a/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments.min.js.map and b/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments.min.js.map differ
diff --git a/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments/selectors.min.js b/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments/selectors.min.js
new file mode 100644 (file)
index 0000000..d325a53
Binary files /dev/null and b/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments/selectors.min.js differ
diff --git a/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments/selectors.min.js.map b/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments/selectors.min.js.map
new file mode 100644 (file)
index 0000000..539a41d
Binary files /dev/null and b/grade/grading/form/guide/amd/build/grades/grader/gradingpanel/comments/selectors.min.js.map differ
index 567ec6a..5f08608 100644 (file)
@@ -28,6 +28,16 @@ import {normaliseResult} from 'core_grades/grades/grader/gradingpanel/normalise'
 // Note: We use jQuery.serializer here until we can rewrite Ajax to use XHR.send()
 import jQuery from 'jquery';
 
+/**
+ * For a given component, contextid, itemname & gradeduserid we can fetch the currently assigned grade.
+ *
+ * @param {String} component
+ * @param {Number} contextid
+ * @param {String} itemname
+ * @param {Number} gradeduserid
+ *
+ * @returns {Promise}
+ */
 export const fetchCurrentGrade = (component, contextid, itemname, gradeduserid) => {
     return fetchMany([{
         methodname: `gradingform_guide_grader_gradingpanel_fetch`,
@@ -40,7 +50,17 @@ export const fetchCurrentGrade = (component, contextid, itemname, gradeduserid)
     }])[0];
 };
 
-
+/**
+ * For a given component, contextid, itemname & gradeduserid we can store the currently assigned grade in a given form.
+ *
+ * @param {String} component
+ * @param {Number} contextid
+ * @param {String} itemname
+ * @param {Number} gradeduserid
+ * @param {HTMLElement} rootNode
+ *
+ * @returns {Promise}
+ */
 export const storeCurrentGrade = async(component, contextid, itemname, gradeduserid, rootNode) => {
     const form = rootNode.querySelector('form');
 
index 8e69154..c2cbfb5 100644 (file)
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+import Selectors from './comments/selectors';
+
+/**
+ * Manage the frequently used comments in the Marking Guide form.
+ *
+ * @param {String} rootId
+ */
 export const init = (rootId) => {
     const rootNode = document.querySelector(`#${rootId}`);
 
     rootNode.addEventListener('click', (e) => {
-        if (!e.target.matches('[data-gradingform_guide-role="frequent-comment"]')) {
+        if (!e.target.matches(Selectors.frequentComment)) {
             return;
         }
 
         e.preventDefault();
 
-        const clicked = e.target.closest('[data-gradingform_guide-role="frequent-comment"]');
-        const criterion = clicked.closest('[data-gradingform-guide-role="criterion"]');
-        const remark = criterion.querySelector('[data-gradingform-guide-role="remark"]');
+        const clicked = e.target.closest(Selectors.frequentComment);
+        const criterion = clicked.closest(Selectors.criterion);
+        const remark = criterion.querySelector(Selectors.remark);
 
         if (!remark) {
             return;
         }
 
+        // Either append the comment to an existing comment or set it as the comment.
         if (remark.value.trim()) {
             remark.value += `\n${clicked.innerHTML}`;
         } else {
diff --git a/grade/grading/form/guide/amd/src/grades/grader/gradingpanel/comments/selectors.js b/grade/grading/form/guide/amd/src/grades/grader/gradingpanel/comments/selectors.js
new file mode 100644 (file)
index 0000000..45bd89f
--- /dev/null
@@ -0,0 +1,28 @@
+// 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/>.
+
+/**
+ * Define all of the selectors we will be using on the Marking Guide interface.
+ *
+ * @module     gradingform_guide/grades/grader/gradingpanel/comments/selectors
+ * @package    gradingform_guide
+ * @copyright  2019 Mathew May <mathew.solutions>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+export default {
+    frequentComment: '[data-gradingform_guide-role="frequent-comment"]',
+    criterion: '[data-gradingform-guide-role="criterion"]',
+    remark: '[data-gradingform-guide-role="remark"]',
+};
index 3f9c810..fe34182 100644 (file)
@@ -26,6 +26,8 @@ declare(strict_types = 1);
 
 namespace gradingform_guide\grades\grader\gradingpanel\external;
 
+global $CFG;
+
 use coding_exception;
 use context;
 use core_user;
@@ -40,6 +42,7 @@ use external_value;
 use external_warnings;
 use moodle_exception;
 use stdClass;
+require_once($CFG->dirroot.'/grade/grading/form/guide/lib.php');
 
 /**
  * Web services relating to fetching of a marking guide for the grading panel.
@@ -89,6 +92,11 @@ class fetch extends external_api {
      * @param string $itemname
      * @param int $gradeduserid
      * @return array
+     * @throws \dml_exception
+     * @throws \invalid_parameter_exception
+     * @throws \restricted_context_exception
+     * @throws coding_exception
+     * @throws moodle_exception
      * @since Moodle 3.8
      */
     public static function execute(string $component, int $contextid, string $itemname, int $gradeduserid): array {
@@ -118,7 +126,7 @@ class fetch extends external_api {
         // Fetch the gradeitem instance.
         $gradeitem = gradeitem::instance($component, $context, $itemname);
 
-        if ('guide' !== $gradeitem->get_advanced_grading_method()) {
+        if (MARKING_GUIDE !== $gradeitem->get_advanced_grading_method()) {
             throw new moodle_exception(
                 "The {$itemname} item in {$component}/{$contextid} is not configured for advanced grading with a marking guide"
             );
@@ -133,7 +141,8 @@ class fetch extends external_api {
     /**
      * Get the data to be fetched.
      *
-     * @param component_gradeitem $gradeitem
+     * @param gradeitem $gradeitem
+     * @param stdClass $gradeduser
      * @return array
      */
     public static function get_fetch_data(gradeitem $gradeitem, stdClass $gradeduser): array {
index c9fdaae..f1300e0 100644 (file)
@@ -26,6 +26,8 @@ declare(strict_types = 1);
 
 namespace gradingform_guide\grades\grader\gradingpanel\external;
 
+global $CFG;
+
 use coding_exception;
 use context;
 use core_grades\component_gradeitem as gradeitem;
@@ -36,6 +38,7 @@ use external_function_parameters;
 use external_single_structure;
 use external_value;
 use moodle_exception;
+require_once($CFG->dirroot.'/grade/grading/form/guide/lib.php');
 
 /**
  * Web services relating to storing of a marking guide for the grading panel.
@@ -89,7 +92,13 @@ class store extends external_api {
      * @param int $contextid
      * @param string $itemname
      * @param int $gradeduserid
+     * @param string $formdata
      * @return array
+     * @throws \dml_exception
+     * @throws \invalid_parameter_exception
+     * @throws \restricted_context_exception
+     * @throws coding_exception
+     * @throws moodle_exception
      * @since Moodle 3.8
      */
     public static function execute(string $component, int $contextid, string $itemname, int $gradeduserid, string $formdata): array {
@@ -132,7 +141,7 @@ class store extends external_api {
         // Require that this user can save grades.
         $gradeitem->require_user_can_grade($gradeduser, $USER);
 
-        if ('guide' !== $gradeitem->get_advanced_grading_method()) {
+        if (MARKING_GUIDE !== $gradeitem->get_advanced_grading_method()) {
             throw new moodle_exception(
                 "The {$itemname} item in {$component}/{$contextid} is not configured for advanced grading with a marking guide"
             );
index 24a947e..88ea5fd 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
 /**
  * External functions and service definitions for the Marking Guide advanced grading form.
  *
- * @package    mod_forum
+ * @package    gradingform_guide
  * @copyright  2019 Andrew Nicols <andrew@nicols.co.uk>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+defined('MOODLE_INTERNAL') || die;
+
 $functions = [
     'gradingform_guide_grader_gradingpanel_fetch' => [
         'classname' => 'gradingform_guide\\grades\\grader\\gradingpanel\\external\\fetch',
index ffec06c..f878c5e 100644 (file)
@@ -26,6 +26,9 @@ defined('MOODLE_INTERNAL') || die();
 
 require_once($CFG->dirroot.'/grade/grading/form/lib.php');
 
+/** guide: Used to compare our gradeitem_type against. */
+const MARKING_GUIDE = 'guide';
+
 /**
  * This controller encapsulates the guide grading logic
  *
index 2588328..7d816e6 100644 (file)
@@ -1,15 +1,75 @@
+{{!
+    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/>.
+}}
+{{!
+    @template gradingform_rubric/grades/grader/gradingpanel
+
+    Classes required for JS:
+    * none
+
+    Data attributes required for JS:
+    * none
+
+    Context variables required for this template:
+    * instanceid: Instance of the module this grading form belongs too
+    * criterion: A gradeable item in the Marking Guide
+    * name: Name of the gradeable item
+    * id: ID of the gradeable item
+    * description: Description shown to students for this gradeable item
+    * descriptionmarkers: Description shown to teachers for this gradeable item
+    * maxscore: Max allowable assinable points for this item
+    * score: Current score assigned to the learner for this item
+    * remark: Text input for the teacher to relay to the student
+    * hascomments: Flag for frequently used comments
+    * comments: Array of frequently used comments
+    * description: Description of a frequently used comment
+
+    Example context (json):
+    {
+        "instanceid": "42",
+        "criterion": [
+            {
+                "name": "Motivation",
+                "id": 13,
+                "description": "Show your motivation to rock climbing",
+                "descriptionmarkers": "Does the student show interest in climbing?",
+                "maxscore": 37,
+                "score": 20,
+                "remark": "That's great!",
+                "hascomments": true,
+                "comments": [
+                    {"description": "Great work!"},
+                    {"description": "You should really try it before jumping to conclusions"}
+                ]
+            }
+        ]
+    }
+}}
 <form id="gradingform_guide-{{uniqid}}">
   <input type="hidden" name="instanceid" value="{{instanceid}}">
   {{#criterion}}
     <div data-gradingform-guide-role="criterion">
       <h5>
         {{name}}
-        <a 
-          href="#gradingform_guide-{{uniqid}}-criteria-{{id}}-description" 
-          aria-controls="gradingform_guide-{{uniqid}}-criteria-{{id}}-description" 
-          aria-expanded="false" 
-          data-toggle="collapse" 
-          role="button" 
+        <a
+          href="#gradingform_guide-{{uniqid}}-criteria-{{id}}-description"
+          aria-controls="gradingform_guide-{{uniqid}}-criteria-{{id}}-description"
+          aria-expanded="false"
+          data-toggle="collapse"
+          role="button"
           >
             {{# pix }} info, gradingform_guide {{/ pix }}
         </a>
       </div>
       <div class="form-group">
         <label for="gradingform_guide-{{uniqid}}-criteria-{{id}}-score">{{#str}}outof, gradingform_guide, {{maxscore}}{{/str}}</label>
-        <input class="form-control" type="number" name="advancedgrading[criteria][{{id}}][score]" value="{{score}}" 
-            id="gradingform_guide-{{uniqid}}-criteria-{{id}}-score" 
+        <input class="form-control" type="number" name="advancedgrading[criteria][{{id}}][score]" value="{{score}}"
+            id="gradingform_guide-{{uniqid}}-criteria-{{id}}-score"
             aria-describedby="gradingform_guide-{{uniqid}}-help-{{id}}-score">
         <small id="gradingform_guide-{{uniqid}}-help-{{id}}-score" class="sr-only">{{#str}}grade_help, gradingform_guide{{/str}}</small>
       </div>
       <div class="form-group ">
         <label for="gradingform_guide-{{uniqid}}-criteria-{{id}}-remark">{{#str}}additionalcomments, gradingform_guide{{/str}}</label>
         <div class="input-group mb-3 form-inset form-inset-right">
-          <textarea class="form-control" type="text" name="advancedgrading[criteria][{{id}}][remark]" 
-              id="gradingform_guide-{{uniqid}}-criteria-{{id}}-remark" 
-              aria-describedby="gradingform_guide-{{uniqid}}-help-{{id}}-remark" 
-              data-gradingform-guide-role="remark" 
+          <textarea class="form-control" type="text" name="advancedgrading[criteria][{{id}}][remark]"
+              id="gradingform_guide-{{uniqid}}-criteria-{{id}}-remark"
+              aria-describedby="gradingform_guide-{{uniqid}}-help-{{id}}-remark"
+              data-gradingform-guide-role="remark"
               >{{remark}}</textarea>
           {{#hascomments}}
-            <a 
-              class="form-inset-item" 
-              href="#gradingform_guide-{{uniqid}}-criteria-{{id}}-remark-frequent-comments" 
-              aria-controls="gradingform_guide-{{uniqid}}-criteria-{{id}}-remark-frequent-comments" 
-              aria-expanded="false" 
-              data-toggle="collapse" 
-              role="button" 
+            <a
+              class="form-inset-item"
+              href="#gradingform_guide-{{uniqid}}-criteria-{{id}}-remark-frequent-comments"
+              aria-controls="gradingform_guide-{{uniqid}}-criteria-{{id}}-remark-frequent-comments"
+              aria-expanded="false"
+              data-toggle="collapse"
+              role="button"
               >
                 {{#pix}}plus, gradingform_guide{{/pix}}
             </a>
index cdb8005..84ed112 100644 (file)
@@ -14,8 +14,6 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-defined('MOODLE_INTERNAL') || die();
-
 /**
  * Coverage information for the gradingform_guide plugin.
  *
@@ -25,6 +23,8 @@ defined('MOODLE_INTERNAL') || die();
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+defined('MOODLE_INTERNAL') || die();
+
 /**
  * Coverage information for the gradingform_guide plugin.
  *
@@ -33,7 +33,7 @@ defined('MOODLE_INTERNAL') || die();
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 return new class extends phpunit_coverage_info {
-    /** @var array The list of folders relative to the plugin root to whitelist in coverage generation. */
+    // Array The list of folders relative to the plugin root to whitelist in coverage generation.
     protected $whitelistfolders = [
         'classes',
         'tests/generator',
index 1f58bbd..bee39c5 100644 (file)
@@ -17,7 +17,7 @@
 /**
  * Unit tests for core_grades\component_gradeitems;
  *
- * @package   core_grades
+ * @package   gradingform_guide
  * @category  test
  * @copyright 2019 Andrew Nicols <andrew@nicols.co.uk>
  * @license   http://www.gnu.org/copyleft/gpl.html GNU Public License
@@ -37,7 +37,7 @@ use moodle_exception;
 /**
  * Unit tests for core_grades\component_gradeitems;
  *
- * @package   core_grades
+ * @package   gradingform_guide
  * @category  test
  * @copyright 2019 Andrew Nicols <andrew@nicols.co.uk>
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
index bc46350..c55badf 100644 (file)
@@ -17,7 +17,7 @@
 /**
  * Unit tests for core_grades\component_gradeitems;
  *
- * @package   core_grades
+ * @package   gradingform_guide
  * @category  test
  * @copyright 2019 Andrew Nicols <andrew@nicols.co.uk>
  * @license   http://www.gnu.org/copyleft/gpl.html GNU Public License
@@ -37,7 +37,7 @@ use moodle_exception;
 /**
  * Unit tests for core_grades\component_gradeitems;
  *
- * @package   core_grades
+ * @package   gradingform_guide
  * @category  test
  * @copyright 2019 Andrew Nicols <andrew@nicols.co.uk>
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later