Commit | Line | Data |
---|---|---|
23da998f CC |
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/>. | |
bf5bbe01 | 16 | |
23da998f | 17 | /** |
bf5bbe01 | 18 | * Glossary module external API. |
23da998f CC |
19 | * |
20 | * @package mod_glossary | |
21 | * @category external | |
22 | * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com> | |
23 | * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later | |
bf5bbe01 | 24 | * @since Moodle 3.1 |
23da998f | 25 | */ |
d0d4372c FM |
26 | |
27 | defined('MOODLE_INTERNAL') || die(); | |
28 | ||
bf5bbe01 | 29 | require_once($CFG->libdir . '/externallib.php'); |
d0d4372c | 30 | require_once($CFG->dirroot . '/mod/glossary/lib.php'); |
bf5bbe01 | 31 | |
23da998f | 32 | /** |
bf5bbe01 | 33 | * Glossary module external functions. |
23da998f CC |
34 | * |
35 | * @package mod_glossary | |
36 | * @category external | |
37 | * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com> | |
38 | * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later | |
bf5bbe01 | 39 | * @since Moodle 3.1 |
23da998f CC |
40 | */ |
41 | class mod_glossary_external extends external_api { | |
bf5bbe01 | 42 | |
23da998f CC |
43 | /** |
44 | * Describes the parameters for get_glossaries_by_courses. | |
45 | * | |
46 | * @return external_external_function_parameters | |
bf5bbe01 | 47 | * @since Moodle 3.1 |
23da998f CC |
48 | */ |
49 | public static function get_glossaries_by_courses_parameters() { | |
50 | return new external_function_parameters ( | |
51 | array( | |
52 | 'courseids' => new external_multiple_structure( | |
53 | new external_value(PARAM_INT, 'course id'), | |
bf5bbe01 | 54 | 'Array of course IDs', VALUE_DEFAULT, array() |
23da998f CC |
55 | ), |
56 | ) | |
57 | ); | |
58 | } | |
bf5bbe01 | 59 | |
23da998f | 60 | /** |
bf5bbe01 | 61 | * Returns a list of glossaries in a provided list of courses. |
23da998f | 62 | * |
bf5bbe01 FM |
63 | * If no list is provided all glossaries that the user can view will be returned. |
64 | * | |
65 | * @param array $courseids the course IDs. | |
66 | * @return array of glossaries | |
67 | * @since Moodle 3.1 | |
23da998f CC |
68 | */ |
69 | public static function get_glossaries_by_courses($courseids = array()) { | |
23da998f | 70 | $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids)); |
bf5bbe01 | 71 | |
23da998f | 72 | $warnings = array(); |
bf5bbe01 FM |
73 | $courses = array(); |
74 | $courseids = $params['courseids']; | |
75 | ||
76 | if (empty($courseids)) { | |
23da998f CC |
77 | $courses = enrol_get_my_courses(); |
78 | $courseids = array_keys($courses); | |
79 | } | |
bf5bbe01 | 80 | |
23da998f | 81 | // Array to store the glossaries to return. |
bf5bbe01 FM |
82 | $glossaries = array(); |
83 | ||
23da998f CC |
84 | // Ensure there are courseids to loop through. |
85 | if (!empty($courseids)) { | |
bf5bbe01 FM |
86 | list($courses, $warnings) = external_util::validate_courses($courseids, $courses); |
87 | ||
88 | // Get the glossaries in these courses, this function checks users visibility permissions. | |
89 | $glossaries = get_all_instances_in_courses('glossary', $courses); | |
23da998f | 90 | foreach ($glossaries as $glossary) { |
bf5bbe01 FM |
91 | $context = context_module::instance($glossary->coursemodule); |
92 | $glossary->name = external_format_string($glossary->name, $context->id); | |
93 | list($glossary->intro, $glossary->introformat) = external_format_text($glossary->intro, $glossary->introformat, | |
94 | $context->id, 'mod_glossary', 'intro', null); | |
23da998f CC |
95 | } |
96 | } | |
bf5bbe01 | 97 | |
23da998f | 98 | $result = array(); |
bf5bbe01 | 99 | $result['glossaries'] = $glossaries; |
23da998f CC |
100 | $result['warnings'] = $warnings; |
101 | return $result; | |
102 | } | |
bf5bbe01 | 103 | |
23da998f CC |
104 | /** |
105 | * Describes the get_glossaries_by_courses return value. | |
106 | * | |
107 | * @return external_single_structure | |
bf5bbe01 | 108 | * @since Moodle 3.1 |
23da998f CC |
109 | */ |
110 | public static function get_glossaries_by_courses_returns() { | |
bf5bbe01 FM |
111 | return new external_single_structure(array( |
112 | 'glossaries' => new external_multiple_structure( | |
113 | new external_single_structure(array( | |
114 | 'id' => new external_value(PARAM_INT, 'Glossary id'), | |
115 | 'coursemodule' => new external_value(PARAM_INT, 'Course module id'), | |
116 | 'course' => new external_value(PARAM_INT, 'Course id'), | |
117 | 'name' => new external_value(PARAM_RAW, 'Glossary name'), | |
118 | 'intro' => new external_value(PARAM_RAW, 'The Glossary intro'), | |
119 | 'introformat' => new external_format_value('intro'), | |
120 | 'allowduplicatedentries' => new external_value(PARAM_INT, 'If enabled, multiple entries can have the' . | |
121 | ' same concept name'), | |
122 | 'displayformat' => new external_value(PARAM_TEXT, 'Display format type'), | |
123 | 'mainglossary' => new external_value(PARAM_INT, 'If enabled this glossary is a main glossary.'), | |
124 | 'showspecial' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' . | |
125 | ' special characters, such as @ and #'), | |
126 | 'showalphabet' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' . | |
127 | ' letters of the alphabet'), | |
128 | 'showall' => new external_value(PARAM_INT, 'If enabled, participants can browse all entries at once'), | |
129 | 'allowcomments' => new external_value(PARAM_INT, 'If enabled, all participants with permission to' . | |
130 | ' create comments will be able to add comments to glossary entries'), | |
131 | 'allowprintview' => new external_value(PARAM_INT, 'If enabled, students are provided with a link to a' . | |
132 | ' printer-friendly version of the glossary. The link is always available to teachers'), | |
133 | 'usedynalink' => new external_value(PARAM_INT, 'If site-wide glossary auto-linking has been enabled' . | |
134 | ' by an administrator and this checkbox is ticked, the entry will be automatically linked' . | |
135 | ' wherever the concept words and phrases appear throughout the rest of the course.'), | |
136 | 'defaultapproval' => new external_value(PARAM_INT, 'If set to no, entries require approving by a' . | |
137 | ' teacher before they are viewable by everyone.'), | |
138 | 'approvaldisplayformat' => new external_value(PARAM_TEXT, 'When approving glossary items you may wish' . | |
139 | ' to use a different display format'), | |
140 | 'globalglossary' => new external_value(PARAM_INT, ''), | |
141 | 'entbypage' => new external_value(PARAM_INT, 'Entries shown per page'), | |
142 | 'editalways' => new external_value(PARAM_INT, 'Always allow editing'), | |
143 | 'rsstype' => new external_value(PARAM_INT, 'To enable the RSS feed for this activity, select either' . | |
144 | ' concepts with author or concepts without author to be included in the feed'), | |
145 | 'rssarticles' => new external_value(PARAM_INT, 'This setting specifies the number of glossary entry' . | |
146 | ' concepts to include in the RSS feed. Between 5 and 20 generally acceptable'), | |
147 | 'assessed' => new external_value(PARAM_INT, 'Aggregate type'), | |
148 | 'assesstimestart' => new external_value(PARAM_INT, 'Restrict rating to items created after this'), | |
149 | 'assesstimefinish' => new external_value(PARAM_INT, 'Restrict rating to items created before this'), | |
150 | 'scale' => new external_value(PARAM_INT, 'Scale ID'), | |
151 | 'timecreated' => new external_value(PARAM_INT, 'Time created'), | |
152 | 'timemodified' => new external_value(PARAM_INT, 'Time modified'), | |
153 | 'completionentries' => new external_value(PARAM_INT, 'Number of entries to complete'), | |
154 | 'section' => new external_value(PARAM_INT, 'Section'), | |
155 | 'visible' => new external_value(PARAM_INT, 'Visible'), | |
156 | 'groupmode' => new external_value(PARAM_INT, 'Group mode'), | |
157 | 'groupingid' => new external_value(PARAM_INT, 'Grouping ID'), | |
158 | ), 'Glossaries') | |
159 | ), | |
160 | 'warnings' => new external_warnings()) | |
23da998f CC |
161 | ); |
162 | } | |
d0d4372c FM |
163 | |
164 | /** | |
165 | * Returns the description of the external function parameters. | |
166 | * | |
167 | * @return external_function_parameters | |
168 | * @since Moodle 3.1 | |
169 | */ | |
170 | public static function view_glossary_parameters() { | |
171 | return new external_function_parameters(array( | |
172 | 'id' => new external_value(PARAM_INT, 'Glossary instance ID'), | |
173 | 'mode' => new external_value(PARAM_ALPHA, 'The mode in which the glossary is viewed'), | |
174 | )); | |
175 | } | |
176 | ||
177 | /** | |
178 | * Notify that the course module was viewed. | |
179 | * | |
180 | * @param int $id The glossary instance ID. | |
181 | * @return array of warnings and status result | |
182 | * @since Moodle 3.1 | |
183 | * @throws moodle_exception | |
184 | */ | |
185 | public static function view_glossary($id, $mode) { | |
186 | global $DB; | |
187 | ||
188 | $params = self::validate_parameters(self::view_glossary_parameters(), array( | |
189 | 'id' => $id, | |
190 | 'mode' => $mode | |
191 | )); | |
192 | $id = $params['id']; | |
193 | $mode = $params['mode']; | |
194 | $warnings = array(); | |
195 | ||
196 | // Fetch and confirm. | |
197 | $glossary = $DB->get_record('glossary', array('id' => $id), '*', MUST_EXIST); | |
198 | list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary'); | |
199 | $context = context_module::instance($cm->id); | |
200 | self::validate_context($context); | |
201 | ||
202 | // Trigger module viewed event. | |
203 | glossary_view($glossary, $course, $cm, $context, $mode); | |
204 | ||
205 | return array( | |
206 | 'status' => true, | |
207 | 'warnings' => $warnings | |
208 | ); | |
209 | } | |
210 | ||
211 | /** | |
212 | * Returns the description of the external function return value. | |
213 | * | |
214 | * @return external_description | |
215 | * @since Moodle 3.1 | |
216 | */ | |
217 | public static function view_glossary_returns() { | |
218 | return new external_single_structure(array( | |
219 | 'status' => new external_value(PARAM_BOOL, 'True on success'), | |
220 | 'warnings' => new external_warnings() | |
221 | )); | |
222 | } | |
223 | ||
61fce284 FM |
224 | /** |
225 | * Returns the description of the external function parameters. | |
226 | * | |
227 | * @return external_function_parameters | |
228 | * @since Moodle 3.1 | |
229 | */ | |
230 | public static function view_entry_parameters() { | |
231 | return new external_function_parameters(array( | |
232 | 'id' => new external_value(PARAM_INT, 'Glossary entry ID'), | |
233 | )); | |
234 | } | |
235 | ||
236 | /** | |
237 | * Notify that the entry was viewed. | |
238 | * | |
239 | * @param int $id The entry ID. | |
240 | * @return array of warnings and status result | |
241 | * @since Moodle 3.1 | |
242 | * @throws moodle_exception | |
243 | */ | |
244 | public static function view_entry($id) { | |
245 | global $DB, $USER; | |
246 | ||
247 | $params = self::validate_parameters(self::view_entry_parameters(), array('id' => $id)); | |
248 | $id = $params['id']; | |
249 | $warnings = array(); | |
250 | ||
251 | // Fetch and confirm. | |
252 | $entry = $DB->get_record('glossary_entries', array('id' => $id), '*', MUST_EXIST); | |
253 | $glossary = $DB->get_record('glossary', array('id' => $entry->glossaryid), '*', MUST_EXIST); | |
254 | list($course, $cm) = get_course_and_cm_from_instance($glossary, 'glossary'); | |
255 | $context = context_module::instance($cm->id); | |
256 | self::validate_context($context); | |
257 | ||
258 | if (empty($entry->approved) && $entry->userid != $USER->id && !has_capability('mod/glossary:approve', $context)) { | |
259 | throw new invalid_parameter_exception('invalidentry'); | |
260 | } | |
261 | ||
262 | // Trigger view. | |
263 | glossary_entry_view($entry, $context); | |
264 | ||
265 | return array( | |
266 | 'status' => true, | |
267 | 'warnings' => $warnings | |
268 | ); | |
269 | } | |
270 | ||
271 | /** | |
272 | * Returns the description of the external function return value. | |
273 | * | |
274 | * @return external_description | |
275 | * @since Moodle 3.1 | |
276 | */ | |
277 | public static function view_entry_returns() { | |
278 | return new external_single_structure(array( | |
279 | 'status' => new external_value(PARAM_BOOL, 'True on success'), | |
280 | 'warnings' => new external_warnings() | |
281 | )); | |
282 | } | |
283 | ||
23da998f | 284 | } |