MDL-61028 core_search: Allow filtering search by user (front-end)

Creates a new 'Users' field in the search filters form. This field
requires new JavaScript and, to implement this, a new AJAX-callable
web service to search for users by name, with detailed restrictions
based on the current user's access to view profiles.

lang/en/search.php

@@ -26,6 +26,7 @@ $string['advancedsearch'] = 'Advanced search';
 $string['all'] = 'All';
 $string['allareas'] = 'All areas';
 $string['allcourses'] = 'All courses';
+$string['allusers'] = 'All users';
 $string['author'] = 'Author';
 $string['authorname'] = 'Author name';
 $string['back'] = 'Back';

lib/db/services.php

@@ -1178,6 +1178,13 @@ $functions = array(
         'type' => 'write',
         'capabilities' => 'moodle/role:assign'
     ),
+    'core_search_get_relevant_users' => array(
+        'classname' => '\core_search\external',
+        'methodname' => 'get_relevant_users',
+        'description' => 'Gets relevant users for a search request.',
+        'type' => 'read',
+        'ajax' => true
+    ),
     'core_tag_get_tagindex' => array(
         'classname' => 'core_tag_external',
         'methodname' => 'get_tagindex',

search/amd/build/form-search-user-selector.min.js

@@ -0,0 +1 @@
+define(["jquery","core/ajax","core/templates"],function(a,b,c){return{processResults:function(b,c){var d=[];return a.each(c,function(a,b){d.push({value:b.id,label:b._label})}),d},transport:function(d,e,f,g){var h,i={query:e},j=a(d).attr("withincourseid");"undefined"!=typeof j&&""!==a("#id_searchwithin").val()?i.courseid=j:i.courseid=0,h=b.call([{methodname:"core_search_get_relevant_users",args:i}]),h[0].then(function(b){var d=[];return a.each(b,function(a,b){d.push(c.render("core_search/form-user-selector-suggestion",b))}),a.when.apply(a.when,d).then(function(){var c=arguments,d=0;a.each(b,function(a,b){b._label=c[d++]}),f(b)})}).fail(g)}}});

search/amd/src/form-search-user-selector.js

@@ -0,0 +1,82 @@
+// This file is part of Moodle - http://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/>.
+
+/**
+ * Search user selector module.
+ *
+ * @module core_search/form-search-user-selector
+ * @class form-search-user-selector
+ * @package core_search
+ * @copyright 2017 The Open University
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+define(['jquery', 'core/ajax', 'core/templates'], function($, Ajax, Templates) {
+
+    return /** @alias module:core_search/form-search-user-selector */ {
+
+        processResults: function(selector, results) {
+            var users = [];
+            $.each(results, function(index, user) {
+                users.push({
+                    value: user.id,
+                    label: user._label
+                });
+            });
+            return users;
+        },
+
+        transport: function(selector, query, success, failure) {
+            var promise;
+
+            // Search within specific course if known and if the 'search within' dropdown is set
+            // to search within course or activity.
+            var args = {query: query};
+            var courseid = $(selector).attr('withincourseid');
+            if (typeof courseid !== "undefined" && $('#id_searchwithin').val() !== '') {
+                args.courseid = courseid;
+            } else {
+                args.courseid = 0;
+            }
+
+            // Call AJAX request.
+            promise = Ajax.call([{methodname: 'core_search_get_relevant_users', args: args}]);
+
+            // When AJAX request returns, handle the results.
+            promise[0].then(function(results) {
+                var promises = [];
+
+                // Render label with user name and picture.
+                $.each(results, function(index, user) {
+                    promises.push(Templates.render('core_search/form-user-selector-suggestion', user));
+                });
+
+                // Apply the label to the results.
+                return $.when.apply($.when, promises).then(function() {
+                    var args = arguments;
+                    var i = 0;
+                    $.each(results, function(index, user) {
+                        user._label = args[i++];
+                    });
+                    success(results);
+                    return;
+                });
+
+            }).fail(failure);
+        }
+
+    };
+
+});

search/classes/external.php

@@ -0,0 +1,119 @@
+<?php
+// This file is part of Moodle - http://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/>.
+
+/**
+ * Handles external (web service) function calls related to search.
+ *
+ * @package core_search
+ * @copyright 2017 The Open University
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core_search;
+
+use core_user\external\user_summary_exporter;
+use \external_value;
+use \external_single_structure;
+use \external_multiple_structure;
+
+defined('MOODLE_INTERNAL') || die();
+
+global $CFG;
+require_once($CFG->libdir . '/externallib.php');
+
+/**
+ * Handles external (web service) function calls related to search.
+ *
+ * @package core_search
+ * @copyright 2017 The Open University
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class external extends \external_api {
+    /**
+     * Returns parameter types for get_relevant_users function.
+     *
+     * @return \external_function_parameters Parameters
+     */
+    public static function get_relevant_users_parameters() {
+        return new \external_function_parameters([
+                'query' => new external_value(PARAM_RAW,
+                    'Query string (full or partial user full name or other details)'),
+                'courseid' => new external_value(PARAM_INT, 'Course id (0 if none)'),
+                ]);
+    }
+
+    /**
+     * Returns result type for get_relevant_users function.
+     *
+     * @return \external_description Result type
+     */
+    public static function get_relevant_users_returns() {
+        return new external_multiple_structure(
+                new external_single_structure([
+                    'id' => new external_value(PARAM_INT, 'User id'),
+                    'fullname' => new external_value(PARAM_RAW, 'Full name as text'),
+                    'profileimageurlsmall' => new external_value(PARAM_URL, 'URL to small profile image')
+                ]));
+    }
+
+    /**
+     * Searches for users given a query, taking into account the current user's permissions and
+     * possibly a course to check within.
+     *
+     * @param string $query Query text
+     * @param int $courseid Course id or 0 if no restriction
+     * @return array Defined return structure
+     */
+    public static function get_relevant_users($query, $courseid) {
+        global $CFG, $PAGE;
+
+        // Validate parameter.
+        self::validate_parameters(self::get_relevant_users_parameters(),
+                ['query' => $query, 'courseid' => $courseid]);
+
+        // Validate the context (search page is always system context).
+        $systemcontext = \context_system::instance();
+        self::validate_context($systemcontext);
+
+        // Get course object too.
+        if ($courseid) {
+            $coursecontext = \context_course::instance($courseid);
+        } else {
+            $coursecontext = null;
+        }
+
+        // If not logged in, can't see anyone when forceloginforprofiles is on.
+        if (!empty($CFG->forceloginforprofiles)) {
+            if (!isloggedin() || isguestuser()) {
+                return [];
+            }
+        }
+
+        $users = \core_user::search($query, $coursecontext);
+
+        $result = [];
+        foreach ($users as $user) {
+            // Get a standard exported user object.
+            $fulldetails = (new user_summary_exporter($user))->export($PAGE->get_renderer('core'));
+
+            // To avoid leaking private data to students, only include the specific information we
+            // are going to display (and not the email, idnumber, etc).
+            $result[] = (object)['id' => $fulldetails->id, 'fullname' => $fulldetails->fullname,
+                    'profileimageurlsmall' => $fulldetails->profileimageurlsmall];
+        }
+        return $result;
+    }
+}

search/classes/output/form/search.php

@@ -27,6 +27,7 @@ namespace core_search\output\form;
 defined('MOODLE_INTERNAL') || die;
 
 require_once($CFG->libdir . '/formslib.php');
+require_once($CFG->libdir . '/externallib.php');
 
 class search extends \moodleform {
 
@@ -36,7 +37,7 @@ class search extends \moodleform {
      * @return void
      */
     function definition() {
-        global $USER;
+        global $USER, $DB, $OUTPUT;
 
         $mform =& $this->_form;
         $mform->disable_form_change_checker();
@@ -95,6 +96,31 @@ class search extends \moodleform {
         $mform->addElement('course', 'courseids', get_string('courses', 'core'), $options);
         $mform->setType('courseids', PARAM_INT);
 
+        // If the search engine can search by user, and the user is logged in (so we have
+        // permission to call the user-listing web service) then show the user selector.
+        if ($search->get_engine()->supports_users() && isloggedin()) {
+            $options = [
+                'ajax' => 'core_search/form-search-user-selector',
+                'multiple' => true,
+                'noselectionstring' => get_string('allusers', 'search'),
+                'valuehtmlcallback' => function($value) {
+                    global $DB, $OUTPUT;
+                    $user = $DB->get_record('user', ['id' => (int)$value], '*', IGNORE_MISSING);
+                    if (!$user || !user_can_view_profile($user)) {
+                        return false;
+                    }
+                    $details = user_get_user_details($user);
+                    return $OUTPUT->render_from_template(
+                            'core_search/form-user-selector-suggestion', $details);
+                }
+            ];
+            if (!empty($this->_customdata['withincourseid'])) {
+                $options['withincourseid'] = $this->_customdata['withincourseid'];
+            }
+
+            $mform->addElement('autocomplete', 'userids', get_string('users'), [], $options);
+        }
+
         if (!empty($this->_customdata['searchwithin'])) {
             // Course options should be hidden if we choose to search within a specific location.
             $mform->hideIf('courseids', 'searchwithin', 'ne', '');

search/templates/form-user-selector-suggestion.mustache

@@ -0,0 +1,41 @@
+{{!
+    This file is part of Moodle - http://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_search/form-user-selector-suggestion
+
+    Moodle template for the list of valid options in an autocomplate form element.
+
+    Classes required for JS:
+    * none
+
+    Data attributes required for JS:
+    * none
+
+    Context variables required for this template:
+    * profileimageurlsmall Url to a small profile image.
+    * fullname Users full name
+
+    Example context (json):
+    { "id": "1",
+      "fullname": "Kermit Thefrog",
+      "profileimageurlsmall": "https://example.org/img"
+    }
+}}
+<span>
+    <img height="12" src="{{profileimageurlsmall}}" alt="" role="presentation">
+    <span>{{fullname}}</span>
+</span>

search/tests/behat/search_by_user.feature

@@ -0,0 +1,67 @@
+@core @core_search
+Feature: Select users when searching for user-created content
+  In order to search for content by specific users
+  As a user
+  I need to be able to add users to the select list in the search form
+
+  Background:
+    Given the following config values are set as admin:
+      | enableglobalsearch | 1    |
+      | searchengine       | solr |
+    And the following "courses" exist:
+      | shortname | fullname |
+      | C1        | Frogs    |
+      | C2        | Zombies  |
+    And the following "activities" exist:
+      | activity | name       | intro      | course | idnumber |
+      | page     | PageName1  | PageDesc1  | C1     | PAGE1    |
+    And the following "users" exist:
+      | username | firstname | lastname   |
+      | s1       | Anne      | Other      |
+      | s2       | Anne      | Additional |
+      | t        | Anne      | Ditin      |
+    And the following "course enrolments" exist:
+      | user | course | role    |
+      | s1   | C1     | student |
+      | s2   | C2     | student |
+      | t    | C1     | teacher |
+
+  @javascript
+  Scenario: As administrator, search for users from home page
+    Given I log in as "admin"
+    And global search expects the query "frogs" and will return:
+      | type     | idnumber |
+      | activity | PAGE1    |
+    And I search for "frogs" using the header global search box
+    And I expand all fieldsets
+    And I set the field with xpath "//select[@id='id_userids']/../input[@type='text']" to "Anne"
+    # Alphabetical surname order.
+    Then "Anne Additional" "text" should appear before "Anne Ditin" "text"
+    And "Anne Ditin" "text" should appear before "Anne Other" "text"
+
+  @javascript
+  Scenario: As administrator, search for users within course
+    Given I log in as "admin"
+    And I am on "Frogs" course homepage
+    And global search expects the query "frogs" and will return:
+      | type     | idnumber |
+      | activity | PAGE1    |
+    And I search for "frogs" using the header global search box
+    And I expand all fieldsets
+    And I select "Course: Frogs" from the "Search within" singleselect
+    And I set the field with xpath "//select[@id='id_userids']/../input[@type='text']" to "Anne"
+    # Users in selected course appear first.
+    And "Anne Additional" "text" should appear after "Anne Other" "text"
+
+  @javascript
+  Scenario: As student, cannot see users on other courses
+    Given I log in as "s1"
+    And I am on "Frogs" course homepage
+    And global search expects the query "frogs" and will return:
+      | type     | idnumber |
+      | activity | PAGE1    |
+    And I search for "frogs" using the header global search box
+    And I expand all fieldsets
+    And I set the field with xpath "//select[@id='id_userids']/../input[@type='text']" to "A"
+    Then "Anne Ditin" "text" should appear before "Anne Other" "text"
+    And "Anne Additional" "text" should not exist

search/tests/external_test.php

@@ -0,0 +1,72 @@
+<?php
+// This file is part of Moodle - http://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/>.
+
+/**
+ * External function unit tests.
+ *
+ * @package core_search
+ * @copyright 2017 The Open University
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core_search;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * External function unit tests.
+ *
+ * @package core_search
+ * @copyright 2017 The Open University
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class external_testcase extends \advanced_testcase {
+
+    public function setUp() {
+        $this->resetAfterTest();
+    }
+
+    /**
+     * Checks the get_relevant_users function used when selecting users in search filter.
+     */
+    public function test_get_relevant_users() {
+        // Set up two users to search for and one to do the searching.
+        $generator = $this->getDataGenerator();
+        $student1 = $generator->create_user(['firstname' => 'Amelia', 'lastname' => 'Aardvark']);
+        $student2 = $generator->create_user(['firstname' => 'Amelia', 'lastname' => 'Beetle']);
+        $student3 = $generator->create_user(['firstname' => 'Zebedee', 'lastname' => 'Boing']);
+        $course = $generator->create_course();
+        $generator->enrol_user($student1->id, $course->id, 'student');
+        $generator->enrol_user($student2->id, $course->id, 'student');
+        $generator->enrol_user($student3->id, $course->id, 'student');
+
+        // As student 3, search for the other two.
+        $this->setUser($student3);
+        $result = external::get_relevant_users('Amelia', 0);
+        $this->assertCount(2, $result);
+
+        // Check that the result contains all the expected fields.
+        $this->assertEquals($student1->id, $result[0]->id);
+        $this->assertEquals('Amelia Aardvark', $result[0]->fullname);
+        $this->assertContains('/u/f2', $result[0]->profileimageurlsmall);
+
+        // Check we aren't leaking information about user email address (for instance).
+        $this->assertObjectNotHasAttribute('email', $result[0]);
+
+        // Note: We are not checking search permissions, search by different fields, etc. as these
+        // are covered by the core_user::search unit test.
+    }
+}