MDL-67814 core_h5p: Update to eslintignore to handle included file.
[moodle.git] / question / type / ddwtos / amd / src / ddwtos.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/>.
16 /**
17  * JavaScript to make drag-drop into text questions work.
18  *
19  * Some vocabulary to help understand this code:
20  *
21  * The question text contains 'drops' - blanks into which the 'drags', the missing
22  * words, can be put.
23  *
24  * The thing that can be moved into the drops are called 'drags'. There may be
25  * multiple copies of the 'same' drag which does not really cause problems.
26  * Each drag has a 'choice' number which is the value set on the drop's hidden
27  * input when this drag is placed in a drop.
28  *
29  * These may be in separate 'groups', distinguished by colour.
30  * Things can only interact with other things in the same group.
31  * The groups are numbered from 1.
32  *
33  * The place where a given drag started from is called its 'home'.
34  *
35  * @module     qtype_ddwtos/ddwtos
36  * @package    qtype_ddwtos
37  * @copyright  2018 The Open University
38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  * @since      3.6
40  */
41 define(['jquery', 'core/dragdrop', 'core/key_codes'], function($, dragDrop, keys) {
43     "use strict";
45     /**
46      * Object to handle one drag-drop into text question.
47      *
48      * @param {String} containerId id of the outer div for this question.
49      * @param {boolean} readOnly whether the question is being displayed read-only.
50      * @constructor
51      */
52     function DragDropToTextQuestion(containerId, readOnly) {
53         this.containerId = containerId;
54         if (readOnly) {
55             this.getRoot().addClass('qtype_ddwtos-readonly');
56         }
57         this.resizeAllDragsAndDrops();
58         this.cloneDrags();
59         this.positionDrags();
60     }
62     /**
63      * In each group, resize all the items to be the same size.
64      */
65     DragDropToTextQuestion.prototype.resizeAllDragsAndDrops = function() {
66         var thisQ = this;
67         this.getRoot().find('.answercontainer > div').each(function(i, node) {
68             thisQ.resizeAllDragsAndDropsInGroup(
69                 thisQ.getClassnameNumericSuffix($(node), 'draggrouphomes'));
70         });
71     };
73     /**
74      * In a given group, set all the drags and drops to be the same size.
75      *
76      * @param {int} group the group number.
77      */
78     DragDropToTextQuestion.prototype.resizeAllDragsAndDropsInGroup = function(group) {
79         var thisQ = this,
80             dragHomes = this.getRoot().find('.draggrouphomes' + group + ' span.draghome'),
81             maxWidth = 0,
82             maxHeight = 0;
84         // Find the maximum size of any drag in this groups.
85         dragHomes.each(function(i, drag) {
86             maxWidth = Math.max(maxWidth, Math.ceil(drag.offsetWidth));
87             maxHeight = Math.max(maxHeight, Math.ceil(0 + drag.offsetHeight));
88         });
90         // The size we will want to set is a bit bigger than this.
91         maxWidth += 8;
92         maxHeight += 2;
94         // Set each drag home to that size.
95         dragHomes.each(function(i, drag) {
96             thisQ.setElementSize(drag, maxWidth, maxHeight);
97         });
99         // Set each drop to that size.
100         this.getRoot().find('span.drop.group' + group).each(function(i, drop) {
101             thisQ.setElementSize(drop, maxWidth, maxHeight);
102         });
103     };
105     /**
106      * Set a given DOM element to be a particular size.
107      *
108      * @param {HTMLElement} element
109      * @param {int} width
110      * @param {int} height
111      */
112     DragDropToTextQuestion.prototype.setElementSize = function(element, width, height) {
113         $(element).width(width).height(height).css('lineHeight', height + 'px');
114     };
116     /**
117      * Invisible 'drag homes' are output by the renderer. These have the same properties
118      * as the drag items but are invisible. We clone these invisible elements to make the
119      * actual drag items.
120      */
121     DragDropToTextQuestion.prototype.cloneDrags = function() {
122         var thisQ = this;
123         this.getRoot().find('span.draghome').each(function(index, draghome) {
124             thisQ.cloneDragsForOneChoice($(draghome));
125         });
126     };
128     /**
129      * Clone drag item for one choice.
130      *
131      * @param {jQuery} dragHome the drag home to clone.
132      */
133     DragDropToTextQuestion.prototype.cloneDragsForOneChoice = function(dragHome) {
134         if (dragHome.hasClass('infinite')) {
135             var noOfDrags = this.noOfDropsInGroup(this.getGroup(dragHome));
136             for (var i = 0; i < noOfDrags; i++) {
137                 this.cloneDrag(dragHome);
138             }
139         } else {
140             this.cloneDrag(dragHome);
141         }
142     };
144     /**
145      * Clone drag item.
146      *
147      * @param {jQuery} dragHome
148      */
149     DragDropToTextQuestion.prototype.cloneDrag = function(dragHome) {
150         var drag = dragHome.clone();
151         drag.removeClass('draghome')
152             .addClass('drag unplaced moodle-has-zindex')
153             .offset(dragHome.offset());
154         this.getRoot().find('div.drags').append(drag);
155     };
157     /**
158      * Update the position of drags.
159      */
160     DragDropToTextQuestion.prototype.positionDrags = function() {
161         var thisQ = this,
162             root = this.getRoot();
164         // First move all items back home.
165         root.find('span.drag').each(function(i, dragNode) {
166             var drag = $(dragNode),
167                 currentPlace = thisQ.getClassnameNumericSuffix(drag, 'inplace');
168             drag.addClass('unplaced')
169                 .removeClass('placed')
170                 .offset(thisQ.getDragHome(thisQ.getGroup(drag), thisQ.getChoice(drag)).offset());
171             if (currentPlace !== null) {
172                 drag.removeClass('inplace' + currentPlace);
173             }
174         });
176         // Then place the once that should be placed.
177         root.find('input.placeinput').each(function(i, inputNode) {
178             var input = $(inputNode),
179                 choice = input.val(),
180                 place = thisQ.getPlace(input);
182             // Record the last known position of the drop.
183             var drop = root.find('.drop.place' + place),
184                 dropPosition = drop.offset();
185             drop.data('prev-top', dropPosition.top).data('prev-left', dropPosition.left);
187             if (choice === '0') {
188                 // No item in this place.
189                 return;
190             }
192             thisQ.getUnplacedChoice(thisQ.getGroup(input), choice)
193                 .removeClass('unplaced')
194                 .addClass('placed inplace' + place)
195                 .offset(root.find('.drop.place' + place).offset());
196         });
197     };
199     /**
200      * Check to see if a drop target has moved. If so, refresh the layout.
201      */
202     DragDropToTextQuestion.prototype.fixLayoutIfDropsMoved = function() {
203         var thisQ = this,
204             root = this.getRoot(),
205             didMove = false;
207         root.find('input.placeinput').each(function(i, inputNode) {
208             var place = thisQ.getPlace($(inputNode)),
209                 drop = root.find('.drop.place' + place),
210                 dropPosition = drop.offset(),
211                 prevTop = drop.data('prev-top'),
212                 prevLeft = drop.data('prev-left');
213             if (prevLeft === undefined || prevTop === undefined) {
214                 // Question is not set up yet. Nothing to do.
215                 return;
216             }
217             if (prevTop === dropPosition.top && prevLeft === dropPosition.left) {
218                 // Things have not moved.
219                 return;
220             }
221             didMove = true;
222         });
224         if (didMove) {
225             // We need to reposition things.
226             this.positionDrags();
227         }
228     };
230     /**
231      * Handles the start of dragging an item.
232      *
233      * @param {Event} e the touch start or mouse down event.
234      */
235     DragDropToTextQuestion.prototype.handleDragStart = function(e) {
236         var thisQ = this,
237             drag = $(e.target).closest('.drag');
239         var info = dragDrop.prepare(e);
240         if (!info.start) {
241             return;
242         }
244         var currentPlace = this.getClassnameNumericSuffix(drag, 'inplace');
245         if (currentPlace !== null) {
246             this.setInputValue(currentPlace, 0);
247             drag.removeClass('inplace' + currentPlace);
248         }
250         drag.addClass('beingdragged');
251         dragDrop.start(e, drag, function(x, y, drag) {
252             thisQ.dragMove(x, y, drag);
253         }, function(x, y, drag) {
254             thisQ.dragEnd(x, y, drag);
255         });
256     };
258     /**
259      * Called whenever the currently dragged items moves.
260      *
261      * @param {Number} pageX the x position.
262      * @param {Number} pageY the y position.
263      * @param {jQuery} drag the item being moved.
264      */
265     DragDropToTextQuestion.prototype.dragMove = function(pageX, pageY, drag) {
266         var thisQ = this;
267         this.getRoot().find('span.drop.group' + this.getGroup(drag)).each(function(i, dropNode) {
268             var drop = $(dropNode);
269             if (thisQ.isPointInDrop(pageX, pageY, drop)) {
270                 drop.addClass('valid-drag-over-drop');
271             } else {
272                 drop.removeClass('valid-drag-over-drop');
273             }
274         });
275     };
277     /**
278      * Called when user drops a drag item.
279      *
280      * @param {Number} pageX the x position.
281      * @param {Number} pageY the y position.
282      * @param {jQuery} drag the item being moved.
283      */
284     DragDropToTextQuestion.prototype.dragEnd = function(pageX, pageY, drag) {
285         var thisQ = this,
286             root = this.getRoot(),
287             placed = false;
288         root.find('span.drop.group' + this.getGroup(drag)).each(function(i, dropNode) {
289             var drop = $(dropNode);
290             if (!thisQ.isPointInDrop(pageX, pageY, drop)) {
291                 // Not this drop.
292                 return true;
293             }
295             // Now put this drag into the drop.
296             drop.removeClass('valid-drag-over-drop');
297             thisQ.sendDragToDrop(drag, drop);
298             placed = true;
299             return false; // Stop the each() here.
300         });
302         if (!placed) {
303             this.sendDragHome(drag);
304         }
305     };
307     /**
308      * Animate a drag item into a given place (or back home).
309      *
310      * @param {jQuery|null} drag the item to place. If null, clear the place.
311      * @param {jQuery} drop the place to put it.
312      */
313     DragDropToTextQuestion.prototype.sendDragToDrop = function(drag, drop) {
314         // Is there already a drag in this drop? if so, evict it.
315         var oldDrag = this.getCurrentDragInPlace(this.getPlace(drop));
316         if (oldDrag.length !== 0) {
317             this.sendDragHome(oldDrag);
318         }
320         if (drag.length === 0) {
321             this.setInputValue(this.getPlace(drop), 0);
322         } else {
323             this.setInputValue(this.getPlace(drop), this.getChoice(drag));
324             drag.removeClass('unplaced')
325                 .addClass('placed inplace' + this.getPlace(drop));
326             this.animateTo(drag, drop);
327         }
328     };
330     /**
331      * Animate a drag back to its home.
332      *
333      * @param {jQuery} drag the item being moved.
334      */
335     DragDropToTextQuestion.prototype.sendDragHome = function(drag) {
336         drag.removeClass('placed').addClass('unplaced');
337         var currentPlace = this.getClassnameNumericSuffix(drag, 'inplace');
338         if (currentPlace !== null) {
339             drag.removeClass('inplace' + currentPlace);
340         }
342         this.animateTo(drag, this.getDragHome(this.getGroup(drag), this.getChoice(drag)));
343     };
345     /**
346      * Handles keyboard events on drops.
347      *
348      * Drops are focusable. Once focused, right/down/space switches to the next choice, and
349      * left/up switches to the previous. Escape clear.
350      *
351      * @param {KeyboardEvent} e
352      */
353     DragDropToTextQuestion.prototype.handleKeyPress = function(e) {
354         var drop = $(e.target).closest('.drop'),
355             currentDrag = this.getCurrentDragInPlace(this.getPlace(drop)),
356             nextDrag = $();
358         switch (e.keyCode) {
359             case keys.space:
360             case keys.arrowRight:
361             case keys.arrowDown:
362                 nextDrag = this.getNextDrag(this.getGroup(drop), currentDrag);
363                 break;
365             case keys.arrowLeft:
366             case keys.arrowUp:
367                 nextDrag = this.getPreviousDrag(this.getGroup(drop), currentDrag);
368                 break;
370             case keys.escape:
371                 break;
373             default:
374                 return; // To avoid the preventDefault below.
375         }
377         e.preventDefault();
378         this.sendDragToDrop(nextDrag, drop);
379     };
381     /**
382      * Choose the next drag in a group.
383      *
384      * @param {int} group which group.
385      * @param {jQuery} drag current choice (empty jQuery if there isn't one).
386      * @return {jQuery} the next drag in that group, or null if there wasn't one.
387      */
388     DragDropToTextQuestion.prototype.getNextDrag = function(group, drag) {
389         var choice,
390             numChoices = this.noOfChoicesInGroup(group);
392         if (drag.length === 0) {
393             choice = 1; // Was empty, so we want to select the first choice.
394         } else {
395             choice = this.getChoice(drag) + 1;
396         }
398         var next = this.getUnplacedChoice(group, choice);
399         while (next.length === 0 && choice < numChoices) {
400             choice++;
401             next = this.getUnplacedChoice(group, choice);
402         }
404         return next;
405     };
407     /**
408      * Choose the previous drag in a group.
409      *
410      * @param {int} group which group.
411      * @param {jQuery} drag current choice (empty jQuery if there isn't one).
412      * @return {jQuery} the next drag in that group, or null if there wasn't one.
413      */
414     DragDropToTextQuestion.prototype.getPreviousDrag = function(group, drag) {
415         var choice;
417         if (drag.length === 0) {
418             choice = this.noOfChoicesInGroup(group);
419         } else {
420             choice = this.getChoice(drag) - 1;
421         }
423         var previous = this.getUnplacedChoice(group, choice);
424         while (previous.length === 0 && choice > 1) {
425             choice--;
426             previous = this.getUnplacedChoice(group, choice);
427         }
429         // Does this choice exist?
430         return previous;
431     };
433     /**
434      * Animate an object to the given destination.
435      *
436      * @param {jQuery} drag the element to be animated.
437      * @param {jQuery} target element marking the place to move it to.
438      */
439     DragDropToTextQuestion.prototype.animateTo = function(drag, target) {
440         var currentPos = drag.offset(),
441             targetPos = target.offset();
442         drag.addClass('beingdragged');
444         // Animate works in terms of CSS position, whereas locating an object
445         // on the page works best with jQuery offset() function. So, to get
446         // the right target position, we work out the required change in
447         // offset() and then add that to the current CSS position.
448         drag.animate(
449             {
450                 left: parseInt(drag.css('left')) + targetPos.left - currentPos.left,
451                 top: parseInt(drag.css('top')) + targetPos.top - currentPos.top
452             },
453             {
454                 duration: 'fast',
455                 done: function() {
456                     drag.removeClass('beingdragged');
457                     // It seems that the animation sometimes leaves the drag
458                     // one pixel out of position. Put it in exactly the right place.
459                     drag.offset(targetPos);
460                 }
461             }
462         );
463     };
465     /**
466      * Detect if a point is inside a given DOM node.
467      *
468      * @param {Number} pageX the x position.
469      * @param {Number} pageY the y position.
470      * @param {jQuery} drop the node to check (typically a drop).
471      * @return {boolean} whether the point is inside the node.
472      */
473     DragDropToTextQuestion.prototype.isPointInDrop = function(pageX, pageY, drop) {
474         var position = drop.offset();
475         return pageX >= position.left && pageX < position.left + drop.width()
476                 && pageY >= position.top && pageY < position.top + drop.height();
477     };
479     /**
480      * Set the value of the hidden input for a place, to record what is currently there.
481      *
482      * @param {int} place which place to set the input value for.
483      * @param {int} choice the value to set.
484      */
485     DragDropToTextQuestion.prototype.setInputValue = function(place, choice) {
486         this.getRoot().find('input.placeinput.place' + place).val(choice);
487     };
489     /**
490      * Get the outer div for this question.
491      *
492      * @returns {jQuery} containing that div.
493      */
494     DragDropToTextQuestion.prototype.getRoot = function() {
495         return $(document.getElementById(this.containerId));
496     };
498     /**
499      * Get drag home for a given choice.
500      *
501      * @param {int} group the group.
502      * @param {int} choice the choice number.
503      * @returns {jQuery} containing that div.
504      */
505     DragDropToTextQuestion.prototype.getDragHome = function(group, choice) {
506         return this.getRoot().find('.draghome.group' + group + '.choice' + choice);
507     };
509     /**
510      * Get an unplaced choice for a particular group.
511      *
512      * @param {int} group the group.
513      * @param {int} choice the choice number.
514      * @returns {jQuery} jQuery wrapping the unplaced choice. If there isn't one, the jQuery will be empty.
515      */
516     DragDropToTextQuestion.prototype.getUnplacedChoice = function(group, choice) {
517         return this.getRoot().find('.drag.group' + group + '.choice' + choice + '.unplaced').slice(0, 1);
518     };
520     /**
521      * Get the drag that is currently in a given place.
522      *
523      * @param {int} place the place number.
524      * @return {jQuery} the current drag (or an empty jQuery if none).
525      */
526     DragDropToTextQuestion.prototype.getCurrentDragInPlace = function(place) {
527         return this.getRoot().find('span.drag.inplace' + place);
528     };
530     /**
531      * Return the number of blanks in a given group.
532      *
533      * @param {int} group the group number.
534      * @returns {int} the number of drops.
535      */
536     DragDropToTextQuestion.prototype.noOfDropsInGroup = function(group) {
537         return this.getRoot().find('.drop.group' + group).length;
538     };
540     /**
541      * Return the number of choices in a given group.
542      *
543      * @param {int} group the group number.
544      * @returns {int} the number of choices.
545      */
546     DragDropToTextQuestion.prototype.noOfChoicesInGroup = function(group) {
547         return this.getRoot().find('.draghome.group' + group).length;
548     };
550     /**
551      * Return the number at the end of the CSS class name with the given prefix.
552      *
553      * @param {jQuery} node
554      * @param {String} prefix name prefix
555      * @returns {Number|null} the suffix if found, else null.
556      */
557     DragDropToTextQuestion.prototype.getClassnameNumericSuffix = function(node, prefix) {
558         var classes = node.attr('class');
559         if (classes !== '') {
560             var classesArr = classes.split(' ');
561             for (var index = 0; index < classesArr.length; index++) {
562                 var patt1 = new RegExp('^' + prefix + '([0-9])+$');
563                 if (patt1.test(classesArr[index])) {
564                     var patt2 = new RegExp('([0-9])+$');
565                     var match = patt2.exec(classesArr[index]);
566                     return Number(match[0]);
567                 }
568             }
569         }
570         return null;
571     };
573     /**
574      * Get the choice number of a drag.
575      *
576      * @param {jQuery} drag the drag.
577      * @returns {Number} the choice number.
578      */
579     DragDropToTextQuestion.prototype.getChoice = function(drag) {
580         return this.getClassnameNumericSuffix(drag, 'choice');
581     };
583     /**
584      * Given a DOM node that is significant to this question
585      * (drag, drop, ...) get the group it belongs to.
586      *
587      * @param {jQuery} node a DOM node.
588      * @returns {Number} the group it belongs to.
589      */
590     DragDropToTextQuestion.prototype.getGroup = function(node) {
591         return this.getClassnameNumericSuffix(node, 'group');
592     };
594     /**
595      * Get the place number of a drop, or its corresponding hidden input.
596      *
597      * @param {jQuery} node the DOM node.
598      * @returns {Number} the place number.
599      */
600     DragDropToTextQuestion.prototype.getPlace = function(node) {
601         return this.getClassnameNumericSuffix(node, 'place');
602     };
604     /**
605      * Singleton that tracks all the DragDropToTextQuestions on this page, and deals
606      * with event dispatching.
607      *
608      * @type {Object}
609      */
610     var questionManager = {
611         /**
612          * {boolean} used to ensure the event handlers are only initialised once per page.
613          */
614         eventHandlersInitialised: false,
616         /**
617          * {DragDropToTextQuestion[]} all the questions on this page, indexed by containerId (id on the .que div).
618          */
619         questions: {},
621         /**
622          * Initialise questions.
623          *
624          * @param {String} containerId id of the outer div for this question.
625          * @param {boolean} readOnly whether the question is being displayed read-only.
626          */
627         init: function(containerId, readOnly) {
628             questionManager.questions[containerId] = new DragDropToTextQuestion(containerId, readOnly);
629             if (!questionManager.eventHandlersInitialised) {
630                 questionManager.setupEventHandlers();
631                 questionManager.eventHandlersInitialised = true;
632             }
633         },
635         /**
636          * Set up the event handlers that make this question type work. (Done once per page.)
637          */
638         setupEventHandlers: function() {
639             $('body').on('mousedown touchstart',
640                     '.que.ddwtos:not(.qtype_ddwtos-readonly) span.drag',
641                     questionManager.handleDragStart)
642                 .on('keydown',
643                     '.que.ddwtos:not(.qtype_ddwtos-readonly) span.drop',
644                     questionManager.handleKeyPress);
646             $(window).on('resize', questionManager.handleWindowResize);
647             setTimeout(questionManager.fixLayoutIfThingsMoved, 100);
648         },
650         /**
651          * Handle mouse down / touch start on drags.
652          * @param {Event} e the DOM event.
653          */
654         handleDragStart: function(e) {
655             e.preventDefault();
656             var question = questionManager.getQuestionForEvent(e);
657             if (question) {
658                 question.handleDragStart(e);
659             }
660         },
662         /**
663          * Handle key down / press on drops.
664          * @param {KeyboardEvent} e
665          */
666         handleKeyPress: function(e) {
667             var question = questionManager.getQuestionForEvent(e);
668             if (question) {
669                 question.handleKeyPress(e);
670             }
671         },
673         /**
674          * Handle when the window is resized.
675          */
676         handleWindowResize: function() {
677             for (var containerId in questionManager.questions) {
678                 if (questionManager.questions.hasOwnProperty(containerId)) {
679                     questionManager.questions[containerId].positionDrags();
680                 }
681             }
682         },
684         /**
685          * Sometimes, despite our best efforts, things change in a way that cannot
686          * be specifically caught (e.g. dock expanding or collapsing in Boost).
687          * Therefore, we need to periodically check everything is in the right position.
688          */
689         fixLayoutIfThingsMoved: function() {
690             for (var containerId in questionManager.questions) {
691                 if (questionManager.questions.hasOwnProperty(containerId)) {
692                     questionManager.questions[containerId].fixLayoutIfDropsMoved();
693                 }
694             }
696             // We use setTimeout after finishing work, rather than setInterval,
697             // in case positioning things is slow. We want 100 ms gap
698             // between executions, not what setInterval does.
699             setTimeout(questionManager.fixLayoutIfThingsMoved, 100);
700         },
702         /**
703          * Given an event, work out which question it affects.
704          *
705          * @param {Event} e the event.
706          * @returns {DragDropToTextQuestion|undefined} The question, or undefined.
707          */
708         getQuestionForEvent: function(e) {
709             var containerId = $(e.currentTarget).closest('.que.ddwtos').attr('id');
710             return questionManager.questions[containerId];
711         }
712     };
714     /**
715      * @alias module:qtype_ddwtos/ddwtos
716      */
717     return {
718         /**
719          * Initialise one drag-drop into text question.
720          *
721          * @param {String} containerId id of the outer div for this question.
722          * @param {boolean} readOnly whether the question is being displayed read-only.
723          */
724         init: questionManager.init
725     };
726 });