source: moodle/trunk/fuentes/availability/classes/tree_node.php @ 1331

Last change on this file since 1331 was 1331, checked in by jrpelegrina, 3 years ago

Updated to moodle 3.0.3

File size: 11.0 KB
Line 
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/>.
16
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 */
24
25namespace core_availability;
26
27defined('MOODLE_INTERNAL') || die();
28
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 */
36abstract 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);
64
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);
77
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();
84
85    /**
86     * Checks whether this node should be included after restore or not. The
87     * node may be removed depending on restore settings, which you can get from
88     * the $task object.
89     *
90     * By default nodes are still included after restore.
91     *
92     * @param string $restoreid Restore ID
93     * @param int $courseid ID of target course
94     * @param \base_logger $logger Logger for any warnings
95     * @param string $name Name of this item (for use in warning messages)
96     * @param \base_task $task Current restore task
97     * @return bool True if there was any change
98     */
99    public function include_after_restore($restoreid, $courseid, \base_logger $logger, $name,
100            \base_task $task) {
101        return true;
102    }
103
104    /**
105     * Updates this node after restore, returning true if anything changed.
106     * The default behaviour is simply to return false. If there is a problem
107     * with the update, $logger can be used to output a warning.
108     *
109     * Note: If you need information about the date offset, call
110     * \core_availability\info::get_restore_date_offset($restoreid). For
111     * information on the restoring task and its settings, call
112     * \core_availability\info::get_restore_task($restoreid).
113     *
114     * @param string $restoreid Restore ID
115     * @param int $courseid ID of target course
116     * @param \base_logger $logger Logger for any warnings
117     * @param string $name Name of this item (for use in warning messages)
118     * @return bool True if there was any change
119     */
120    public function update_after_restore($restoreid, $courseid, \base_logger $logger, $name) {
121        return false;
122    }
123
124    /**
125     * Updates this node if it contains any references (dependencies) to the
126     * given table and id.
127     *
128     * @param string $table Table name e.g. 'course_modules'
129     * @param int $oldid Previous ID
130     * @param int $newid New ID
131     * @return bool True if it changed, otherwise false
132     */
133    public abstract function update_dependency_id($table, $oldid, $newid);
134
135    /**
136     * Checks whether this condition applies to user lists. The default is
137     * false (the condition is used to control access, but does not prevent
138     * the student from appearing in lists).
139     *
140     * For example, group conditions apply to user lists: we do not want to
141     * include a student in a list of users if they are prohibited from
142     * accessing the activity because they don't belong to a relevant group.
143     * However, date conditions do not apply - we still want to show users
144     * in a list of people who might have submitted an assignment, even if they
145     * are no longer able to access the assignment in question because there is
146     * a date restriction.
147     *
148     * The general idea is that conditions which are likely to be permanent
149     * (group membership, user profile) apply to user lists. Conditions which
150     * are likely to be temporary (date, grade requirement) do not.
151     *
152     * Conditions which do apply to user lists must implement the
153     * filter_user_list function.
154     *
155     * @return bool True if this condition applies to user lists
156     */
157    public function is_applied_to_user_lists() {
158        return false;
159    }
160
161    /**
162     * Tests this condition against a user list. Users who do not meet the
163     * condition will be removed from the list, unless they have the ability
164     * to view hidden activities/sections.
165     *
166     * This function must be implemented if is_applied_to_user_lists returns
167     * true. Otherwise it will not be called.
168     *
169     * The function must operate efficiently, e.g. by using a fixed number of
170     * database queries regardless of how many users are in the list.
171     *
172     * Within this function, if you need to check capabilities, please use
173     * the provided checker which caches results where possible.
174     *
175     * Conditions do not need to check the viewhiddenactivities or
176     * viewhiddensections capabilities. These are handled by
177     * core_availability\info::filter_user_list.
178     *
179     * @param array $users Array of userid => object
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 capability_checker $checker
183     * @return array Filtered version of input array
184     * @throws \coding_exception If called on a condition that doesn't apply to user lists
185     */
186    public function filter_user_list(array $users, $not,
187            \core_availability\info $info, capability_checker $checker) {
188        throw new \coding_exception('Not implemented (do not call unless '.
189                'is_applied_to_user_lists is true)');
190    }
191
192    /**
193     * Obtains SQL that returns a list of enrolled users that has been filtered
194     * by the conditions applied in the availability API, similar to calling
195     * get_enrolled_users and then filter_user_list. As for filter_user_list,
196     * this ONLY filters out users with conditions that are marked as applying
197     * to user lists. For example, group conditions are included but date
198     * conditions are not included.
199     *
200     * The returned SQL is a query that returns a list of user IDs. It does not
201     * include brackets, so you neeed to add these to make it into a subquery.
202     * You would normally use it in an SQL phrase like "WHERE u.id IN ($sql)".
203     *
204     * The SQL will be complex and may be slow. It uses named parameters (sorry,
205     * I know they are annoying, but it was unavoidable here).
206     *
207     * If there are no conditions, the returned result is array('', array()).
208     *
209     * Conditions do not need to check the viewhiddenactivities or
210     * viewhiddensections capabilities. These are handled by
211     * core_availability\info::get_user_list_sql.
212     *
213     * @param bool $not True if this condition is applying in negative mode
214     * @param \core_availability\info $info Item we're checking
215     * @param bool $onlyactive If true, only returns active enrolments
216     * @return array Array with two elements: SQL subquery and parameters array
217     * @throws \coding_exception If called on a condition that doesn't apply to user lists
218     */
219    public function get_user_list_sql($not, \core_availability\info $info, $onlyactive) {
220        if (!$this->is_applied_to_user_lists()) {
221            throw new \coding_exception('Not implemented (do not call unless '.
222                    'is_applied_to_user_lists is true)');
223        }
224
225        // Handle situation where plugin does not implement this, by returning a
226        // default (all enrolled users). This ensures compatibility with 2.7
227        // plugins and behaviour. Plugins should be updated to support this
228        // new function (if they return true to is_applied_to_user_lists).
229        debugging('Availability plugins that return true to is_applied_to_user_lists ' .
230                'should also now implement get_user_list_sql: ' . get_class($this),
231                DEBUG_DEVELOPER);
232        return get_enrolled_sql($info->get_context(), '', 0, $onlyactive);
233    }
234
235    /**
236     * Utility function for generating SQL parameters (because we can't use ?
237     * parameters because get_enrolled_sql has infected us with horrible named
238     * parameters).
239     *
240     * @param array $params Params array (value will be added to this array)
241     * @param string|int $value Value
242     * @return SQL code for the parameter, e.g. ':pr1234'
243     */
244    protected static function unique_sql_parameter(array &$params, $value) {
245        static $count = 1;
246        $unique = 'usp' . $count;
247        $params[$unique] = $value;
248        $count++;
249        return ':' . $unique;
250    }
251}
Note: See TracBrowser for help on using the repository browser.