MDL-10971 question type multianswer: Respect quiz shuffle option
[moodle.git] / availability / classes / tree_node.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Node (base class) used to construct a tree of availability conditions.
19  *
20  * @package core_availability
21  * @copyright 2014 The Open University
22  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace core_availability;
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Node (base class) used to construct a tree of availability conditions.
31  *
32  * @package core_availability
33  * @copyright 2014 The Open University
34  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
35  */
36 abstract class tree_node {
37     /**
38      * Determines whether this particular item is currently available
39      * according to the availability criteria.
40      *
41      * - This does not include the 'visible' setting (i.e. this might return
42      *   true even if visible is false); visible is handled independently.
43      * - This does not take account of the viewhiddenactivities capability.
44      *   That should apply later.
45      *
46      * The $not option is potentially confusing. This option always indicates
47      * the 'real' value of NOT. For example, a condition inside a 'NOT AND'
48      * group will get this called with $not = true, but if you put another
49      * 'NOT OR' group inside the first group, then a condition inside that will
50      * be called with $not = false. We need to use the real values, rather than
51      * the more natural use of the current value at this point inside the tree,
52      * so that the information displayed to users makes sense.
53      *
54      * @param bool $not Set true if we are inverting the condition
55      * @param \core_availability\info $info Item we're checking
56      * @param bool $grabthelot Performance hint: if true, caches information
57      *   required for all course-modules, to make the front page and similar
58      *   pages work more quickly (works only for current user)
59      * @param int $userid User ID to check availability for
60      * @return result Availability check result
61      */
62     public abstract function check_available($not,
63             \core_availability\info $info, $grabthelot, $userid);
65     /**
66      * Checks whether this condition is actually going to be available for
67      * all users under normal circumstances.
68      *
69      * Normally, if there are any conditions, then it may be hidden. However
70      * in the case of date conditions there are some conditions which will
71      * definitely not result in it being hidden for anyone.
72      *
73      * @param bool $not Set true if we are inverting the condition
74      * @return bool True if condition will return available for everyone
75      */
76     public abstract function is_available_for_all($not = false);
78     /**
79      * Saves tree data back to a structure object.
80      *
81      * @return \stdClass Structure object (ready to be made into JSON format)
82      */
83     public abstract function save();
85     /**
86      * Updates this node after restore, returning true if anything changed.
87      * The default behaviour is simply to return false. If there is a problem
88      * with the update, $logger can be used to output a warning.
89      *
90      * @param string $restoreid Restore ID
91      * @param int $courseid ID of target course
92      * @param \base_logger $logger Logger for any warnings
93      * @param string $name Name of this item (for use in warning messages)
94      * @return bool True if there was any change
95      */
96     public function update_after_restore($restoreid, $courseid, \base_logger $logger, $name) {
97         return false;
98     }
100     /**
101      * Updates this node if it contains any references (dependencies) to the
102      * given table and id.
103      *
104      * @param string $table Table name e.g. 'course_modules'
105      * @param int $oldid Previous ID
106      * @param int $newid New ID
107      * @return bool True if it changed, otherwise false
108      */
109     public abstract function update_dependency_id($table, $oldid, $newid);
111     /**
112      * Checks whether this condition applies to user lists. The default is
113      * false (the condition is used to control access, but does not prevent
114      * the student from appearing in lists).
115      *
116      * For example, group conditions apply to user lists: we do not want to
117      * include a student in a list of users if they are prohibited from
118      * accessing the activity because they don't belong to a relevant group.
119      * However, date conditions do not apply - we still want to show users
120      * in a list of people who might have submitted an assignment, even if they
121      * are no longer able to access the assignment in question because there is
122      * a date restriction.
123      *
124      * The general idea is that conditions which are likely to be permanent
125      * (group membership, user profile) apply to user lists. Conditions which
126      * are likely to be temporary (date, grade requirement) do not.
127      *
128      * Conditions which do apply to user lists must implement the
129      * filter_user_list function.
130      *
131      * @return bool True if this condition applies to user lists
132      */
133     public function is_applied_to_user_lists() {
134         return false;
135     }
137     /**
138      * Tests this condition against a user list. Users who do not meet the
139      * condition will be removed from the list.
140      *
141      * This function must be implemented if is_applied_to_user_lists returns
142      * true. Otherwise it will not be called.
143      *
144      * The function must operate efficiently, e.g. by using a fixed number of
145      * database queries regardless of how many users are in the list.
146      *
147      * Within this function, if you need to check capabilities, please use
148      * the provided checker which caches results where possible.
149      *
150      * @param array $users Array of userid => object
151      * @param bool $not True if this condition is applying in negative mode
152      * @param \core_availability\info $info Item we're checking
153      * @param capability_checker $checker
154      * @return array Filtered version of input array
155      * @throws \coding_exception If called on a condition that doesn't apply to user lists
156      */
157     public function filter_user_list(array $users, $not,
158             \core_availability\info $info, capability_checker $checker) {
159         throw new \coding_exception('Not implemented (do not call unless '.
160                 'is_applied_to_user_lists is true)');
161     }
163     /**
164      * Obtains SQL that returns a list of enrolled users that has been filtered
165      * by the conditions applied in the availability API, similar to calling
166      * get_enrolled_users and then filter_user_list. As for filter_user_list,
167      * this ONLY filteres out users with conditions that are marked as applying
168      * to user lists. For example, group conditions are included but date
169      * conditions are not included.
170      *
171      * The returned SQL is a query that returns a list of user IDs. It does not
172      * include brackets, so you neeed to add these to make it into a subquery.
173      * You would normally use it in an SQL phrase like "WHERE u.id IN ($sql)".
174      *
175      * The SQL will be complex and may be slow. It uses named parameters (sorry,
176      * I know they are annoying, but it was unavoidable here).
177      *
178      * If there are no conditions, the returned result is array('', array()).
179      *
180      * @param bool $not True if this condition is applying in negative mode
181      * @param \core_availability\info $info Item we're checking
182      * @param bool $onlyactive If true, only returns active enrolments
183      * @return array Array with two elements: SQL subquery and parameters array
184      * @throws \coding_exception If called on a condition that doesn't apply to user lists
185      */
186     public function get_user_list_sql($not, \core_availability\info $info, $onlyactive) {
187         if (!$this->is_applied_to_user_lists()) {
188             throw new \coding_exception('Not implemented (do not call unless '.
189                     'is_applied_to_user_lists is true)');
190         }
192         // Handle situation where plugin does not implement this, by returning a
193         // default (all enrolled users). This ensures compatibility with 2.7
194         // plugins and behaviour. Plugins should be updated to support this
195         // new function (if they return true to is_applied_to_user_lists).
196         debugging('Availability plugins that return true to is_applied_to_user_lists ' .
197                 'should also now implement get_user_list_sql: ' . get_class($this),
198                 DEBUG_DEVELOPER);
199         return get_enrolled_sql($info->get_context(), '', 0, $onlyactive);
200     }
202     /**
203      * Utility function for generating SQL parameters (because we can't use ?
204      * parameters because get_enrolled_sql has infected us with horrible named
205      * parameters).
206      *
207      * @param array $params Params array (value will be added to this array)
208      * @param string|int $value Value
209      * @return SQL code for the parameter, e.g. ':pr1234'
210      */
211     protected static function unique_sql_parameter(array &$params, $value) {
212         static $count = 1;
213         $unique = 'usp' . $count;
214         $params[$unique] = $value;
215         $count++;
216         return ':' . $unique;
217     }