weekly release 3.7dev
[moodle.git] / lib / amd / src / form-autocomplete.js
CommitLineData
60a1ea56
DW
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 * Autocomplete wrapper for select2 library.
18 *
19 * @module core/form-autocomplete
20 * @class autocomplete
21 * @package core
22 * @copyright 2015 Damyon Wiese <damyon@moodle.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 * @since 3.0
25 */
26/* globals require: false */
df5feea4
AN
27define(
28 ['jquery', 'core/log', 'core/str', 'core/templates', 'core/notification', 'core/loadingicon'],
29function($, log, str, templates, notification, LoadingIcon) {
60a1ea56
DW
30
31 // Private functions and variables.
32 /** @var {Object} KEYS - List of keycode constants. */
33 var KEYS = {
34 DOWN: 40,
35 ENTER: 13,
36 SPACE: 32,
37 ESCAPE: 27,
e375029e 38 COMMA: 44,
60a1ea56
DW
39 UP: 38
40 };
41
b7df2485
DW
42 var uniqueId = $.now();
43
60a1ea56
DW
44 /**
45 * Make an item in the selection list "active".
46 *
47 * @method activateSelection
48 * @private
49 * @param {Number} index The index in the current (visible) list of selection.
273b2556 50 * @param {Object} state State variables for this autocomplete element.
e994dea0 51 * @return {Promise}
60a1ea56 52 */
273b2556 53 var activateSelection = function(index, state) {
60a1ea56 54 // Find the elements in the DOM.
273b2556 55 var selectionElement = $(document.getElementById(state.selectionId));
60a1ea56
DW
56
57 // Count the visible items.
58 var length = selectionElement.children('[aria-selected=true]').length;
59 // Limit the index to the upper/lower bounds of the list (wrap in both directions).
60 index = index % length;
61 while (index < 0) {
62 index += length;
63 }
64 // Find the specified element.
65 var element = $(selectionElement.children('[aria-selected=true]').get(index));
66 // Create an id we can assign to this element.
273b2556 67 var itemId = state.selectionId + '-' + index;
60a1ea56
DW
68
69 // Deselect all the selections.
70 selectionElement.children().attr('data-active-selection', false).attr('id', '');
71 // Select only this suggestion and assign it the id.
72 element.attr('data-active-selection', true).attr('id', itemId);
73 // Tell the input field it has a new active descendant so the item is announced.
74 selectionElement.attr('aria-activedescendant', itemId);
e994dea0
AN
75
76 return $.Deferred().resolve();
60a1ea56
DW
77 };
78
f992dcf6
DP
79 /**
80 * Update the element that shows the currently selected items.
81 *
82 * @method updateSelectionList
83 * @private
84 * @param {Object} options Original options for this autocomplete element.
85 * @param {Object} state State variables for this autocomplete element.
86 * @param {JQuery} originalSelect The JQuery object matching the hidden select list.
e994dea0 87 * @return {Promise}
f992dcf6
DP
88 */
89 var updateSelectionList = function(options, state, originalSelect) {
e994dea0
AN
90 var pendingKey = 'form-autocomplete-updateSelectionList-' + state.inputId;
91 M.util.js_pending(pendingKey);
92
f992dcf6
DP
93 // Build up a valid context to re-render the template.
94 var items = [];
95 var newSelection = $(document.getElementById(state.selectionId));
96 var activeId = newSelection.attr('aria-activedescendant');
97 var activeValue = false;
98
99 if (activeId) {
100 activeValue = $(document.getElementById(activeId)).attr('data-value');
101 }
102 originalSelect.children('option').each(function(index, ele) {
103 if ($(ele).prop('selected')) {
a97c9370 104 var label;
105 if ($(ele).data('html')) {
106 label = $(ele).data('html');
107 } else {
108 label = $(ele).html();
109 }
110 items.push({label: label, value: $(ele).attr('value')});
f992dcf6
DP
111 }
112 });
9f5f3dcc 113 var context = $.extend({items: items}, options, state);
f992dcf6
DP
114
115 // Render the template.
e994dea0
AN
116 return templates.render('core/form_autocomplete_selection', context)
117 .then(function(html, js) {
f992dcf6 118 // Add it to the page.
e994dea0 119 templates.replaceNodeContents(newSelection, html, js);
f992dcf6
DP
120
121 if (activeValue !== false) {
122 // Reselect any previously selected item.
123 newSelection.children('[aria-selected=true]').each(function(index, ele) {
124 if ($(ele).attr('data-value') === activeValue) {
125 activateSelection(index, state);
126 }
127 });
128 }
e994dea0
AN
129
130 return activeValue;
131 })
132 .then(function() {
133 return M.util.js_complete(pendingKey);
134 })
135 .catch(notification.exception);
1eaba735
FM
136 };
137
138 /**
139 * Notify of a change in the selection.
140 *
141 * @param {jQuery} originalSelect The jQuery object matching the hidden select list.
1eaba735
FM
142 */
143 var notifyChange = function(originalSelect) {
144 if (typeof M.core_formchangechecker !== 'undefined') {
eb97811b
MG
145 M.core_formchangechecker.set_form_changed();
146 }
f992dcf6
DP
147 originalSelect.change();
148 };
149
60a1ea56 150 /**
563fe0a5 151 * Remove the given item from the list of selected things.
60a1ea56 152 *
563fe0a5 153 * @method deselectItem
60a1ea56 154 * @private
273b2556
DW
155 * @param {Object} options Original options for this autocomplete element.
156 * @param {Object} state State variables for this autocomplete element.
c96f55e6 157 * @param {Element} item The item to be deselected.
60a1ea56 158 * @param {Element} originalSelect The original select list.
e994dea0 159 * @return {Promise}
60a1ea56 160 */
273b2556 161 var deselectItem = function(options, state, item, originalSelect) {
563fe0a5
RW
162 var selectedItemValue = $(item).attr('data-value');
163
164 // We can only deselect items if this is a multi-select field.
273b2556 165 if (options.multiple) {
563fe0a5
RW
166 // Look for a match, and toggle the selected property if there is a match.
167 originalSelect.children('option').each(function(index, ele) {
168 if ($(ele).attr('value') == selectedItemValue) {
169 $(ele).prop('selected', false);
bdd60287
DW
170 // We remove newly created custom tags from the suggestions list when they are deselected.
171 if ($(ele).attr('data-iscustom')) {
172 $(ele).remove();
173 }
60a1ea56 174 }
563fe0a5
RW
175 });
176 }
60a1ea56 177 // Rerender the selection list.
e994dea0
AN
178 return updateSelectionList(options, state, originalSelect)
179 .then(function() {
180 // Notify that the selection changed.
181 notifyChange(originalSelect);
182
183 return;
184 });
60a1ea56
DW
185 };
186
187 /**
188 * Make an item in the suggestions "active" (about to be selected).
189 *
190 * @method activateItem
191 * @private
192 * @param {Number} index The index in the current (visible) list of suggestions.
273b2556 193 * @param {Object} state State variables for this instance of autocomplete.
e994dea0 194 * @return {Promise}
60a1ea56 195 */
273b2556 196 var activateItem = function(index, state) {
60a1ea56 197 // Find the elements in the DOM.
273b2556
DW
198 var inputElement = $(document.getElementById(state.inputId));
199 var suggestionsElement = $(document.getElementById(state.suggestionsId));
60a1ea56
DW
200
201 // Count the visible items.
202 var length = suggestionsElement.children('[aria-hidden=false]').length;
203 // Limit the index to the upper/lower bounds of the list (wrap in both directions).
204 index = index % length;
205 while (index < 0) {
206 index += length;
207 }
208 // Find the specified element.
209 var element = $(suggestionsElement.children('[aria-hidden=false]').get(index));
210 // Find the index of this item in the full list of suggestions (including hidden).
211 var globalIndex = $(suggestionsElement.children('[role=option]')).index(element);
212 // Create an id we can assign to this element.
273b2556 213 var itemId = state.suggestionsId + '-' + globalIndex;
60a1ea56
DW
214
215 // Deselect all the suggestions.
216 suggestionsElement.children().attr('aria-selected', false).attr('id', '');
217 // Select only this suggestion and assign it the id.
218 element.attr('aria-selected', true).attr('id', itemId);
219 // Tell the input field it has a new active descendant so the item is announced.
220 inputElement.attr('aria-activedescendant', itemId);
32f3de56
DW
221
222 // Scroll it into view.
223 var scrollPos = element.offset().top
224 - suggestionsElement.offset().top
225 + suggestionsElement.scrollTop()
226 - (suggestionsElement.height() / 2);
e994dea0 227 return suggestionsElement.animate({
32f3de56 228 scrollTop: scrollPos
e994dea0 229 }, 100).promise();
60a1ea56
DW
230 };
231
232 /**
233 * Find the index of the current active suggestion, and activate the next one.
234 *
235 * @method activateNextItem
236 * @private
273b2556 237 * @param {Object} state State variable for this auto complete element.
e994dea0 238 * @return {Promise}
60a1ea56 239 */
273b2556 240 var activateNextItem = function(state) {
60a1ea56 241 // Find the list of suggestions.
273b2556 242 var suggestionsElement = $(document.getElementById(state.suggestionsId));
60a1ea56
DW
243 // Find the active one.
244 var element = suggestionsElement.children('[aria-selected=true]');
245 // Find it's index.
246 var current = suggestionsElement.children('[aria-hidden=false]').index(element);
247 // Activate the next one.
e994dea0 248 return activateItem(current + 1, state);
60a1ea56
DW
249 };
250
251 /**
252 * Find the index of the current active selection, and activate the previous one.
253 *
254 * @method activatePreviousSelection
255 * @private
273b2556 256 * @param {Object} state State variables for this instance of autocomplete.
e994dea0 257 * @return {Promise}
60a1ea56 258 */
273b2556 259 var activatePreviousSelection = function(state) {
60a1ea56 260 // Find the list of selections.
273b2556 261 var selectionsElement = $(document.getElementById(state.selectionId));
60a1ea56
DW
262 // Find the active one.
263 var element = selectionsElement.children('[data-active-selection=true]');
264 if (!element) {
e994dea0 265 return activateSelection(0, state);
60a1ea56
DW
266 }
267 // Find it's index.
268 var current = selectionsElement.children('[aria-selected=true]').index(element);
269 // Activate the next one.
e994dea0 270 return activateSelection(current - 1, state);
60a1ea56 271 };
e994dea0 272
60a1ea56
DW
273 /**
274 * Find the index of the current active selection, and activate the next one.
275 *
276 * @method activateNextSelection
277 * @private
273b2556 278 * @param {Object} state State variables for this instance of autocomplete.
e994dea0 279 * @return {Promise}
60a1ea56 280 */
273b2556 281 var activateNextSelection = function(state) {
60a1ea56 282 // Find the list of selections.
273b2556 283 var selectionsElement = $(document.getElementById(state.selectionId));
e994dea0 284
60a1ea56
DW
285 // Find the active one.
286 var element = selectionsElement.children('[data-active-selection=true]');
e994dea0
AN
287 var current = 0;
288
289 if (element) {
290 // The element was found. Determine the index and move to the next one.
291 current = selectionsElement.children('[aria-selected=true]').index(element);
292 current = current + 1;
293 } else {
294 // No selected item found. Move to the first.
295 current = 0;
60a1ea56 296 }
e994dea0
AN
297
298 return activateSelection(current, state);
60a1ea56
DW
299 };
300
301 /**
302 * Find the index of the current active suggestion, and activate the previous one.
303 *
304 * @method activatePreviousItem
305 * @private
273b2556 306 * @param {Object} state State variables for this autocomplete element.
e994dea0 307 * @return {Promise}
60a1ea56 308 */
273b2556 309 var activatePreviousItem = function(state) {
60a1ea56 310 // Find the list of suggestions.
273b2556 311 var suggestionsElement = $(document.getElementById(state.suggestionsId));
e994dea0 312
60a1ea56
DW
313 // Find the active one.
314 var element = suggestionsElement.children('[aria-selected=true]');
e994dea0 315
60a1ea56
DW
316 // Find it's index.
317 var current = suggestionsElement.children('[aria-hidden=false]').index(element);
e994dea0
AN
318
319 // Activate the previous one.
320 return activateItem(current - 1, state);
60a1ea56
DW
321 };
322
323 /**
324 * Close the list of suggestions.
325 *
326 * @method closeSuggestions
327 * @private
273b2556 328 * @param {Object} state State variables for this autocomplete element.
e994dea0 329 * @return {Promise}
60a1ea56 330 */
273b2556 331 var closeSuggestions = function(state) {
60a1ea56 332 // Find the elements in the DOM.
273b2556
DW
333 var inputElement = $(document.getElementById(state.inputId));
334 var suggestionsElement = $(document.getElementById(state.suggestionsId));
60a1ea56
DW
335
336 // Announce the list of suggestions was closed, and read the current list of selections.
273b2556 337 inputElement.attr('aria-expanded', false).attr('aria-activedescendant', state.selectionId);
e994dea0 338
60a1ea56
DW
339 // Hide the suggestions list (from screen readers too).
340 suggestionsElement.hide().attr('aria-hidden', true);
e994dea0
AN
341
342 return $.Deferred().resolve();
60a1ea56
DW
343 };
344
345 /**
346 * Rebuild the list of suggestions based on the current values in the select list, and the query.
347 *
348 * @method updateSuggestions
349 * @private
273b2556
DW
350 * @param {Object} options The original options for this autocomplete.
351 * @param {Object} state The state variables for this autocomplete.
352 * @param {String} query The current text for the search string.
60a1ea56 353 * @param {JQuery} originalSelect The JQuery object matching the hidden select list.
e994dea0 354 * @return {Promise}
60a1ea56 355 */
273b2556 356 var updateSuggestions = function(options, state, query, originalSelect) {
e994dea0
AN
357 var pendingKey = 'form-autocomplete-updateSuggestions-' + state.inputId;
358 M.util.js_pending(pendingKey);
359
60a1ea56 360 // Find the elements in the DOM.
273b2556
DW
361 var inputElement = $(document.getElementById(state.inputId));
362 var suggestionsElement = $(document.getElementById(state.suggestionsId));
60a1ea56
DW
363
364 // Used to track if we found any visible suggestions.
365 var matchingElements = false;
366 // Options is used by the context when rendering the suggestions from a template.
273b2556 367 var suggestions = [];
60a1ea56
DW
368 originalSelect.children('option').each(function(index, option) {
369 if ($(option).prop('selected') !== true) {
9f5f3dcc 370 suggestions[suggestions.length] = {label: option.innerHTML, value: $(option).attr('value')};
60a1ea56
DW
371 }
372 });
373
374 // Re-render the list of suggestions.
273b2556 375 var searchquery = state.caseSensitive ? query : query.toLocaleLowerCase();
9f5f3dcc 376 var context = $.extend({options: suggestions}, options, state);
e994dea0 377 var returnVal = templates.render(
60a1ea56 378 'core/form_autocomplete_suggestions',
273b2556 379 context
e994dea0
AN
380 )
381 .then(function(html, js) {
60a1ea56 382 // We have the new template, insert it in the page.
e994dea0
AN
383 templates.replaceNode(suggestionsElement, html, js);
384
60a1ea56 385 // Get the element again.
273b2556 386 suggestionsElement = $(document.getElementById(state.suggestionsId));
60a1ea56
DW
387 // Show it if it is hidden.
388 suggestionsElement.show().attr('aria-hidden', false);
389 // For each option in the list, hide it if it doesn't match the query.
390 suggestionsElement.children().each(function(index, node) {
391 node = $(node);
273b2556
DW
392 if ((options.caseSensitive && node.text().indexOf(searchquery) > -1) ||
393 (!options.caseSensitive && node.text().toLocaleLowerCase().indexOf(searchquery) > -1)) {
60a1ea56
DW
394 node.show().attr('aria-hidden', false);
395 matchingElements = true;
396 } else {
397 node.hide().attr('aria-hidden', true);
398 }
399 });
400 // If we found any matches, show the list.
81c471e2 401 inputElement.attr('aria-expanded', true);
9411beb3
DM
402 if (originalSelect.attr('data-notice')) {
403 // Display a notice rather than actual suggestions.
404 suggestionsElement.html(originalSelect.attr('data-notice'));
405 } else if (matchingElements) {
60a1ea56
DW
406 // We only activate the first item in the list if tags is false,
407 // because otherwise "Enter" would select the first item, instead of
408 // creating a new tag.
273b2556
DW
409 if (!options.tags) {
410 activateItem(0, state);
60a1ea56
DW
411 }
412 } else {
81c471e2
DW
413 // Nothing matches. Tell them that.
414 str.get_string('nosuggestions', 'form').done(function(nosuggestionsstr) {
415 suggestionsElement.html(nosuggestionsstr);
416 });
60a1ea56 417 }
60a1ea56 418
e994dea0
AN
419 return suggestionsElement;
420 })
421 .then(function() {
422 return M.util.js_complete(pendingKey);
423 })
424 .catch(notification.exception);
425
426 return returnVal;
60a1ea56
DW
427 };
428
429 /**
430 * Create a new item for the list (a tag).
431 *
432 * @method createItem
433 * @private
273b2556
DW
434 * @param {Object} options The original options for the autocomplete.
435 * @param {Object} state State variables for the autocomplete.
60a1ea56 436 * @param {JQuery} originalSelect The JQuery object matching the hidden select list.
e994dea0 437 * @return {Promise}
60a1ea56 438 */
273b2556 439 var createItem = function(options, state, originalSelect) {
60a1ea56 440 // Find the element in the DOM.
273b2556 441 var inputElement = $(document.getElementById(state.inputId));
60a1ea56
DW
442 // Get the current text in the input field.
443 var query = inputElement.val();
444 var tags = query.split(',');
445 var found = false;
446
447 $.each(tags, function(tagindex, tag) {
448 // If we can only select one at a time, deselect any current value.
449 tag = tag.trim();
450 if (tag !== '') {
273b2556 451 if (!options.multiple) {
60a1ea56
DW
452 originalSelect.children('option').prop('selected', false);
453 }
454 // Look for an existing option in the select list that matches this new tag.
455 originalSelect.children('option').each(function(index, ele) {
456 if ($(ele).attr('value') == tag) {
457 found = true;
458 $(ele).prop('selected', true);
459 }
460 });
461 // Only create the item if it's new.
462 if (!found) {
463 var option = $('<option>');
18e2f403 464 option.append(document.createTextNode(tag));
60a1ea56
DW
465 option.attr('value', tag);
466 originalSelect.append(option);
467 option.prop('selected', true);
bdd60287
DW
468 // We mark newly created custom options as we handle them differently if they are "deselected".
469 option.attr('data-iscustom', true);
60a1ea56
DW
470 }
471 }
472 });
bdd60287 473
e994dea0
AN
474 return updateSelectionList(options, state, originalSelect)
475 .then(function() {
476 // Notify that the selection changed.
477 notifyChange(originalSelect);
478
479 return;
480 })
481 .then(function() {
482 // Clear the input field.
483 inputElement.val('');
484
485 return;
486 })
487 .then(function() {
488 // Close the suggestions list.
489 return closeSuggestions(state);
490 });
60a1ea56
DW
491 };
492
60a1ea56
DW
493 /**
494 * Select the currently active item from the suggestions list.
495 *
496 * @method selectCurrentItem
497 * @private
273b2556
DW
498 * @param {Object} options The original options for the autocomplete.
499 * @param {Object} state State variables for the autocomplete.
60a1ea56 500 * @param {JQuery} originalSelect The JQuery object matching the hidden select list.
e994dea0 501 * @return {Promise}
60a1ea56 502 */
273b2556 503 var selectCurrentItem = function(options, state, originalSelect) {
60a1ea56 504 // Find the elements in the page.
273b2556
DW
505 var inputElement = $(document.getElementById(state.inputId));
506 var suggestionsElement = $(document.getElementById(state.suggestionsId));
60a1ea56
DW
507 // Here loop through suggestions and set val to join of all selected items.
508
509 var selectedItemValue = suggestionsElement.children('[aria-selected=true]').attr('data-value');
510 // The select will either be a single or multi select, so the following will either
511 // select one or more items correctly.
512 // Take care to use 'prop' and not 'attr' for selected properties.
513 // If only one can be selected at a time, start by deselecting everything.
273b2556 514 if (!options.multiple) {
60a1ea56
DW
515 originalSelect.children('option').prop('selected', false);
516 }
517 // Look for a match, and toggle the selected property if there is a match.
518 originalSelect.children('option').each(function(index, ele) {
519 if ($(ele).attr('value') == selectedItemValue) {
520 $(ele).prop('selected', true);
521 }
522 });
78162bf5 523
e994dea0
AN
524 return updateSelectionList(options, state, originalSelect)
525 .then(function() {
526 // Notify that the selection changed.
527 notifyChange(originalSelect);
786e014c 528
e994dea0
AN
529 return;
530 })
531 .then(function() {
532 if (options.closeSuggestionsOnSelect) {
533 // Clear the input element.
534 inputElement.val('');
535 // Close the list of suggestions.
536 return closeSuggestions(state);
537 } else {
538 // Focus on the input element so the suggestions does not auto-close.
539 inputElement.focus();
540 // Remove the last selected item from the suggestions list.
541 return updateSuggestions(options, state, inputElement.val(), originalSelect);
542 }
543 });
60a1ea56
DW
544 };
545
546 /**
547 * Fetch a new list of options via ajax.
548 *
549 * @method updateAjax
550 * @private
551 * @param {Event} e The event that triggered this update.
273b2556
DW
552 * @param {Object} options The original options for the autocomplete.
553 * @param {Object} state The state variables for the autocomplete.
60a1ea56 554 * @param {JQuery} originalSelect The JQuery object matching the hidden select list.
60a1ea56 555 * @param {Object} ajaxHandler This is a module that does the ajax fetch and translates the results.
e994dea0 556 * @return {Promise}
60a1ea56 557 */
273b2556 558 var updateAjax = function(e, options, state, originalSelect, ajaxHandler) {
e994dea0 559 var pendingPromise = addPendingJSPromise('updateAjax');
efef2efd
HN
560 // We need to show the indicator outside of the hidden select list.
561 // So we get the parent id of the hidden select list.
562 var parentElement = $(document.getElementById(state.selectId)).parent();
563 LoadingIcon.addIconToContainerRemoveOnCompletion(parentElement, pendingPromise);
e994dea0 564
60a1ea56
DW
565 // Get the query to pass to the ajax function.
566 var query = $(e.currentTarget).val();
567 // Call the transport function to do the ajax (name taken from Select2).
273b2556 568 ajaxHandler.transport(options.selector, query, function(results) {
60a1ea56 569 // We got a result - pass it through the translator before using it.
273b2556 570 var processedResults = ajaxHandler.processResults(options.selector, results);
60a1ea56
DW
571 var existingValues = [];
572
573 // Now destroy all options that are not currently selected.
574 originalSelect.children('option').each(function(optionIndex, option) {
575 option = $(option);
576 if (!option.prop('selected')) {
577 option.remove();
578 } else {
91ab264c 579 existingValues.push(String(option.attr('value')));
60a1ea56
DW
580 }
581 });
91ab264c
DW
582
583 if (!options.multiple && originalSelect.children('option').length === 0) {
584 // If this is a single select - and there are no current options
585 // the first option added will be selected by the browser. This causes a bug!
586 // We need to insert an empty option so that none of the real options are selected.
587 var option = $('<option>');
588 originalSelect.append(option);
589 }
9411beb3
DM
590 if ($.isArray(processedResults)) {
591 // Add all the new ones returned from ajax.
592 $.each(processedResults, function(resultIndex, result) {
593 if (existingValues.indexOf(String(result.value)) === -1) {
594 var option = $('<option>');
595 option.append(result.label);
596 option.attr('value', result.value);
597 originalSelect.append(option);
598 }
599 });
600 originalSelect.attr('data-notice', '');
601 } else {
602 // The AJAX handler returned a string instead of the array.
603 originalSelect.attr('data-notice', processedResults);
604 }
60a1ea56 605 // Update the list of suggestions now from the new values in the select list.
e994dea0 606 pendingPromise.resolve(updateSuggestions(options, state, '', originalSelect));
78162bf5 607 }, function(error) {
e994dea0 608 pendingPromise.reject(error);
78162bf5 609 });
e994dea0
AN
610
611 return pendingPromise;
60a1ea56
DW
612 };
613
614 /**
615 * Add all the event listeners required for keyboard nav, blur clicks etc.
616 *
617 * @method addNavigation
618 * @private
273b2556
DW
619 * @param {Object} options The options used to create this autocomplete element.
620 * @param {Object} state State variables for this autocomplete element.
60a1ea56 621 * @param {JQuery} originalSelect The JQuery object matching the hidden select list.
60a1ea56 622 */
273b2556 623 var addNavigation = function(options, state, originalSelect) {
60a1ea56 624 // Start with the input element.
273b2556 625 var inputElement = $(document.getElementById(state.inputId));
60a1ea56
DW
626 // Add keyboard nav with keydown.
627 inputElement.on('keydown', function(e) {
e994dea0 628 var pendingJsPromise = addPendingJSPromise('addNavigation-' + state.inputId + '-' + e.keyCode);
78162bf5 629
60a1ea56
DW
630 switch (e.keyCode) {
631 case KEYS.DOWN:
632 // If the suggestion list is open, move to the next item.
273b2556 633 if (!options.showSuggestions) {
97d2ea7f 634 // Do not consume this event.
e994dea0 635 pendingJsPromise.resolve();
97d2ea7f
DW
636 return true;
637 } else if (inputElement.attr('aria-expanded') === "true") {
e994dea0 638 pendingJsPromise.resolve(activateNextItem(state));
60a1ea56 639 } else {
d304952b 640 // Handle ajax population of suggestions.
273b2556
DW
641 if (!inputElement.val() && options.ajax) {
642 require([options.ajax], function(ajaxHandler) {
e994dea0 643 pendingJsPromise.resolve(updateAjax(e, options, state, originalSelect, ajaxHandler));
d304952b
AG
644 });
645 } else {
47dd5350 646 // Open the suggestions list.
e994dea0 647 pendingJsPromise.resolve(updateSuggestions(options, state, inputElement.val(), originalSelect));
d304952b 648 }
60a1ea56
DW
649 }
650 // We handled this event, so prevent it.
651 e.preventDefault();
652 return false;
60a1ea56
DW
653 case KEYS.UP:
654 // Choose the previous active item.
e994dea0
AN
655 pendingJsPromise.resolve(activatePreviousItem(state));
656
60a1ea56
DW
657 // We handled this event, so prevent it.
658 e.preventDefault();
659 return false;
660 case KEYS.ENTER:
273b2556 661 var suggestionsElement = $(document.getElementById(state.suggestionsId));
60a1ea56
DW
662 if ((inputElement.attr('aria-expanded') === "true") &&
663 (suggestionsElement.children('[aria-selected=true]').length > 0)) {
664 // If the suggestion list has an active item, select it.
e994dea0 665 pendingJsPromise.resolve(selectCurrentItem(options, state, originalSelect));
273b2556 666 } else if (options.tags) {
60a1ea56 667 // If tags are enabled, create a tag.
e994dea0
AN
668 pendingJsPromise.resolve(createItem(options, state, originalSelect));
669 } else {
670 pendingJsPromise.resolve();
60a1ea56 671 }
e994dea0 672
60a1ea56
DW
673 // We handled this event, so prevent it.
674 e.preventDefault();
675 return false;
676 case KEYS.ESCAPE:
677 if (inputElement.attr('aria-expanded') === "true") {
678 // If the suggestion list is open, close it.
e994dea0
AN
679 pendingJsPromise.resolve(closeSuggestions(state));
680 } else {
681 pendingJsPromise.resolve();
60a1ea56
DW
682 }
683 // We handled this event, so prevent it.
684 e.preventDefault();
685 return false;
e375029e 686 }
e994dea0 687 pendingJsPromise.resolve();
e375029e
NK
688 return true;
689 });
690 // Support multi lingual COMMA keycode (44).
691 inputElement.on('keypress', function(e) {
e994dea0 692
e375029e
NK
693 if (e.keyCode === KEYS.COMMA) {
694 if (options.tags) {
695 // If we are allowing tags, comma should create a tag (or enter).
e994dea0
AN
696 addPendingJSPromise('keypress-' + e.keyCode)
697 .resolve(createItem(options, state, originalSelect));
e375029e
NK
698 }
699 // We handled this event, so prevent it.
700 e.preventDefault();
701 return false;
60a1ea56
DW
702 }
703 return true;
704 });
e1db2b41 705 inputElement.on('blur', function() {
e994dea0 706 var pendingPromise = addPendingJSPromise('form-autocomplete-blur');
e1db2b41
RW
707 window.setTimeout(function() {
708 // Get the current element with focus.
709 var focusElement = $(document.activeElement);
e994dea0 710
e1db2b41
RW
711 // Only close the menu if the input hasn't regained focus.
712 if (focusElement.attr('id') != inputElement.attr('id')) {
273b2556 713 if (options.tags) {
e994dea0
AN
714 pendingPromise.then(function() {
715 return createItem(options, state, originalSelect);
716 })
717 .catch();
527bde6e 718 }
e994dea0
AN
719 pendingPromise.then(function() {
720 return closeSuggestions(state);
721 })
722 .catch();
60a1ea56 723 }
e994dea0
AN
724
725 pendingPromise.resolve();
60a1ea56
DW
726 }, 500);
727 });
273b2556
DW
728 if (options.showSuggestions) {
729 var arrowElement = $(document.getElementById(state.downArrowId));
47dd5350 730 arrowElement.on('click', function(e) {
e994dea0
AN
731 var pendingPromise = addPendingJSPromise('form-autocomplete-show-suggestions');
732
97d2ea7f
DW
733 // Prevent the close timer, or we will open, then close the suggestions.
734 inputElement.focus();
e994dea0 735
47dd5350
DW
736 // Handle ajax population of suggestions.
737 if (!inputElement.val() && options.ajax) {
738 require([options.ajax], function(ajaxHandler) {
e994dea0 739 pendingPromise.resolve(updateAjax(e, options, state, originalSelect, ajaxHandler));
47dd5350
DW
740 });
741 } else {
742 // Else - open the suggestions list.
e994dea0 743 pendingPromise.resolve(updateSuggestions(options, state, inputElement.val(), originalSelect));
47dd5350 744 }
97d2ea7f
DW
745 });
746 }
60a1ea56 747
273b2556 748 var suggestionsElement = $(document.getElementById(state.suggestionsId));
5cfd7a72
MO
749 // Remove any click handler first.
750 suggestionsElement.parent().prop("onclick", null).off("click");
60a1ea56 751 suggestionsElement.parent().on('click', '[role=option]', function(e) {
e994dea0 752 var pendingPromise = addPendingJSPromise('form-autocomplete-parent');
60a1ea56
DW
753 // Handle clicks on suggestions.
754 var element = $(e.currentTarget).closest('[role=option]');
273b2556 755 var suggestionsElement = $(document.getElementById(state.suggestionsId));
60a1ea56
DW
756 // Find the index of the clicked on suggestion.
757 var current = suggestionsElement.children('[aria-hidden=false]').index(element);
e994dea0 758
60a1ea56 759 // Activate it.
e994dea0
AN
760 activateItem(current, state)
761 .then(function() {
762 // And select it.
763 return selectCurrentItem(options, state, originalSelect);
764 })
765 .then(function() {
766 return pendingPromise.resolve();
767 })
768 .catch();
60a1ea56 769 });
273b2556 770 var selectionElement = $(document.getElementById(state.selectionId));
60a1ea56 771 // Handle clicks on the selected items (will unselect an item).
adebc069 772 selectionElement.on('click', '[role=listitem]', function(e) {
e994dea0
AN
773 var pendingPromise = addPendingJSPromise('form-autocomplete-clicks');
774
563fe0a5 775 // Remove it from the selection.
e994dea0 776 pendingPromise.resolve(deselectItem(options, state, $(e.currentTarget), originalSelect));
60a1ea56
DW
777 });
778 // Keyboard navigation for the selection list.
adebc069 779 selectionElement.on('keydown', function(e) {
e994dea0 780 var pendingPromise = addPendingJSPromise('form-autocomplete-keydown-' + e.keyCode);
60a1ea56
DW
781 switch (e.keyCode) {
782 case KEYS.DOWN:
60a1ea56
DW
783 // We handled this event, so prevent it.
784 e.preventDefault();
e994dea0
AN
785
786 // Choose the next selection item.
787 pendingPromise.resolve(activateNextSelection(state));
60a1ea56
DW
788 return false;
789 case KEYS.UP:
60a1ea56
DW
790 // We handled this event, so prevent it.
791 e.preventDefault();
e994dea0
AN
792
793 // Choose the previous selection item.
794 pendingPromise.resolve(activatePreviousSelection(state));
60a1ea56
DW
795 return false;
796 case KEYS.SPACE:
797 case KEYS.ENTER:
563fe0a5 798 // Get the item that is currently selected.
273b2556 799 var selectedItem = $(document.getElementById(state.selectionId)).children('[data-active-selection=true]');
563fe0a5 800 if (selectedItem) {
563fe0a5 801 e.preventDefault();
e994dea0
AN
802
803 // Unselect this item.
804 pendingPromise.resolve(deselectItem(options, state, selectedItem, originalSelect));
563fe0a5 805 }
60a1ea56
DW
806 return false;
807 }
e994dea0
AN
808
809 // Not handled. Resolve the promise.
810 pendingPromise.resolve();
60a1ea56
DW
811 return true;
812 });
813 // Whenever the input field changes, update the suggestion list.
273b2556 814 if (options.showSuggestions) {
68a0485c
JP
815 // If this field uses ajax, set it up.
816 if (options.ajax) {
817 require([options.ajax], function(ajaxHandler) {
e994dea0
AN
818 // Creating throttled handlers free of race conditions, and accurate.
819 // This code keeps track of a throttleTimeout, which is periodically polled.
820 // Once the throttled function is executed, the fact that it is running is noted.
821 // If a subsequent request comes in whilst it is running, this request is re-applied.
68a0485c 822 var throttleTimeout = null;
e994dea0 823 var inProgress = false;
78162bf5 824 var pendingKey = 'autocomplete-throttledhandler';
68a0485c 825 var handler = function(e) {
e994dea0
AN
826 // Empty the current timeout.
827 throttleTimeout = null;
828
829 // Mark this request as in-progress.
830 inProgress = true;
831
832 // Process the request.
833 updateAjax(e, options, state, originalSelect, ajaxHandler)
834 .then(function() {
835 // Check if the throttleTimeout is still empty.
836 // There's a potential condition whereby the JS request takes long enough to complete that
837 // another task has been queued.
838 // In this case another task will be kicked off and we must wait for that before marking htis as
839 // complete.
840 if (null === throttleTimeout) {
841 // Mark this task as complete.
842 M.util.js_complete(pendingKey);
843 }
844 inProgress = false;
845
846 return arguments[0];
847 })
848 .catch(notification.exception);
68a0485c
JP
849 };
850
851 // For input events, we do not want to trigger many, many updates.
852 var throttledHandler = function(e) {
e994dea0
AN
853 window.clearTimeout(throttleTimeout);
854 if (inProgress) {
855 // A request is currently ongoing.
856 // Delay this request another 100ms.
857 throttleTimeout = window.setTimeout(throttledHandler.bind(this, e), 100);
858 return;
859 }
860
861 if (throttleTimeout === null) {
862 // There is currently no existing timeout handler, and it has not been recently cleared, so
863 // this is the start of a throttling check.
78162bf5 864 M.util.js_pending(pendingKey);
68a0485c 865 }
e994dea0
AN
866
867 // There is currently no existing timeout handler, and it has not been recently cleared, so this
868 // is the start of a throttling check.
869 // Queue a call to the handler.
68a0485c
JP
870 throttleTimeout = window.setTimeout(handler.bind(this, e), 300);
871 };
e994dea0 872
68a0485c
JP
873 // Trigger an ajax update after the text field value changes.
874 inputElement.on("input", throttledHandler);
875 });
876 } else {
877 inputElement.on('input', function(e) {
878 var query = $(e.currentTarget).val();
879 var last = $(e.currentTarget).data('last-value');
880 // IE11 fires many more input events than required - even when the value has not changed.
881 // We need to only do this for real value changed events or the suggestions will be
882 // unclickable on IE11 (because they will be rebuilt before the click event fires).
883 // Note - because of this we cannot close the list when the query is empty or it will break
884 // on IE11.
885 if (last !== query) {
886 updateSuggestions(options, state, query, originalSelect);
887 }
888 $(e.currentTarget).data('last-value', query);
889 });
890 }
97d2ea7f 891 }
60a1ea56
DW
892 };
893
e994dea0
AN
894 /**
895 * Create and return an unresolved Promise for some pending JS.
896 *
897 * @param {String} key The unique identifier for this promise
898 * @return {Promise}
899 */
900 var addPendingJSPromise = function(key) {
901 var pendingKey = 'form-autocomplete:' + key;
902
903 M.util.js_pending(pendingKey);
904
905 var pendingPromise = $.Deferred();
906
907 pendingPromise
908 .then(function() {
909 M.util.js_complete(pendingKey);
910
911 return arguments[0];
912 })
913 .catch(notification.exception);
914
915 return pendingPromise;
916 };
917
60a1ea56
DW
918 return /** @alias module:core/form-autocomplete */ {
919 // Public variables and functions.
920 /**
921 * Turn a boring select box into an auto-complete beast.
922 *
923 * @method enhance
c96f55e6 924 * @param {string} selector The selector that identifies the select box.
60a1ea56
DW
925 * @param {boolean} tags Whether to allow support for tags (can define new entries).
926 * @param {string} ajax Name of an AMD module to handle ajax requests. If specified, the AMD
927 * module must expose 2 functions "transport" and "processResults".
928 * These are modeled on Select2 see: https://select2.github.io/options.html#ajax
929 * @param {String} placeholder - The text to display before a selection is made.
ecbc2a2f 930 * @param {Boolean} caseSensitive - If search has to be made case sensitive.
c96f55e6 931 * @param {Boolean} showSuggestions - If suggestions should be shown
427e3cbc 932 * @param {String} noSelectionString - Text to display when there is no selection
198d7291 933 * @param {Boolean} closeSuggestionsOnSelect - Whether to close the suggestions immediately after making a selection.
13426bae 934 * @return {Promise}
60a1ea56 935 */
198d7291
JP
936 enhance: function(selector, tags, ajax, placeholder, caseSensitive, showSuggestions, noSelectionString,
937 closeSuggestionsOnSelect) {
60a1ea56 938 // Set some default values.
273b2556
DW
939 var options = {
940 selector: selector,
941 tags: false,
942 ajax: false,
943 placeholder: placeholder,
944 caseSensitive: false,
427e3cbc
EM
945 showSuggestions: true,
946 noSelectionString: noSelectionString
273b2556 947 };
78162bf5
AN
948 var pendingKey = 'autocomplete-setup-' + selector;
949 M.util.js_pending(pendingKey);
273b2556
DW
950 if (typeof tags !== "undefined") {
951 options.tags = tags;
60a1ea56 952 }
273b2556
DW
953 if (typeof ajax !== "undefined") {
954 options.ajax = ajax;
60a1ea56 955 }
273b2556
DW
956 if (typeof caseSensitive !== "undefined") {
957 options.caseSensitive = caseSensitive;
ecbc2a2f 958 }
273b2556
DW
959 if (typeof showSuggestions !== "undefined") {
960 options.showSuggestions = showSuggestions;
97d2ea7f 961 }
427e3cbc 962 if (typeof noSelectionString === "undefined") {
35be5826 963 str.get_string('noselection', 'form').done(function(result) {
1388b618
JP
964 options.noSelectionString = result;
965 }).fail(notification.exception);
427e3cbc 966 }
60a1ea56
DW
967
968 // Look for the select element.
969 var originalSelect = $(selector);
970 if (!originalSelect) {
971 log.debug('Selector not found: ' + selector);
78162bf5 972 M.util.js_complete(pendingKey);
f3ecea3a 973 return false;
60a1ea56
DW
974 }
975
d8e57f02
DW
976 originalSelect.css('visibility', 'hidden').attr('aria-hidden', true);
977
60a1ea56 978 // Hide the original select.
60a1ea56
DW
979
980 // Find or generate some ids.
273b2556
DW
981 var state = {
982 selectId: originalSelect.attr('id'),
b7df2485
DW
983 inputId: 'form_autocomplete_input-' + uniqueId,
984 suggestionsId: 'form_autocomplete_suggestions-' + uniqueId,
985 selectionId: 'form_autocomplete_selection-' + uniqueId,
986 downArrowId: 'form_autocomplete_downarrow-' + uniqueId
273b2556 987 };
b7df2485
DW
988
989 // Increment the unique counter so we don't get duplicates ever.
990 uniqueId++;
991
273b2556
DW
992 options.multiple = originalSelect.attr('multiple');
993
198d7291
JP
994 if (typeof closeSuggestionsOnSelect !== "undefined") {
995 options.closeSuggestionsOnSelect = closeSuggestionsOnSelect;
996 } else {
997 // If not specified, this will close suggestions by default for single-select elements only.
998 options.closeSuggestionsOnSelect = !options.multiple;
999 }
1000
273b2556 1001 var originalLabel = $('[for=' + state.selectId + ']');
60a1ea56 1002 // Create the new markup and insert it after the select.
273b2556 1003 var suggestions = [];
60a1ea56 1004 originalSelect.children('option').each(function(index, option) {
9f5f3dcc 1005 suggestions[index] = {label: option.innerHTML, value: $(option).attr('value')};
60a1ea56
DW
1006 });
1007
1008 // Render all the parts of our UI.
273b2556
DW
1009 var context = $.extend({}, options, state);
1010 context.options = suggestions;
1011 context.items = [];
1012
5cdf8d49
DM
1013 // Collect rendered inline JS to be executed once the HTML is shown.
1014 var collectedjs = '';
1015
1016 var renderInput = templates.render('core/form_autocomplete_input', context).then(function(html, js) {
1017 collectedjs += js;
1018 return html;
1019 });
1020
1021 var renderDatalist = templates.render('core/form_autocomplete_suggestions', context).then(function(html, js) {
1022 collectedjs += js;
1023 return html;
1024 });
1025
1026 var renderSelection = templates.render('core/form_autocomplete_selection', context).then(function(html, js) {
1027 collectedjs += js;
1028 return html;
1029 });
60a1ea56 1030
e994dea0
AN
1031 return $.when(renderInput, renderDatalist, renderSelection)
1032 .then(function(input, suggestions, selection) {
d8e57f02 1033 originalSelect.hide();
60a1ea56
DW
1034 originalSelect.after(suggestions);
1035 originalSelect.after(input);
1036 originalSelect.after(selection);
d8e57f02 1037
5cdf8d49
DM
1038 templates.runTemplateJS(collectedjs);
1039
60a1ea56 1040 // Update the form label to point to the text input.
273b2556 1041 originalLabel.attr('for', state.inputId);
60a1ea56 1042 // Add the event handlers.
273b2556
DW
1043 addNavigation(options, state, originalSelect);
1044
273b2556 1045 var suggestionsElement = $(document.getElementById(state.suggestionsId));
60a1ea56
DW
1046 // Hide the suggestions by default.
1047 suggestionsElement.hide().attr('aria-hidden', true);
1048
e994dea0
AN
1049 return;
1050 })
1051 .then(function() {
60a1ea56 1052 // Show the current values in the selection list.
e994dea0
AN
1053 return updateSelectionList(options, state, originalSelect);
1054 })
1055 .then(function() {
1056 return M.util.js_complete(pendingKey);
1057 })
1058 .catch(function(error) {
78162bf5
AN
1059 M.util.js_complete(pendingKey);
1060 notification.exception(error);
60a1ea56
DW
1061 });
1062 }
1063 };
1064});