Docs For Class user_selector

Class user_selector_base

Description

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.

abstract:

Located in /user/selector/lib.php (line 38)

Direct descendents

Class	Description
service_user_selector	Base class for user selectors.
role_assign_user_selector_base	Base class to avoid duplicating code.
admins_potential_selector	Base class for user selectors.
admins_existing_selector	Base class for user selectors.
mnetservice_enrol_existing_users_selector	Selector of our users enrolled into remote course via enrol_mnet plugin
mnetservice_enrol_potential_users_selector	Selector of our users who could be enrolled into a remote course via their enrol_mnet
forum_subscriber_selector_base	Abstract class used by forum subscriber selection controls
groups_user_selector_base	Base class to avoid duplicating code.
enrol_manual_potential_participant	Enrol candidates
enrol_manual_current_participant	Enroled users
cohort_candidate_selector	Cohort assignment candidates
cohort_existing_selector	Cohort assignment candidates

Variable Summary

static array $jsmodule

boolean $autoselectunique

array $exclude

array $extrafields

boolean $multiselect

string $name

boolean $preserveselected

int $rows

boolean $searchanywhere

array|null $selected

mixed $validatinguserids

Method Summary

user_selector_base __construct (string $name, [array $options = array()])

void clear_exclusions ()

mixed display ([boolean $return = false])

void exclude (array $arrayofuserids)

array find_users (string $search)

array get_exclusions ()

string get_name ()

array get_options ()

integer get_rows ()

object the get_selected_user ()

array get_selected_users ()

any initialise_javascript ( $search, boolean $optiontracker)

void invalidate_selected_users ()

boolean is_multiselect ()

boolean is_validating ()

array load_selected_users ()

string output_optgroup (string $groupname, array $users, boolean $select)

string output_options (array $groupedusers, $search)

string output_user (object $user)

string required_fields_sql (string $u)

string search_button_caption ()

array search_sql (string $search, string $u)

void set_extra_fields (array $fields)

void set_multiselect (boolean $multiselect)

void set_rows (integer $numrows)

array too_many_results (string $search, int $count)

Variables

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

var: JavaScript YUI3 Module definition
access: protected

boolean $autoselectunique = false (line 55)

var: If only one user matches the search, should we select them automatically.
access: protected

array $exclude = array() (line 48)

var: A list of userids that should not be returned by this control.
access: protected

array $extrafields (line 42)

var: Extra fields to search on and return in addition to firstname and lastname.
access: protected

boolean $multiselect = true (line 44)

var: Whether the conrol should allow selection of many users, or just one.
access: protected

string $name (line 40)

var: The control name (and id) in the HTML.
access: protected

boolean $preserveselected = false (line 53)

var: When the search changes, do we keep previously selected options that do not match the new search term?
access: protected

int $rows = USER_SELECTOR_DEFAULT_ROWS (line 46)

var: The height this control should have, in rows.
access: protected

boolean $searchanywhere = false (line 58)

var: When searching, do we only match the starts of fields (better performance) or do we match occurrences anywhere?
access: protected

array|null $selected = null (line 50)

var: A list of the users who are selected.
access: protected

mixed $validatinguserids = null (line 60)

var: This is used by get selected users
access: protected

Methods

Constructor __construct (line 87)

Constructor. Each subclass must have a constructor with this signature.

access: public

user_selector_base __construct (string $name, [array $options = array()])

string $name: the control name/id for use in the HTML.
array $options: other options needed to construct this selector. You must be able to clone a userselector by doing new get_class($us)($us->get_name(), $us->get_options());

Redefined in descendants as:

clear_exclusions (line 126)

Clear the list of excluded user ids.

access: public

void clear_exclusions ()

display (line 183)

Output this user_selector as HTML.

return: if $return is true, returns the HTML as a string, otherwise returns nothing.
access: public

mixed display ([boolean $return = false])

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

exclude (line 119)

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.

access: public

void exclude (array $arrayofuserids)

array $arrayofuserids: the user ids to exclude.

find_users (line 320)

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.

return: 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.
abstract:
access: public

array find_users (string $search)

string $search: the search string.

Redefined in descendants as:

service_user_selector::find_users()
potential_assignees_below_course::find_users()
potential_assignees_course_and_above::find_users()
existing_role_holders::find_users()
admins_potential_selector::find_users()
admins_existing_selector::find_users()
mnetservice_enrol_existing_users_selector::find_users() : Find our users currently enrolled into the remote course
mnetservice_enrol_potential_users_selector::find_users() : Find our users who could be enrolled into the remote course
forum_potential_subscriber_selector::find_users() : Finds all potential users
forum_existing_subscriber_selector::find_users() : Finds all subscribed users
group_members_selector::find_users()
group_non_members_selector::find_users()
enrol_manual_potential_participant::find_users() : Candidate users
enrol_manual_current_participant::find_users() : Candidate users
cohort_candidate_selector::find_users() : Candidate users
cohort_existing_selector::find_users() : Candidate users

get_exclusions (line 133)

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

array get_exclusions ()

get_name (line 277)

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

string get_name ()

get_options (line 328)

Note: this function must be implemented if you use the search ajax field

(e.g. set $options['file'] = '/admin/filecontainingyourclass.php';)

return: the options needed to recreate this user_selector.
access: protected

array get_options ()

Redefined in descendants as:

service_user_selector::get_options()
role_assign_user_selector_base::get_options()
admins_potential_selector::get_options()
admins_existing_selector::get_options()
mnetservice_enrol_existing_users_selector::get_options()
mnetservice_enrol_potential_users_selector::get_options()
forum_subscriber_selector_base::get_options() : Returns an array of options to seralise and store for searches
forum_potential_subscriber_selector::get_options() : Returns an arary of options for this control
groups_user_selector_base::get_options()
enrol_manual_potential_participant::get_options()
enrol_manual_current_participant::get_options()
cohort_candidate_selector::get_options()
cohort_existing_selector::get_options()

get_rows (line 254)

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

integer get_rows ()

get_selected_user (line 154)

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

return: selected user object, or null if none.
access: public

object the get_selected_user ()

get_selected_users (line 142)

return: of user objects. The users that were selected. This is a more sophisticated version of optional_param($this->name, array(), PARAM_INTEGER) that validates the returned list of ids against the rules for this user selector.
access: public

array get_selected_users ()

initialise_javascript (line 633)

return: HTML needed here.
access: protected

any initialise_javascript ( $search, boolean $optiontracker)

boolean $optiontracker: if true, initialise JavaScript for updating the user prefs.
$search

invalidate_selected_users (line 174)

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.

access: public

void invalidate_selected_users ()

is_multiselect (line 270)

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

boolean is_multiselect ()

is_validating (line 344)

return: if true, we are validating a list of selected users, rather than preparing a list of uesrs to choose from.
access: protected

boolean is_validating ()

load_selected_users (line 354)

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

return: of user objects.
access: protected

array load_selected_users ()

output_optgroup (line 554)

Output one particular optgroup. Used by the preceding function output_options.

return: HTML code.
access: protected

string output_optgroup (string $groupname, array $users, boolean $select)

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.

output_options (line 506)

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.

return: HTML code.
access: protected

string output_options (array $groupedusers, $search)

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

output_user (line 582)

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

return: a string representation of the user.
access: public

string output_user (object $user)

object $user: the user to display.

Redefined in descendants as:

group_non_members_selector::output_user()

required_fields_sql (line 394)

return: fragment of SQL to go in the select list of the query.
access: protected

string required_fields_sql (string $u)

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

search_button_caption (line 595)

return: the caption for the search button.
access: protected

string search_button_caption ()

search_sql (line 416)

return: 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.
access: protected

array search_sql (string $search, string $u)

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

set_extra_fields (line 287)

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

access: public

void set_extra_fields (array $fields)

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

set_multiselect (line 263)

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

access: public

void set_multiselect (boolean $multiselect)

boolean $multiselect: true = allow multiple selection.

set_rows (line 247)

The height this control will be displayed, in rows.

access: public

void set_rows (integer $numrows)

integer $numrows: the desired height.

too_many_results (line 485)

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.

return: in the right format to return from the find_users method.
access: protected

array too_many_results (string $search, int $count)

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

Documentation generated on Tue, 15 Nov 2011 00:19:32 +0800 by phpDocumentor 1.4.3