Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

Code for ajax user selectors.

Copyright: 1999 onwards Martin Dougiamas http://dougiamas.com
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 990 lines (39 kb)
Included or required:0 times
Referenced: 9 times
Includes or requires: 0 files

Defines 4 classes

user_selector_base:: (27 methods):
  __construct()
  exclude()
  clear_exclusions()
  get_exclusions()
  get_selected_users()
  get_selected_user()
  invalidate_selected_users()
  display()
  set_rows()
  get_rows()
  set_multiselect()
  is_multiselect()
  get_name()
  set_extra_fields()
  get_options()
  is_validating()
  load_selected_users()
  required_fields_sql()
  search_sql()
  too_many_results()
  output_options()
  output_optgroup()
  output_user()
  search_button_caption()
  initialise_option()
  option_checkbox()
  initialise_javascript()

groups_user_selector_base:: (3 methods):
  __construct()
  get_options()
  convert_array_format()

group_members_selector:: (1 method):
  find_users()

group_non_members_selector:: (5 methods):
  output_user()
  get_js_module()
  print_user_summaries()
  get_user_summaries()
  find_users()


Class: user_selector_base  - X-Ref

Base class for user selectors.

In your theme, you must give each user-selector a defined width. If the
user selector has name="myid", then the div myid_wrapper must have a width
specified.

__construct($name, $options = array()   X-Ref
Constructor. Each subclass must have a constructor with this signature.

param: string $name the control name/id for use in the HTML.
param: array $options other options needed to construct this selector.

exclude($arrayofuserids)   X-Ref
All to the list of user ids that this control will not select.

For example, on the role assign page, we do not list the users who already have the role in question.

param: array $arrayofuserids the user ids to exclude.

clear_exclusions()   X-Ref
Clear the list of excluded user ids.


get_exclusions()   X-Ref
Returns the list of user ids that this control will not select.

return: array the list of user ids that this control will not select.

get_selected_users()   X-Ref
The users that were selected.

This is a more sophisticated version of optional_param($this->name, array(), PARAM_INT) that validates the
returned list of ids against the rules for this user selector.

return: array of user objects.

get_selected_user()   X-Ref
Convenience method for when multiselect is false (throws an exception if not).

return: object the selected user object, or null if none.

invalidate_selected_users()   X-Ref
Invalidates the list of selected users.

If you update the database in such a way that it is likely to change the
list of users that this component is allowed to select from, then you
must call this method. For example, on the role assign page, after you have
assigned some roles to some users, you should call this.

display($return = false)   X-Ref
Output this user_selector as HTML.

param: boolean $return if true, return the HTML as a string instead of outputting it.
return: mixed if $return is true, returns the HTML as a string, otherwise returns nothing.

set_rows($numrows)   X-Ref
The height this control will be displayed, in rows.

param: integer $numrows the desired height.

get_rows()   X-Ref
Returns the number of rows to display in this control.

return: integer the height this control will be displayed, in rows.

set_multiselect($multiselect)   X-Ref
Whether this control will allow selection of many, or just one user.

param: boolean $multiselect true = allow multiple selection.

is_multiselect()   X-Ref
Returns true is multiselect should be allowed.

return: boolean whether this control will allow selection of more than one user.

get_name()   X-Ref
Returns the id/name of this control.

return: string the id/name that this control will have in the HTML.

set_extra_fields($fields)   X-Ref
Set the user fields that are displayed in the selector in addition to the user's name.

param: array $fields a list of field names that exist in the user table.

get_options()   X-Ref
Note: this function must be implemented if you use the search ajax field
(e.g. set $options['file'] = '/admin/filecontainingyourclass.php';)

return: array the options needed to recreate this user_selector.

is_validating()   X-Ref
Returns true if this control is validating a list of users.

return: boolean if true, we are validating a list of selected users,

load_selected_users()   X-Ref
Get the list of users that were selected by doing optional_param then validating the result.

return: array of user objects.

required_fields_sql(string $u)   X-Ref
Returns SQL to select required fields.

param: string $u the table alias for the user table in the query being
return: string fragment of SQL to go in the select list of the query.

search_sql(string $search, string $u)   X-Ref
Returns an array with SQL to perform a search and the params that go into it.

param: string $search the text to search for.
param: string $u the table alias for the user table in the query being
return: array an array with two elements, a fragment of SQL to go in the

too_many_results($search, $count)   X-Ref
Used to generate a nice message when there are too many users to show.

The message includes the number of users that currently match, and the
text of the message depends on whether the search term is non-blank.

param: string $search the search term, as passed in to the find users method.
param: int $count the number of users that currently match.
return: array in the right format to return from the find_users method.

output_options($groupedusers, $search)   X-Ref
Output the list of <optgroup>s and <options>s that go inside the select.

This method should do the same as the JavaScript method
user_selector.prototype.handle_response.

param: array $groupedusers an array, as returned by find_users.
param: string $search
return: string HTML code.

output_optgroup($groupname, $users, $select)   X-Ref
Output one particular optgroup. Used by the preceding function output_options.

param: string $groupname the label for this optgroup.
param: array $users the users to put in this optgroup.
param: boolean $select if true, select the users in this group.
return: string HTML code.

output_user($user)   X-Ref
Convert a user object to a string suitable for displaying as an option in the list box.

param: object $user the user to display.
return: string a string representation of the user.

search_button_caption()   X-Ref
Returns the string to use for the search button caption.

return: string the caption for the search button.

initialise_option($name, $default)   X-Ref
Initialise one of the option checkboxes, either from  the request, or failing that from the
user_preferences table, or finally from the given default.

param: string $name
param: mixed $default
return: mixed|null|string

option_checkbox($name, $on, $label)   X-Ref
Output one of the options checkboxes.

param: string $name
param: string $on
param: string $label
return: string

initialise_javascript($search)   X-Ref
Initialises JS for this control.

param: string $search
return: string any HTML needed here.

Class: groups_user_selector_base  - X-Ref

Base class to avoid duplicating code.

__construct($name, $options)   X-Ref
Constructor.

param: string $name control name
param: array $options should have two elements with keys groupid and courseid.

get_options()   X-Ref
Returns options for this selector.

return: array

convert_array_format($roles, $search)   X-Ref
Creates an organised array from given data.

param: array $roles array in the format returned by groups_calculate_role_people.
param: string $search
return: array array in the format find_users is supposed to return.

Class: group_members_selector  - X-Ref

User selector subclass for the list of users who are in a certain group.

Used on the add group memebers page.

find_users($search)   X-Ref
Finds users to display in this control.

param: string $search
return: array

Class: group_non_members_selector  - X-Ref

User selector subclass for the list of users who are not in a certain group.

Used on the add group members page.

output_user($user)   X-Ref
Output user.

param: stdClass $user
return: string

get_js_module()   X-Ref
Returns the user selector JavaScript module

return: array

print_user_summaries($courseid)   X-Ref
Creates a global JS variable (userSummaries) that is used by the group selector
to print related information when the user clicks on a user in the groups UI.

Used by /group/clientlib.js

param: int $courseid

get_user_summaries($courseid)   X-Ref
Construct HTML lists of group-memberships of the current set of users.

Used in user/selector/search.php to repopulate the userSummaries JS global
that is created in self::print_user_summaries() above.

param: int $courseid The course
return: string[] Array of HTML lists of groups.

find_users($search)   X-Ref
Finds users to display in this control.

param: string $search
return: array