Moodle APIs 4.3
Moodle 4.3.6 (Build: 20240812)
|
Base class for a single availability condition. More...
Public Member Functions | |
__toString () | |
Display a representation of this condition (used for debugging). | |
check_available ($not, info $info, $grabthelot, $userid) | |
check_available ($not, core_availability\info $info, $grabthelot, $userid) | |
Determines whether this particular item is currently available according to the availability criteria. | |
description_callback (array $params) | |
Returns a marker indicating that some of the description text should be computed at display time. | |
filter_user_list (array $users, $not, core_availability\info $info, capability_checker $checker) | |
Tests this condition against a user list. | |
get_description ($full, $not, info $info) | |
Obtains a string describing this restriction (whether or not it actually applies). | |
get_standalone_description ($full, $not, info $info) | |
Obtains a string describing this restriction, used when there is only a single restriction to display. | |
get_user_list_sql ($not, core_availability\info $info, $onlyactive) | |
Obtains SQL that returns a list of enrolled users that has been filtered by the conditions applied in the availability API, similar to calling get_enrolled_users and then filter_user_list. | |
include_after_restore ($restoreid, $courseid, base_logger $logger, $name, base_task $task) | |
Checks whether this node should be included after restore or not. | |
is_applied_to_user_lists () | |
Checks whether this condition applies to user lists. | |
is_available ($not, info $info, $grabthelot, $userid) | |
Determines whether a particular item is currently available according to this availability condition. | |
is_available_for_all ($not=false) | |
Checks whether this condition is actually going to be available for all users under normal circumstances. | |
save () | |
Saves tree data back to a structure object. | |
update_after_restore ($restoreid, $courseid, base_logger $logger, $name) | |
Updates this node after restore, returning true if anything changed. | |
update_dependency_id ($table, $oldid, $newid) | |
Updates this node if it contains any references (dependencies) to the given table and id. | |
Static Public Member Functions | |
static | completion_value_used ($course, $cmid) |
If the plugin has been configured to rely on a particular activity's completion value, it should return true here. | |
static | description_cm_name (int $cmid) |
Returns a marker indicating that an activity name should be placed in a description. | |
static | description_format_string (string $str) |
Returns a marker indicating that formatted text should be placed in a description. | |
Protected Member Functions | |
get_debug_string () | |
Obtains a representation of the options of this condition as a string, for debugging. | |
get_type () | |
Gets the type name (e.g. | |
Static Protected Member Functions | |
static | unique_sql_parameter (array &$params, $value) |
Utility function for generating SQL parameters (because we can't use ? parameters because get_enrolled_sql has infected us with horrible named parameters). | |
Static Protected Attributes | |
static int | $uniquesqlparametercounter = 1 |
Counter to be used in tree_node::unique_sql_parameter(). | |
Base class for a single availability condition.
All condition types must extend this class.
The structure of a condition in JSON input data is:
{ type:'date', ... }
where 'date' is the name of the plugin (availability_date in this case) and ... is arbitrary extra data to be used by the plugin.
Conditions require a constructor with one parameter: $structure. This will contain all the JSON data for the condition. If the structure of the data is incorrect (e.g. missing fields) then the constructor may throw a coding_exception. However, the constructor should cope with all data that was previously valid (e.g. if the format changes, old data may still be present in a restore, so there should be a default value for any new fields and old ones should be handled correctly).
core_availability\condition::__toString | ( | ) |
Display a representation of this condition (used for debugging).
string | Text representation of condition |
|
abstractinherited |
Determines whether this particular item is currently available according to the availability criteria.
The $not option is potentially confusing. This option always indicates the 'real' value of NOT. For example, a condition inside a 'NOT AND' group will get this called with $not = true, but if you put another 'NOT OR' group inside the first group, then a condition inside that will be called with $not = false. We need to use the real values, rather than the more natural use of the current value at this point inside the tree, so that the information displayed to users makes sense.
bool | $not | Set true if we are inverting the condition |
core_availability\info | $info | Item we're checking |
bool | $grabthelot | Performance hint: if true, caches information required for all course-modules, to make the front page and similar pages work more quickly (works only for current user) |
int | $userid | User ID to check availability for |
result | Availability check result |
|
static |
If the plugin has been configured to rely on a particular activity's completion value, it should return true here.
(This is necessary so that we know the course page needs to update when that activity becomes complete.)
Default implementation returns false.
stdClass | $course | Moodle course object |
int | $cmid | ID of activity whose completion value is considered |
boolean | True if the availability of something else may rely on it |
Reimplemented in availability_completion\condition.
core_availability\condition::description_callback | ( | array | $params | ) |
Returns a marker indicating that some of the description text should be computed at display time.
This will result in a call to the get_description_callback_value static function within the condition class.
Gets placeholder text which will be decoded by info\format_info later when we can safely call most Moodle functions.
string[] | $params | Array of arbitrary parameters |
string | Placeholder text |
|
static |
Returns a marker indicating that an activity name should be placed in a description.
Gets placeholder text which will be decoded by info\format_info later when we can safely display names.
int | $cmid | Course-module id |
string | Placeholder text |
|
static |
Returns a marker indicating that formatted text should be placed in a description.
Gets placeholder text which will be decoded by info\format_info later when we can safely call format_string.
string | $str | Text to be processed with format_string |
string | Placeholder text |
|
inherited |
Tests this condition against a user list.
Users who do not meet the condition will be removed from the list, unless they have the ability to view hidden activities/sections.
This function must be implemented if is_applied_to_user_lists returns true. Otherwise it will not be called.
The function must operate efficiently, e.g. by using a fixed number of database queries regardless of how many users are in the list.
Within this function, if you need to check capabilities, please use the provided checker which caches results where possible.
Conditions do not need to check the viewhiddenactivities or viewhiddensections capabilities. These are handled by core_availability\info\filter_user_list.
array | $users | Array of userid => object |
bool | $not | True if this condition is applying in negative mode |
core_availability\info | $info | Item we're checking |
capability_checker | $checker |
array | Filtered version of input array |
coding_exception | If called on a condition that doesn't apply to user lists |
|
abstractprotected |
Obtains a representation of the options of this condition as a string, for debugging.
string | Text representation of parameters |
Reimplemented in availability_completion\condition, availability_date\condition, availability_grade\condition, availability_group\condition, availability_grouping\condition, and availability_profile\condition.
|
abstract |
Obtains a string describing this restriction (whether or not it actually applies).
Used to obtain information that is displayed to students if the activity is not available to them, and for staff to see what conditions are.
The $full parameter can be used to distinguish between 'staff' cases (when displaying all information about the activity) and 'student' cases (when displaying only conditions they don't meet).
If implementations require a course or modinfo, they should use the get methods in $info. They should not use any other functions that might rely on modinfo, such as format_string.
To work around this limitation, use the functions:
description_cm_name() description_format_string() description_callback()
These return special markers which will be added to the string and processed later after modinfo is complete.
bool | $full | Set true if this is the 'full information' view |
bool | $not | Set true if we are inverting the condition |
info | $info | Item we're checking |
string | Information string (for admin) about all restrictions on this item |
Reimplemented in availability_completion\condition, availability_date\condition, availability_grade\condition, availability_group\condition, availability_grouping\condition, and availability_profile\condition.
core_availability\condition::get_standalone_description | ( | $full, | |
$not, | |||
info | $info ) |
Obtains a string describing this restriction, used when there is only a single restriction to display.
(I.e. this provides a 'short form' rather than showing in a list.)
Default behaviour sticks the prefix text, normally displayed above the list, in front of the standard get_description call.
If implementations require a course or modinfo, they should use the get methods in $info. They should not use any other functions that might rely on modinfo, such as format_string.
To work around this limitation, use the functions:
description_cm_name() description_format_string() description_callback()
These return special markers which will be added to the string and processed later after modinfo is complete.
bool | $full | Set true if this is the 'full information' view |
bool | $not | Set true if we are inverting the condition |
info | $info | Item we're checking |
string | Information string (for admin) about all restrictions on this item |
Reimplemented in availability_date\condition.
|
protected |
Gets the type name (e.g.
'date' for availability_date) of plugin.
string | The type name for this plugin |
|
inherited |
Obtains SQL that returns a list of enrolled users that has been filtered by the conditions applied in the availability API, similar to calling get_enrolled_users and then filter_user_list.
As for filter_user_list, this ONLY filters out users with conditions that are marked as applying to user lists. For example, group conditions are included but date conditions are not included.
The returned SQL is a query that returns a list of user IDs. It does not include brackets, so you neeed to add these to make it into a subquery. You would normally use it in an SQL phrase like "WHERE u.id IN ($sql)".
The SQL will be complex and may be slow. It uses named parameters (sorry, I know they are annoying, but it was unavoidable here).
If there are no conditions, the returned result is array('', array()).
Conditions do not need to check the viewhiddenactivities or viewhiddensections capabilities. These are handled by core_availability\info\get_user_list_sql.
bool | $not | True if this condition is applying in negative mode |
core_availability\info | $info | Item we're checking |
bool | $onlyactive | If true, only returns active enrolments |
array | Array with two elements: SQL subquery and parameters array |
coding_exception | If called on a condition that doesn't apply to user lists |
|
inherited |
Checks whether this node should be included after restore or not.
The node may be removed depending on restore settings, which you can get from the $task object.
By default nodes are still included after restore.
string | $restoreid | Restore ID |
int | $courseid | ID of target course |
base_logger | $logger | Logger for any warnings |
string | $name | Name of this item (for use in warning messages) |
base_task | $task | Current restore task |
bool | True if there was any change |
Reimplemented in availability_group\condition, and availability_grouping\condition.
|
inherited |
Checks whether this condition applies to user lists.
The default is false (the condition is used to control access, but does not prevent the student from appearing in lists).
For example, group conditions apply to user lists: we do not want to include a student in a list of users if they are prohibited from accessing the activity because they don't belong to a relevant group. However, date conditions do not apply - we still want to show users in a list of people who might have submitted an assignment, even if they are no longer able to access the assignment in question because there is a date restriction.
The general idea is that conditions which are likely to be permanent (group membership, user profile) apply to user lists. Conditions which are likely to be temporary (date, grade requirement) do not.
Conditions which do apply to user lists must implement the filter_user_list function.
bool | True if this condition applies to user lists |
Reimplemented in availability_group\condition, availability_grouping\condition, availability_profile\condition, and core_availability\tree.
|
abstract |
Determines whether a particular item is currently available according to this availability condition.
If implementations require a course or modinfo, they should use the get methods in $info.
The $not option is potentially confusing. This option always indicates the 'real' value of NOT. For example, a condition inside a 'NOT AND' group will get this called with $not = true, but if you put another 'NOT OR' group inside the first group, then a condition inside that will be called with $not = false. We need to use the real values, rather than the more natural use of the current value at this point inside the tree, so that the information displayed to users makes sense.
bool | $not | Set true if we are inverting the condition |
info | $info | Item we're checking |
bool | $grabthelot | Performance hint: if true, caches information required for all course-modules, to make the front page and similar pages work more quickly (works only for current user) |
int | $userid | User ID to check availability for |
bool | True if available |
Reimplemented in availability_completion\condition, availability_date\condition, availability_grade\condition, availability_group\condition, availability_grouping\condition, and availability_profile\condition.
core_availability\condition::is_available_for_all | ( | $not = false | ) |
Checks whether this condition is actually going to be available for all users under normal circumstances.
Normally, if there are any conditions, then it may be hidden. However in the case of date conditions there are some conditions which will definitely not result in it being hidden for anyone.
bool | $not | Set true if we are inverting the condition |
bool | True if condition will return available for everyone |
Reimplemented from core_availability\tree_node.
Reimplemented in availability_date\condition.
|
abstractinherited |
Saves tree data back to a structure object.
stdClass | Structure object (ready to be made into JSON format) |
Reimplemented in availability_completion\condition, availability_date\condition, availability_grade\condition, availability_group\condition, availability_grouping\condition, availability_profile\condition, and core_availability\tree.
|
staticprotectedinherited |
Utility function for generating SQL parameters (because we can't use ? parameters because get_enrolled_sql has infected us with horrible named parameters).
array | $params | Params array (value will be added to this array) |
string | int | $value | Value |
SQL | code for the parameter, e.g. ':pr1234' |
|
inherited |
Updates this node after restore, returning true if anything changed.
The default behaviour is simply to return false. If there is a problem with the update, $logger can be used to output a warning.
Note: If you need information about the date offset, call core_availability\info\get_restore_date_offset($restoreid). For information on the restoring task and its settings, call core_availability\info\get_restore_task($restoreid).
string | $restoreid | Restore ID |
int | $courseid | ID of target course |
base_logger | $logger | Logger for any warnings |
string | $name | Name of this item (for use in warning messages) |
bool | True if there was any change |
Reimplemented in availability_completion\condition, availability_date\condition, availability_grade\condition, availability_group\condition, availability_grouping\condition, and core_availability\tree.
core_availability\condition::update_dependency_id | ( | $table, | |
$oldid, | |||
$newid ) |
Updates this node if it contains any references (dependencies) to the given table and id.
string | $table | Table name e.g. 'course_modules' |
int | $oldid | Previous ID |
int | $newid | New ID |
bool | True if it changed, otherwise false |
Reimplemented from core_availability\tree_node.
Reimplemented in availability_completion\condition, availability_grade\condition, availability_group\condition, and availability_grouping\condition.