MDL-74295 question bank: add help icons to columns that need it

question/bank/comment/classes/comment_count_column.php

@@ -68,10 +68,10 @@ protected function display_content($question, $rowclasses): void {
             $datatarget = '[data-target="' . $target . '"]';
             $PAGE->requires->js_call_amd('qbank_comment/comment', 'init', [$datatarget]);
             $attributes = [
+                'href' => '#',
                 'data-target' => $target,
                 'data-questionid' => $question->id,
                 'data-courseid' => $this->qbank->course->id,
-                'class' => 'link-primary comment-pointer'
             ];
         }
         echo \html_writer::tag('a', $commentcount, $attributes);

question/bank/comment/styles.css

@@ -3,7 +3,3 @@
     max-width: none;
     width: 100%;
 }
-
-.comment-pointer {
-    cursor: pointer;
-}

question/bank/statistics/classes/columns/discrimination_index.php

@@ -19,7 +19,9 @@
 use core_question\local\bank\column_base;
 use qbank_statistics\helper;
 /**
- * Discrimination index column
+ * This columns shows a message about whether this question is OK or needs revision.
+ *
+ * This is based on the average discrimination index.
  *
  * @package    qbank_statistics
  * @copyright  2021 Catalyst IT Australia Pty Ltd
@@ -37,6 +39,10 @@ public function get_title(): string {
         return get_string('discrimination_index', 'qbank_statistics');
     }
 
+    public function help_icon(): ?\help_icon {
+        return new \help_icon('discrimination_index', 'qbank_statistics');
+    }
+
     /**
      * Column name.
      *

question/bank/statistics/classes/columns/discriminative_efficiency.php

@@ -19,7 +19,7 @@
 use core_question\local\bank\column_base;
 use qbank_statistics\helper;
 /**
- * Discriminative efficiency column
+ * This column show the average discriminative efficiency for this question.
  *
  * @package    qbank_statistics
  * @copyright  2021 Catalyst IT Australia Pty Ltd
@@ -37,6 +37,10 @@ public function get_title(): string {
         return get_string('discriminative_efficiency', 'qbank_statistics');
     }
 
+    public function help_icon(): ?\help_icon {
+        return new \help_icon('discriminative_efficiency', 'qbank_statistics');
+    }
+
     /**
      * Column name.
      *

question/bank/statistics/classes/columns/facility_index.php

@@ -19,7 +19,7 @@
 use core_question\local\bank\column_base;
 use qbank_statistics\helper;
 /**
- * Facility index column
+ * This column show the average facility index for this question.
  *
  * @package    qbank_statistics
  * @copyright  2021 Catalyst IT Australia Pty Ltd
@@ -37,6 +37,9 @@ public function get_title(): string {
         return get_string('facility_index', 'qbank_statistics');
     }
 
+    public function help_icon(): ?\help_icon {
+        return new \help_icon('facility_index', 'qbank_statistics');
+    }
 
     /**
      * Column name.

question/bank/statistics/classes/helper.php

@@ -38,12 +38,12 @@
 class helper {
 
     /**
-     * @var float Threshold to determine 'need for revision'
+     * @var float Threshold to determine 'Needs checking?'
      */
     private const NEED_FOR_REVISION_LOWER_THRESHOLD = 30;
 
     /**
-     * @var float Threshold to determine 'need for revision'
+     * @var float Threshold to determine 'Needs checking?'
      */
     private const NEED_FOR_REVISION_UPPER_THRESHOLD = 50;
 
@@ -198,7 +198,7 @@ public static function format_percentage(?float $number, bool $fraction = true,
     }
 
     /**
-     * Format discrimination index (need for revision).
+     * Format discrimination index (Needs checking?).
      *
      * @param float|null $value stats value
      * @return array

question/bank/statistics/lang/en/qbank_statistics.php

@@ -30,8 +30,12 @@
 
 // Columns.
 $string['facility_index'] = 'Facility index';
+$string['facility_index_help'] = 'The facility index gives the average mark (as a percentage) obtained on the question (all versions) in all quizzes where the question has been attempted. A higher value normally indicates an easier question.';
 $string['discriminative_efficiency'] = 'Discriminative efficiency';
-$string['discrimination_index'] = 'Need for revision';
+$string['discriminative_efficiency_help'] = 'Discriminative efficiency is a statistical estimate of how well the question assesses students, with a higher value being better. A particularly low value may indicate a problem with the question. A very difficult or easy question (with facility index close to 0% or 100%) can also lead to a low value.';
+$string['discriminative_efficiency_link'] = 'mod/quiz/statistics';
+$string['discrimination_index'] = 'Needs checking?';
+$string['discrimination_index_help'] = 'A question is indicated as likely to need checking based on question statistics. For example, if students obtain a low score on the question but a high score on the whole quiz, or a high score on the question but a low score on the whole quiz, then there may be a problem with the question such as the wrong answer being set as correct. Statistics are not infallible though; this is just a hint that the question should be checked.';
 
 // Text format.
 $string['verylikely'] = 'Very likely';

question/bank/statistics/tests/behat/statistics_action.feature

@@ -25,11 +25,11 @@ Feature: Use the qbank plugin manager page for statistics
     And I navigate to "Question bank" in current page administration
     Then I should not see "Facility index"
     And I should not see "Discriminative efficiency"
-    And I should not see "Need for revision"
+    And I should not see "Needs checking?"
     And I navigate to "Plugins > Question bank plugins > Manage question bank plugins" in site administration
     And I click on "Enable" "link" in the "Question statistics" "table_row"
     And I am on the "Test quiz" "quiz activity" page
     And I navigate to "Question bank" in current page administration
     And I should see "Facility index"
     And I should see "Discriminative efficiency"
-    And I should see "Need for revision"
+    And I should see "Needs checking?"

question/bank/usage/classes/question_usage_column.php

@@ -36,6 +36,10 @@ public function get_title(): string {
         return get_string('questionusage', 'qbank_usage');
     }
 
+    public function help_icon(): ?\help_icon {
+        return new \help_icon('questionusage', 'qbank_usage');
+    }
+
     protected function display_content($question, $rowclasses): void {
         global $PAGE;
         $usagecount = helper::get_question_entry_usage_count($question);
@@ -45,10 +49,10 @@ protected function display_content($question, $rowclasses): void {
             $datatarget = '[data-target="' . $target . '"]';
             $PAGE->requires->js_call_amd('qbank_usage/usage', 'init', [$datatarget, $question->contextid]);
             $attributes = [
+                'href' => '#',
                 'data-target' => $target,
                 'data-questionid' => $question->id,
                 'data-courseid' => $this->qbank->course->id,
-                'class' => 'link-primary comment-pointer'
             ];
         }
         echo \html_writer::tag('a', $usagecount, $attributes);

question/bank/usage/lang/en/qbank_usage.php

@@ -26,6 +26,7 @@
 $string['pluginname'] = 'Question usage';
 $string['privacy:metadata'] = 'The Question usage question bank plugin does not store any user data.';
 $string['questionusage'] = 'Usage';
+$string['questionusage_help'] = 'The number of quizzes in which the question is used, with a link to open a window listing the quizzes and the number of attempts.';
 $string['usageheader'] = 'Question usage';
 
 // Table.

question/classes/local/bank/column_base.php

@@ -97,6 +97,7 @@ public function get_preference(): bool {
      */
     public function display_header(): void {
         global $PAGE;
+        $renderer = $PAGE->get_renderer('core_question', 'bank');
 
         $data = [];
         $data['sortable'] = true;
@@ -125,8 +126,11 @@ public function display_header(): void {
                 $data['tip'] = $tip;
             }
         }
+        $help = $this->help_icon();
+        if ($help) {
+            $data['help'] = $help->export_for_template($renderer);
+        }
 
-        $renderer = $PAGE->get_renderer('core_question', 'bank');
         echo $renderer->render_column_header($data);
     }
 
@@ -145,6 +149,15 @@ public function get_title_tip() {
         return '';
     }
 
+    /**
+     * If you return a help icon here, it is shown in the column header after the title.
+     *
+     * @return \help_icon|null help icon to show, if required.
+     */
+    public function help_icon(): ?\help_icon {
+        return null;
+    }
+
     /**
      * Get a link that changes the sort order, and indicates the current sort state.
      * @param string $sort the column to sort on.

question/templates/column_header.mustache

@@ -17,18 +17,36 @@
 {{!
     @template core_question/column_header
 
+    Displays the <th> header cell for a column in the question bank.
+
+    Context variables required for this template:
+        * extraclasses: CSS classes to add to the th. E.g. "questionstatus pr-3".
+        * help: (optional, may be omitted) help icon. The structure here needs to be as from help_icon::export_for_template().
+
+        Other fields vary, depending on whether the column is sortable.
+
+        Column with plain title, not sortable:
+            * sortable: false
+            * tiptitle: Column name (e.g. "Status")
+            * sorttip: (optional) must be true if tip is present.
+            * tip: (optional) a tool tip to show, if the title needs explanation. E.g. "Select questions for bulk actions".
+
+        Sortable column, with a single type of sort (e.g. question type)
+            * sortable: true
+            * sortlinks: HTML of the title, in a link to sort by this. E.g. "<a href=\"http:\/\/localhost\/moodle_head\/question\/edit.php?courseid=100000&amp;qbs1=-qbank_viewquestiontype%5Cquestion_type_column&amp;qbs2=qbank_viewquestionname%5Cquestion_name_idnumber_tags_column-name\" title=\"Sort by Question type descending\">\n    T<i class=\"icon fa fa-sort-asc fa-fw iconsort\"  title=\"Ascending\" role=\"img\" aria-label=\"Ascending\"><\/i>\n<\/a>"
+
+        Sortable column, with an overall title, and multiple sort types (e.g. question name/idnumber)
+            * sortable: true
+            * title: "Question"
+            * sortlinks: Several sort links concatenated. E.g. "<a href=\"http:\/\/localhost\/moodle_head\/question\/edit.php?courseid=100000&amp;qbs1=qbank_viewquestionname%5Cquestion_name_idnumber_tags_column-name&amp;qbs2=qbank_viewquestiontype%5Cquestion_type_column\" title=\"Sort by Question name ascending\">\n    Question name\n<\/a> \/ <a href=\"http:\/\/localhost\/moodle_head\/question\/edit.php?courseid=100000&amp;qbs1=qbank_viewquestionname%5Cquestion_name_idnumber_tags_column-idnumber&amp;qbs2=qbank_viewquestiontype%5Cquestion_type_column&amp;qbs3=qbank_viewquestionname%5Cquestion_name_idnumber_tags_column-name\" title=\"Sort by ID number ascending\">\n    ID number\n<\/a>"
+
     Example context (json):
     {
-        "qbankheaderdata": [
-          {
-                "extraclasses": "checkbox",
-                "sortable": false,
-                "tiptitle": "Element title",
-                "sorttip": true,
-                "tip": "Select questions for bulk actions",
-                "sortlinks": "sort / sort"
-          }
-        ]
+        "sortable": false,
+        "extraclasses": "checkbox pr-3",
+        "tiptitle": "<input id=\"qbheadercheckbox\" name=\"qbheadercheckbox\" type=\"checkbox\"  value=\"1\"\n       data-action=\"toggle\"\n       data-toggle=\"master\"\n       data-togglegroup=\"qbank\"\n       data-toggle-selectall=\"Select all\"\n       data-toggle-deselectall=\"Deselect all\"\n       \n\/>\n    <label for=\"qbheadercheckbox\" class=\"accesshide\">Select all<\/label>",
+        "sorttip": true,
+        "tip": "Select questions for bulk actions"
     }
 }}
 <th class="header {{extraclasses}}" scope="col">
@@ -48,5 +66,8 @@
             {{{sortlinks}}}
         </div>
     {{/sortable}}
+    {{#help}}
+        {{>core/help_icon}}
+    {{/help}}
 </th>