MDL-67748 user: Add new core_user/form_user_selector JS module

The module provides AJAX support for the autocomplete form element.

user/amd/src/form_user_selector.js

@@ -0,0 +1,87 @@
+// This file is part of Moodle - https://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Provides the required functionality for an autocomplete element to select a user.
+ *
+ * @module      core_user/form_user_selector
+ * @package     core_webservice
+ * @copyright   2020 David Mudrák <david@moodle.com>
+ * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+import Ajax from 'core/ajax';
+import {render as renderTemplate} from 'core/templates';
+import {get_string as getString} from 'core/str';
+
+/**
+ * Load the list of users matching the query and render the selector labels for them.
+ *
+ * @param {String} selector The selector of the auto complete element.
+ * @param {String} query The query string.
+ * @param {Function} callback A callback function receiving an array of results.
+ * @param {Function} failure A function to call in case of failure, receiving the error message.
+ */
+export async function transport(selector, query, callback, failure) {
+
+    const request = {
+        methodname: 'core_user_search_identity',
+        args: {
+            query: query
+        }
+    };
+
+    try {
+        const response = await Ajax.call([request])[0];
+
+        if (response.overflow) {
+            const msg = await getString('toomanyuserstoshow', 'core', '>' + response.maxusersperpage);
+            callback(msg);
+
+        } else {
+            let labels = [];
+            response.list.forEach(user => {
+                labels.push(renderTemplate('core_user/form_user_selector_suggestion', user));
+            });
+            labels = await Promise.all(labels);
+
+            response.list.forEach((user, index) => {
+                user.label = labels[index];
+            });
+
+            callback(response.list);
+        }
+
+    } catch (e) {
+        failure(e);
+    }
+}
+
+/**
+ * Process the results for auto complete elements.
+ *
+ * @param {String} selector The selector of the auto complete element.
+ * @param {Array} results An array or results returned by {@see transport()}.
+ * @return {Array} New array of the selector options.
+ */
+export function processResults(selector, results) {
+
+    if (!Array.isArray(results)) {
+        return results;
+
+    } else {
+        return results.map(result => ({value: result.id, label: result.label}));
+    }
+}

user/templates/form_user_selector_suggestion.mustache

@@ -0,0 +1,54 @@
+{{!
+    This file is part of Moodle - https://moodle.org/
+
+    Moodle is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    Moodle is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+}}
+{{!
+    @template core_user/form_user_selector_suggestion
+
+    Moodle template for the list of valid options in an user selector autocomplate form element.
+
+    Classes required for JS:
+    * none
+
+    Data attributes required for JS:
+    * none
+
+    Context variables required for this template:
+    * fullname - string Users full name
+    * extrafields - list
+
+    Example context (json):
+    {
+        "fullname": "Admin User",
+        "extrafields": [
+            {
+                "name": "email",
+                "value": "admin@example.com"
+            },
+            {
+                "name": "phone1",
+                "value": "0123456789"
+            }
+        ]
+    }
+}}
+<span>
+    <span data-field="fullname">{{fullname}}</span>
+    <small>
+        {{#extrafields}}
+        <span data-field="{{name}}">{{{value}}}</span>
+        {{/extrafields}}
+    </small>
+</span>

user/upgrade.txt

@@ -2,6 +2,8 @@ This files describes API changes for code that uses the user API.
 
 === 3.11 ===
 
+* Added new core_user/form_user_selector JS module that can be used as the 'ajax' handler for the autocomplete form
+  element implementing the user selector.
 * Added new external function core_user_external::search_identity(). The main purpose of this external function is to
   provide data for asynchronous user selectors and similar widgets. It allows to search users matching the given query
   in their name or other available identity fields.