availability_completion\condition Class Reference

Activity completion condition. More...

Inheritance diagram for availability_completion\condition:

Public Member Functions
	__construct ($structure)
	Constructor.
	__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_cmid (stdClass $course, ?int $selfcmid, ?int $selfsectionid)
	Get the cmid referenced in the access restriction.
	get_description ($full, $not, info $info)
	Obtains a string describing this restriction (whether or not it actually applies).
	get_selfids (info $info)
	Return current item IDs (cmid and sectionid).
	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)
	Used in course/lib.php because we need to disable the completion JS if a completion value affects a conditional activity.
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.
static	get_json (int $cmid, int $expectedcompletion)
	Returns a JSON object which corresponds to a condition of this type.
static	wipe_static_cache ()
	Wipes the static cache of modules used in a condition (for unit testing).

Public Attributes
int const	OPTION_PREVIOUS = -1
	previous module cm value used to calculate relative completions

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	get_lang_string_keyword (int $completionstate)
	Returns a more readable keyword corresponding to a completion state.
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).

Protected Attributes
int	$cmid
	ID of module that this depends on.
int	$expectedcompletion
	Expected completion type (one of the COMPLETE_xx constants)
array	$modfastprevious = []
	Array of previous cmids used to calculate relative completions.
array	$sectionfastprevious = []
	Array of cmids previous to each course section.
array	$selfids
	IDs of the current module and section.

Static Protected Attributes
static array	$modsusedincondition = []
	Array of modules used in these conditions for course.
static int	$uniquesqlparametercounter = 1
	Counter to be used in tree_node::unique_sql_parameter().

Detailed Description

Activity completion condition.

Copyright

2014 The Open University

License

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

Constructor & Destructor Documentation

__construct()

availability_completion\condition::__construct

(

$structure

)

Constructor.

Parameters

stdClass

$structure

Data structure from JSON decode

Exceptions

coding_exception

If invalid data structure.

Member Function Documentation

__toString()

core_availability\condition::__toString ( )

inherited

Display a representation of this condition (used for debugging).

Return values

string

Text representation of condition

check_available()

core_availability\tree_node::check_available ( $not, core_availability\info $info, $grabthelot, $userid )

abstractinherited

Determines whether this particular item is currently available according to the availability criteria.

• This does not include the 'visible' setting (i.e. this might return true even if visible is false); visible is handled independently.
• This does not take account of the viewhiddenactivities capability. That should apply later.

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.

Parameters

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

Return values

result

Availability check result

completion_value_used()

static availability_completion\condition::completion_value_used ( $course, $cmid )

static

Used in course/lib.php because we need to disable the completion JS if a completion value affects a conditional activity.

Parameters

stdClass	$course	Moodle course object
int	$cmid	Course-module id

Return values

bool	True if this is used in a condition, false otherwise

Reimplemented from core_availability\condition.

description_callback()

core_availability\condition::description_callback ( array $params )

inherited

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.

Parameters

string[]

$params

Array of arbitrary parameters

Return values

string

Placeholder text

Since

Moodle 4.0

description_cm_name()

static core_availability\condition::description_cm_name ( int $cmid )

staticinherited

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.

Parameters

int

$cmid

Course-module id

Return values

string

Placeholder text

Since

Moodle 4.0

description_format_string()

static core_availability\condition::description_format_string ( string $str )

staticinherited

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.

Parameters

string

$str

Text to be processed with format_string

Return values

string

Placeholder text

Since

Moodle 4.0

filter_user_list()

core_availability\tree_node::filter_user_list ( array $users, $not, core_availability\info $info, capability_checker $checker )

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.

Parameters

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

Return values

array

Filtered version of input array

Exceptions

coding_exception

If called on a condition that doesn't apply to user lists

get_cmid()

availability_completion\condition::get_cmid	(	stdClass	$course,
		?int	$selfcmid,
		?int	$selfsectionid )

Get the cmid referenced in the access restriction.

Parameters

stdClass	$course	course object
int | null	$selfcmid	current course-module ID or null
int | null	$selfsectionid	current course-section ID or null

Return values

int|null

cmid or null if no referenced cm is found

get_debug_string()

availability_completion\condition::get_debug_string ( )

protected

Obtains a representation of the options of this condition as a string, for debugging.

Return values

string

Text representation of parameters

Reimplemented from core_availability\condition.

get_description()

availability_completion\condition::get_description	(		$full,
			$not,
		info	$info )

Obtains a string describing this restriction (whether or not it actually applies).

Parameters

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

Return values

string

Information string (for admin) about all restrictions on this item

Reimplemented from core_availability\condition.

get_json()

static availability_completion\condition::get_json ( int $cmid, int $expectedcompletion )

static

Returns a JSON object which corresponds to a condition of this type.

Intended for unit testing, as normally the JSON values are constructed by JavaScript code.

Parameters

int	$cmid	Course-module id of other activity
int	$expectedcompletion	Expected completion value (COMPLETION_xx)

Return values

stdClass

Object representing condition

get_lang_string_keyword()

static availability_completion\condition::get_lang_string_keyword ( int $completionstate )

staticprotected

Returns a more readable keyword corresponding to a completion state.

Used to make lang strings easier to read.

Parameters

int

$completionstate

COMPLETION_xx constant

Return values

string

Readable keyword

get_selfids()

availability_completion\condition::get_selfids

(

info

$info

)

Return current item IDs (cmid and sectionid).

Parameters

info

$info

Return values

int[]

with [0] => cmid/null, [1] => sectionid/null

get_standalone_description()

core_availability\condition::get_standalone_description ( $full, $not, info $info )

inherited

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.

Parameters

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

Return values

string

Information string (for admin) about all restrictions on this item

Reimplemented in availability_date\condition.

get_type()

core_availability\condition::get_type ( )

protectedinherited

Gets the type name (e.g.

'date' for availability_date) of plugin.

Return values

string

The type name for this plugin

get_user_list_sql()

core_availability\tree_node::get_user_list_sql ( $not, core_availability\info $info, $onlyactive )

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.

Parameters

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

Return values

array

Array with two elements: SQL subquery and parameters array

Exceptions

coding_exception

If called on a condition that doesn't apply to user lists

include_after_restore()

core_availability\tree_node::include_after_restore ( $restoreid, $courseid, base_logger $logger, $name, base_task $task )

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.

Parameters

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

Return values

bool	True if there was any change

Reimplemented in availability_group\condition, and availability_grouping\condition.

is_applied_to_user_lists()

core_availability\tree_node::is_applied_to_user_lists ( )

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.

Return values

bool	True if this condition applies to user lists

Reimplemented in availability_group\condition, availability_grouping\condition, availability_profile\condition, and core_availability\tree.

is_available()

availability_completion\condition::is_available	(		$not,
		info	$info,
			$grabthelot,
			$userid )

Determines whether a particular item is currently available according to this availability condition.

See also

core_availability\tree_node\update_after_restore

Parameters

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

Return values

bool	True if available

Reimplemented from core_availability\condition.

is_available_for_all()

core_availability\condition::is_available_for_all ( $not = false )

inherited

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.

Parameters

bool

$not

Set true if we are inverting the condition

Return values

bool	True if condition will return available for everyone

Reimplemented from core_availability\tree_node.

Reimplemented in availability_date\condition.

save()

availability_completion\condition::save

(

)

Saves tree data back to a structure object.

Return values

stdClass

Structure object (ready to be made into JSON format)

Reimplemented from core_availability\tree_node.

unique_sql_parameter()

static core_availability\tree_node::unique_sql_parameter ( array & $params, $value )

staticprotectedinherited

Utility function for generating SQL parameters (because we can't use ? parameters because get_enrolled_sql has infected us with horrible named parameters).

Parameters

array	$params	Params array (value will be added to this array)
string | int	$value	Value

Return values

SQL	code for the parameter, e.g. ':pr1234'

update_after_restore()

availability_completion\condition::update_after_restore	(		$restoreid,
			$courseid,
		base_logger	$logger,
			$name )

Updates this node after restore, returning true if anything changed.

See also

core_availability\tree_node\update_after_restore

Parameters

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)

Return values

bool	True if there was any change

Reimplemented from core_availability\tree_node.

update_dependency_id()

availability_completion\condition::update_dependency_id	(		$table,
			$oldid,
			$newid )

Updates this node if it contains any references (dependencies) to the given table and id.

Parameters

string	$table	Table name e.g. 'course_modules'
int	$oldid	Previous ID
int	$newid	New ID

Return values

bool	True if it changed, otherwise false

Reimplemented from core_availability\condition.

---

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

• availability/condition/completion/classes/condition.php