MDL-49231 mod_glossary: External function view_entry
[moodle.git] / mod / glossary / classes / external.php
CommitLineData
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
27defined('MOODLE_INTERNAL') || die();
28
bf5bbe01 29require_once($CFG->libdir . '/externallib.php');
d0d4372c 30require_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 */
41class 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}