question/qengine.js

   1 // This file is part of Moodle - http://moodle.org/
   2 //
   3 // Moodle is free software: you can redistribute it and/or modify
   4 // it under the terms of the GNU General Public License as published by
   5 // the Free Software Foundation, either version 3 of the License, or
   6 // (at your option) any later version.
   7 //
   8 // Moodle is distributed in the hope that it will be useful,
   9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 // GNU General Public License for more details.
  12 //
  13 // You should have received a copy of the GNU General Public License
  14 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  15
  16 /**
  17  * JavaScript required by the question engine.
  18  *
  19  * @package    moodlecore
  20  * @subpackage questionengine
  21  * @copyright  2008 The Open University
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25
  26 /**
  27  * Scroll manager is a class that help with saving the scroll positing when you
  28  * click on an action icon, and then when the page is reloaded after processing
  29  * the action, it scrolls you to exactly where you were. This is much nicer for
  30  * the user.
  31  *
  32  * To use this in your code, you need to ensure that:
  33  * 1. The button that triggers the action has to have a click event handler that
  34  *    calls M.core_scroll_manager.save_scroll_pos
  35  * 2. The script that process the action has to grab the scrollpos parameter
  36  *    using $scrollpos = optional_param('scrollpos', 0, PARAM_INT);
  37  * 3. After doing the processing, it must add ->param('scrollpos', $scrollpos)
  38  *    to the URL that it redirects to.
  39  * 4. Finally, on the page that is reloaded (which should be the same as the one
  40  *    the user started on) you need to call M.core_scroll_manager.scroll_to_saved_pos
  41  *    on page load.
  42  */
  43 M.core_scroll_manager = M.core_scroll_manager || {};
  44
  45 /**
  46  * In the form that contains the element, set the value of the form field with
  47  * name scrollpos to the current scroll position. If there is no element with
  48  * that name, it creates a hidden form field wiht that name within the form.
  49  * @param element the element in the form. Should be something that can be
  50  *      passed to Y.one.
  51  */
  52 M.core_scroll_manager.save_scroll_pos = function(Y, element) {
  53     if (typeof(element) == 'string') {
  54         // Have to use getElementById here because element id can contain :.
  55         element = Y.one(document.getElementById(element));
  56     }
  57     var form = element.ancestor('form');
  58     if (!form) {
  59         return;
  60     }
  61     var scrollpos = form.one('input[name=scrollpos]');
  62     if (!scrollpos) {
  63         scrollpos = form.appendChild(form.create('<input type="hidden" name="scrollpos" />'));
  64     }
  65     scrollpos.set('value', form.get('docScrollY'));
  66 }
  67
  68 /**
  69  * Event handler that can be used on a link. Assumes that the link already
  70  * contains at least one URL parameter.
  71  */
  72 M.core_scroll_manager.save_scroll_action = function(e) {
  73     var link = e.target.ancestor('a[href]');
  74     if (!link) {
  75         M.core_scroll_manager.save_scroll_pos({}, e.target);
  76         return;
  77     }
  78     link.set('href', link.get('href') + '&scrollpos=' + link.get('docScrollY'));
  79 }
  80
  81 /**
  82  * If there is a parameter like scrollpos=123 in the URL, scroll to that saved position.
  83  * @deprecated since Moodle 4.0
  84  * @see question\bank\qbank_previewquestion\amd\src
  85  * @todo Final deprecation on Moodle 4.4 MDL-72438
  86  */
  87 M.core_scroll_manager.scroll_to_saved_pos = function(Y) {
  88     Y.log("The scroll_to_saved_pos function has been deprecated. " +
  89         "Please use scrollToSavedPos() in qbank_preview/preview.js instead.", 'moodle-core-notification', 'warn');
  90
  91     var matches = window.location.href.match(/^.*[?&]scrollpos=(\d*)(?:&|$|#).*$/, '$1');
  92     if (matches) {
  93         // onDOMReady is the effective one here. I am leaving the immediate call to
  94         // window.scrollTo in case it reduces flicker.
  95         window.scrollTo(0, matches[1]);
  96         Y.on('domready', function() { window.scrollTo(0, matches[1]); });
  97
  98         // And the following horror is necessary to make it work in IE 8.
  99         // Note that the class ie8 on body is only there in Moodle 2.0 and OU Moodle.
 100         if (Y.one('body').hasClass('ie')) {
 101             M.core_scroll_manager.force_ie_to_scroll(Y, matches[1])
 102         }
 103     }
 104 }
 105
 106 /**
 107  * Beat IE into submission.
 108  * @param targetpos the target scroll position.
 109  */
 110 M.core_scroll_manager.force_ie_to_scroll = function(Y, targetpos) {
 111     var hackcount = 25;
 112     function do_scroll() {
 113         window.scrollTo(0, targetpos);
 114         hackcount -= 1;
 115         if (hackcount > 0) {
 116             setTimeout(do_scroll, 10);
 117         }
 118     }
 119     Y.on('load', do_scroll, window);
 120 }
 121
 122 M.core_question_engine = M.core_question_engine || {};
 123
 124 /**
 125  * Flag used by M.core_question_engine.prevent_repeat_submission.
 126  */
 127 M.core_question_engine.questionformalreadysubmitted = false;
 128
 129 /**
 130  * Initialise a question submit button. This saves the scroll position and
 131  * sets the fragment on the form submit URL so the page reloads in the right place.
 132  * @param button the id of the button in the HTML.
 133  */
 134 M.core_question_engine.init_submit_button = function(Y, button) {
 135     require(['core_form/submit'], function(submit) {
 136         submit.init(button);
 137     });
 138     var totalQuestionsInPage = document.querySelectorAll('div.que').length;
 139     var buttonel = document.getElementById(button);
 140     var outeruniqueid = buttonel.closest('.que').id;
 141     Y.on('click', function(e) {
 142         M.core_scroll_manager.save_scroll_pos(Y, button);
 143         if (totalQuestionsInPage > 1) {
 144             // Only change the form action if the page have more than one question.
 145             buttonel.form.action = buttonel.form.action + '#' + outeruniqueid;
 146         }
 147     }, buttonel);
 148 }
 149
 150 /**
 151  * Initialise a form that contains questions printed using print_question.
 152  * This has the effect of:
 153  * 1. Turning off browser autocomlete.
 154  * 2. Stopping enter from submitting the form (or toggling the next flag) unless
 155  *    keyboard focus is on the submit button or the flag.
 156  * 3. Removes any '.questionflagsavebutton's, since we have JavaScript to toggle
 157  *    the flags using ajax.
 158  * 4. Scroll to the position indicated by scrollpos= in the URL, if it is there.
 159  * 5. Prevent the user from repeatedly submitting the form.
 160  * @param Y the Yahoo object. Needs to have the DOM and Event modules loaded.
 161  * @param form something that can be passed to Y.one, to find the form element.
 162  * @deprecated since Moodle 4.0
 163  * @see question\bank\qbank_previewquestion\amd\src
 164  * @todo Final deprecation on Moodle 4.4 MDL-72438
 165  */
 166 M.core_question_engine.init_form = function(Y, form) {
 167     Y.log("The core_question_engine.init_form function has been deprecated. " +
 168         "Please use setupQuestionForm() in qbank_preview/preview.js instead.", 'moodle-core-notification', 'warn');
 169
 170     Y.one(form).setAttribute('autocomplete', 'off');
 171
 172     Y.on('submit', M.core_question_engine.prevent_repeat_submission, form, form, Y);
 173
 174     Y.on('key', function (e) {
 175         if (!e.target.test('a') && !e.target.test('input[type=submit]') &&
 176                 !e.target.test('input[type=img]') && !e.target.test('textarea') && !e.target.test('[contenteditable=true]')) {
 177             e.preventDefault();
 178         }
 179     }, form, 'press:13');
 180
 181     Y.one(form).all('.questionflagsavebutton').remove();
 182
 183     M.core_scroll_manager.scroll_to_saved_pos(Y);
 184 }
 185
 186 /**
 187  * Event handler to stop a question form being submitted more than once.
 188  * @param e the form submit event.
 189  * @param form the form element.
 190  * @deprecated since Moodle 4.0
 191  * @see question\bank\qbank_previewquestion\amd\src
 192  * @todo Final deprecation on Moodle 4.4 MDL-72438
 193  */
 194 M.core_question_engine.prevent_repeat_submission = function(e, Y) {
 195     Y.log("The prevent_repeat_submission function has been deprecated. " +
 196         "Please use preventRepeatSubmission in qbank_preview/preview.js instead.", 'moodle-core-notification', 'warn');
 197
 198     if (M.core_question_engine.questionformalreadysubmitted) {
 199         e.halt();
 200         return;
 201     }
 202
 203     setTimeout(function() {
 204         Y.all('input[type=submit]').set('disabled', true);
 205     }, 0);
 206     M.core_question_engine.questionformalreadysubmitted = true;
 207 }