Base class to avoid duplicating code. More...

Inheritance diagram for groups_user_selector_base:

Public Member Functions
	__construct ($name, $options)
	Constructor. More...

	clear_exclusions ()
	Clear the list of excluded user ids.

	display ($return=false)
	Output this user_selector as HTML. More...

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

	find_users ($search)
	Search the database for users matching the $search string, and any other conditions that apply. More...

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

	get_name ()
	Returns the id/name of this control. More...

	get_rows ()
	Returns the number of rows to display in this control. More...

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

	get_selected_users ()
	The users that were selected. More...

	invalidate_selected_users ()
	Invalidates the list of selected users. More...

	is_multiselect ()
	Returns true is multiselect should be allowed. More...

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

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

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

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

Public Attributes
int	$maxusersperpage = 100
	this is used to define maximum number of users visible in list

boolean	$viewfullnames = false
	Whether to override fullname()

Protected Member Functions
	convert_array_format ($roles, $search)
	Creates an organised array from given data. More...

	get_options ()
	Returns options for this selector. More...

	initialise_javascript ($search)
	Initialises JS for this control. More...

	is_validating ()
	Returns true if this control is validating a list of users. More...

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

	output_optgroup ($groupname, $users, $select)
	Output one particular optgroup. More...

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

	required_fields_sql ($u)
	Returns SQL to select required fields. More...

	search_button_caption ()
	Returns the string to use for the search button caption. More...

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

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

Protected Attributes
object	$accesscontext
	Context used for capability checks regarding this selector (does not necessarily restrict user list)

boolean	$autoselectunique = false
	If only one user matches the search, should we select them automatically.

int	$courseid

array	$exclude = array()
	A list of userids that should not be returned by this control.

array	$extrafields
	Extra fields to search on and return in addition to firstname and lastname.

int	$groupid

boolean	$multiselect = true
	Whether the conrol should allow selection of many users, or just one.

string	$name
	The control name (and id) in the HTML.

boolean	$preserveselected = false
	When the search changes, do we keep previously selected options that do not match the new search term?

int	$rows = USER_SELECTOR_DEFAULT_ROWS
	The height this control should have, in rows.

boolean	$searchanywhere = false
	When searching, do we only match the starts of fields (better performance) or do we match occurrences anywhere?

array null	$selected = null
	A list of the users who are selected.

mixed	$validatinguserids = null
	This is used by get selected users.

Static Protected Attributes
static array	$jsmodule
	JavaScript YUI3 Module definition. More...

Detailed Description

Base class to avoid duplicating code.

Copyright: 1999 onwards Martin Dougiamas http://dougiamas.com

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

groups_user_selector_base::__construct	(	$name,
		$options
	)

Constructor.

Parameters

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

Reimplemented from user_selector_base.

Member Function Documentation

◆ convert_array_format()

groups_user_selector_base::convert_array_format	(	$roles,
		$search
	)

protected

Creates an organised array from given data.

Parameters

array	$roles	array in the format returned by groups_calculate_role_people.
string	$search

Return values

array array in the format find_users is supposed to return.

◆ display()

user_selector_base::display ( $return = false )

inherited

Output this user_selector as HTML.

Parameters

boolean $return if true, return the HTML as a string instead of outputting it.

Return values

mixed if $return is true, returns the HTML as a string, otherwise returns nothing.

◆ exclude()

user_selector_base::exclude ( $arrayofuserids )

inherited

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.

Parameters

array $arrayofuserids the user ids to exclude.

◆ find_users()

user_selector_base::find_users ( $search )

abstractinherited

Search the database for users matching the $search string, and any other conditions that apply.

The SQL for testing whether a user matches the search string should be obtained by calling the search_sql method.

This method is used both when getting the list of choices to display to the user, and also when validating a list of users that was selected.

When preparing a list of users to choose from ($this->is_validating() return false) you should probably have an maximum number of users you will return, and if more users than this match your search, you should instead return a message generated by the too_many_results() method. However, you should not do this when validating.

If you are writing a new user_selector subclass, I strongly recommend you look at some of the subclasses later in this file and in admin/roles/lib.php. They should help you see exactly what you have to do.

Parameters

string $search the search string.

Return values

array An array of arrays of users. The array keys of the outer array should be the string names of optgroups. The keys of the inner arrays should be userids, and the values should be user objects containing at least the list of fields returned by the method required_fields_sql(). If a user object has a ->disabled property that is true, then that option will be displayed greyed out, and will not be returned by get_selected_users.

Reimplemented in core_role_admins_existing_selector, core_role_admins_potential_selector, core_role_check_users_selector, core_role_existing_role_holders, core_role_potential_assignees_below_course, core_role_potential_assignees_course_and_above, service_user_selector, badge_potential_users_selector, badge_existing_users_selector, cohort_candidate_selector, cohort_existing_selector, enrol_manual_potential_participant, enrol_manual_current_participant, mnetservice_enrol_existing_users_selector, mnetservice_enrol_potential_users_selector, mod_forum_existing_subscriber_selector, mod_forum_potential_subscriber_selector, group_members_selector, and group_non_members_selector.

◆ get_exclusions()

user_selector_base::get_exclusions ( )

inherited

Returns the list of user ids that this control will not select.

Return values

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

◆ get_name()

user_selector_base::get_name ( )

inherited

Returns the id/name of this control.

Return values

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

◆ get_options()

groups_user_selector_base::get_options ( )

protected

Returns options for this selector.

Return values

array

Reimplemented from user_selector_base.

◆ get_rows()

user_selector_base::get_rows ( )

inherited

Returns the number of rows to display in this control.

Return values

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

◆ get_selected_user()

user_selector_base::get_selected_user ( )

inherited

Convenience method for when multiselect is false (throws an exception if not).

Exceptions

moodle_exception

Return values

object the selected user object, or null if none.

◆ get_selected_users()

user_selector_base::get_selected_users ( )

inherited

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 values

array of user objects.

◆ initialise_javascript()

user_selector_base::initialise_javascript ( $search )

protectedinherited

Initialises JS for this control.

Parameters

string $search

Return values

string any HTML needed here.

◆ invalidate_selected_users()

user_selector_base::invalidate_selected_users ( )

inherited

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.

◆ is_multiselect()

user_selector_base::is_multiselect ( )

inherited

Returns true is multiselect should be allowed.

Return values

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

◆ is_validating()

user_selector_base::is_validating ( )

protectedinherited

Returns true if this control is validating a list of users.

Return values

boolean if true, we are validating a list of selected users, rather than preparing a list of uesrs to choose from.

◆ load_selected_users()

user_selector_base::load_selected_users ( )

protectedinherited

Get the list of users that were selected by doing optional_param then validating the result.

Return values

array of user objects.

◆ output_optgroup()

user_selector_base::output_optgroup	(	$groupname,
		$users,
		$select
	)

protectedinherited

Output one particular optgroup.

Used by the preceding function output_options.

Parameters

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

Return values

string HTML code.

◆ output_options()

user_selector_base::output_options	(	$groupedusers,
		$search
	)

protectedinherited

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.

Parameters

array	$groupedusers	an array, as returned by find_users.
string	$search

Return values

string HTML code.

◆ output_user()

user_selector_base::output_user ( $user )

inherited

Convert a user object to a string suitable for displaying as an option in the list box.

Parameters

object $user the user to display.

Return values

string a string representation of the user.

Reimplemented in group_non_members_selector.

◆ required_fields_sql()

user_selector_base::required_fields_sql ( $u )

protectedinherited

Returns SQL to select required fields.

Parameters

string $u the table alias for the user table in the query being built. May be ''.

Return values

string fragment of SQL to go in the select list of the query.

◆ search_button_caption()

user_selector_base::search_button_caption ( )

protectedinherited

Returns the string to use for the search button caption.

Return values

string the caption for the search button.

◆ search_sql()

user_selector_base::search_sql	(	$search,
		$u
	)

protectedinherited

Returns an array with SQL to perform a search and the params that go into it.

Parameters

string	$search	the text to search for.
string	$u	the table alias for the user table in the query being built. May be ''.

Return values

array an array with two elements, a fragment of SQL to go in the where clause the query, and an array containing any required parameters. this uses ? style placeholders.

◆ set_extra_fields()

user_selector_base::set_extra_fields ( $fields )

inherited

Set the user fields that are displayed in the selector in addition to the user's name.

Parameters

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

◆ set_multiselect()

user_selector_base::set_multiselect ( $multiselect )

inherited

Whether this control will allow selection of many, or just one user.

Parameters

boolean $multiselect true = allow multiple selection.

◆ set_rows()

user_selector_base::set_rows ( $numrows )

inherited

The height this control will be displayed, in rows.

Parameters

integer $numrows the desired height.

◆ too_many_results()

user_selector_base::too_many_results	(	$search,
		$count
	)

protectedinherited

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.

Parameters

string	$search	the search term, as passed in to the find users method.
int	$count	the number of users that currently match.

Return values

array in the right format to return from the find_users method.

Member Data Documentation

◆ $jsmodule

array user_selector_base::$jsmodule

staticprotectedinherited

Initial value:

= array(
                'name' => 'user_selector',
                'fullpath' => '/user/selector/module.js',
                'requires'  => array('node', 'event-custom', 'datasource', 'json', 'moodle-core-notification'),
                'strings' => array(
                    array('previouslyselectedusers', 'moodle', '%%SEARCHTERM%%'),
                    array('nomatchingusers', 'moodle', '%%SEARCHTERM%%'),
                    array('none', 'moodle')
                ))

JavaScript YUI3 Module definition.

The documentation for this class was generated from the following file:

user/selector/lib.php

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ convert_array_format()

◆ display()

◆ exclude()

◆ find_users()

◆ get_exclusions()

◆ get_name()

◆ get_options()

◆ get_rows()

◆ get_selected_user()

◆ get_selected_users()

◆ initialise_javascript()

◆ invalidate_selected_users()

◆ is_multiselect()

◆ is_validating()

◆ load_selected_users()

◆ output_optgroup()

◆ output_options()

◆ output_user()

◆ required_fields_sql()

◆ search_button_caption()

◆ search_sql()

◆ set_extra_fields()

◆ set_multiselect()

◆ set_rows()

◆ too_many_results()

Member Data Documentation

◆ $jsmodule