MDL-60874 core_form: allow autocomplete AJAX handlers return a string

Custom AJAX handlers for the form autocomplete fields can now optionally
return string in their processResults() callback. If a string is
returned, it is displayed instead of the list of suggested items.

The string is displayed same way as we inform about no available
suggestions.

lib/amd/src/form-autocomplete.js

@@ -355,7 +355,10 @@ define(['jquery', 'core/log', 'core/str', 'core/templates', 'core/notification']
             });
             // If we found any matches, show the list.
             inputElement.attr('aria-expanded', true);
-            if (matchingElements) {
+            if (originalSelect.attr('data-notice')) {
+                // Display a notice rather than actual suggestions.
+                suggestionsElement.html(originalSelect.attr('data-notice'));
+            } else if (matchingElements) {
                 // We only activate the first item in the list if tags is false,
                 // because otherwise "Enter" would select the first item, instead of
                 // creating a new tag.
@@ -512,15 +515,21 @@ define(['jquery', 'core/log', 'core/str', 'core/templates', 'core/notification']
                 var option = $('<option>');
                 originalSelect.append(option);
             }
-            // And add all the new ones returned from ajax.
-            $.each(processedResults, function(resultIndex, result) {
-                if (existingValues.indexOf(String(result.value)) === -1) {
-                    var option = $('<option>');
-                    option.append(result.label);
-                    option.attr('value', result.value);
-                    originalSelect.append(option);
-                }
-            });
+            if ($.isArray(processedResults)) {
+                // Add all the new ones returned from ajax.
+                $.each(processedResults, function(resultIndex, result) {
+                    if (existingValues.indexOf(String(result.value)) === -1) {
+                        var option = $('<option>');
+                        option.append(result.label);
+                        option.attr('value', result.value);
+                        originalSelect.append(option);
+                    }
+                });
+                originalSelect.attr('data-notice', '');
+            } else {
+                // The AJAX handler returned a string instead of the array.
+                originalSelect.attr('data-notice', processedResults);
+            }
             // Update the list of suggestions now from the new values in the select list.
             updateSuggestions(options, state, '', originalSelect);
             M.util.js_complete(pendingKey);

lib/upgrade.txt

@@ -1,6 +1,12 @@
 This files describes API changes in core libraries and APIs,
 information provided here is intended especially for developers.
 
+=== 3.5.2 ===
+
+* Custom AJAX handlers for the form autocomplete fields can now optionally return string in their processResults()
+  callback. If a string is returned, it is displayed instead of the list if suggested items. This can be used, for
+  example, to inform the user that there are too many items matching the current search criteria.
+
 === 3.5 ===
 
 * There is a new privacy API that every subsystem and plugin has to implement so that the site can become GDPR