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/>. | |
16 | /** | |
17 | * Glossary module external API | |
18 | * | |
19 | * @package mod_glossary | |
20 | * @category external | |
21 | * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com> | |
22 | * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later | |
23 | * @since Moodle 3.0 | |
24 | */ | |
25 | defined('MOODLE_INTERNAL') || die; | |
26 | require_once("$CFG->libdir/externallib.php"); | |
27 | /** | |
28 | * Glossary module external functions | |
29 | * | |
30 | * @package mod_glossary | |
31 | * @category external | |
32 | * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com> | |
33 | * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later | |
34 | * @since Moodle 3.0 | |
35 | */ | |
36 | class mod_glossary_external extends external_api { | |
37 | /** | |
38 | * Describes the parameters for get_glossaries_by_courses. | |
39 | * | |
40 | * @return external_external_function_parameters | |
41 | * @since Moodle 3.0 | |
42 | */ | |
43 | public static function get_glossaries_by_courses_parameters() { | |
44 | return new external_function_parameters ( | |
45 | array( | |
46 | 'courseids' => new external_multiple_structure( | |
47 | new external_value(PARAM_INT, 'course id'), | |
48 | 'Array of course ids', VALUE_DEFAULT, array() | |
49 | ), | |
50 | ) | |
51 | ); | |
52 | } | |
53 | /** | |
54 | * Returns a list of glossaries in a provided list of courses, | |
55 | * if no list is provided all glossaries that the user can view will be returned. | |
56 | * | |
57 | * @param array $courseids the course ids | |
58 | * @return array of glossaries details | |
59 | * @since Moodle 3.0 | |
60 | */ | |
61 | public static function get_glossaries_by_courses($courseids = array()) { | |
62 | global $CFG; | |
63 | $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids)); | |
64 | $warnings = array(); | |
65 | if (!empty($params['courseids'])) { | |
66 | $courses = array(); | |
67 | $courseids = $params['courseids']; | |
68 | } else { | |
69 | $courses = enrol_get_my_courses(); | |
70 | $courseids = array_keys($courses); | |
71 | } | |
72 | // Array to store the glossaries to return. | |
73 | $arrglossaries = array(); | |
74 | // Ensure there are courseids to loop through. | |
75 | if (!empty($courseids)) { | |
76 | // Array of the courses we are going to retrieve the glossaries from. | |
77 | $arraycourses = array(); | |
78 | // Go through the courseids. | |
79 | foreach ($courseids as $cid) { | |
80 | // Check the user can function in this context. | |
81 | try { | |
82 | $context = context_course::instance($cid); | |
83 | self::validate_context($context); | |
84 | if (has_capability('mod/glossary:view', $context)) { | |
85 | // Check if this course was already loaded (by enrol_get_my_courses). | |
86 | if (!isset($courses[$cid])) { | |
87 | $courses[$cid] = get_course($cid); | |
88 | } | |
89 | $arraycourses[$cid] = $courses[$cid]; | |
90 | } else { | |
91 | $warnings[] = array( | |
92 | 'item' => 'course', | |
93 | 'itemid' => $cid, | |
94 | 'warningcode' => '2', | |
95 | 'message' => get_string('missingrequiredcapability', 'webservice', 'mod/glossary:view') | |
96 | ); | |
97 | } | |
98 | } catch (Exception $e) { | |
99 | $warnings[] = array( | |
100 | 'item' => 'course', | |
101 | 'itemid' => $cid, | |
102 | 'warningcode' => '1', | |
103 | 'message' => 'No access rights in course context '.$e->getMessage() | |
104 | ); | |
105 | } | |
106 | } | |
107 | // Get the glossaries in this course, this function checks users visibility permissions. | |
108 | // We can avoid then additional validate_context calls. | |
109 | $glossaries = get_all_instances_in_courses("glossary", $arraycourses); | |
110 | foreach ($glossaries as $glossary) { | |
111 | $glossarycontext = context_module::instance($glossary->coursemodule); | |
112 | // Entry to return. | |
113 | $glossarydetails = array(); | |
114 | // First, we return information that any user can see in the web interface. | |
115 | $glossarydetails['id'] = $glossary->id; | |
116 | $glossarydetails['coursemodule'] = $glossary->coursemodule; | |
117 | $glossarydetails['course'] = $glossary->course; | |
118 | $glossarydetails['name'] = $glossary->name; | |
119 | // Format intro. | |
120 | list($glossarydetails['intro'], $glossarydetails['introformat']) = | |
121 | external_format_text($glossary->intro, $glossary->introformat, | |
122 | $glossarycontext->id, 'mod_glossary', 'intro', null); | |
123 | $glossarydetails['allowduplicatedentries'] = $glossary->allowduplicatedentries; | |
124 | $glossarydetails['displayformat'] = $glossary->displayformat; | |
125 | $glossarydetails['mainglossary'] = $glossary->mainglossary; | |
126 | $glossarydetails['showspecial'] = $glossary->showspecial; | |
127 | $glossarydetails['showalphabet'] = $glossary->showalphabet; | |
128 | $glossarydetails['showall'] = $glossary->showall; | |
129 | $glossarydetails['allowcomments'] = $glossary->allowcomments; | |
130 | $glossarydetails['allowprintview'] = $glossary->allowprintview; | |
131 | $glossarydetails['usedynalink'] = $glossary->usedynalink; | |
132 | $glossarydetails['defaultapproval'] = $glossary->defaultapproval; | |
133 | $glossarydetails['approvaldisplayformat'] = $glossary->approvaldisplayformat; | |
134 | $glossarydetails['globalglossary'] = $glossary->globalglossary; | |
135 | $glossarydetails['entbypage'] = $glossary->entbypage; | |
136 | $glossarydetails['editalways'] = $glossary->editalways; | |
137 | $glossarydetails['rsstype'] = $glossary->rsstype; | |
138 | $glossarydetails['rssarticles'] = $glossary->rssarticles; | |
139 | $glossarydetails['assessed'] = $glossary->assessed; | |
140 | $glossarydetails['assesstimestart'] = $glossary->assesstimestart; | |
141 | $glossarydetails['assesstimefinish'] = $glossary->assesstimefinish; | |
142 | $glossarydetails['scale'] = $glossary->scale; | |
143 | if (has_capability('moodle/course:manageactivities', $glossarycontext)) { | |
144 | $glossarydetails['timecreated'] = $glossary->timecreated; | |
145 | $glossarydetails['timemodified'] = $glossary->timemodified; | |
146 | $glossarydetails['completionentries'] = $glossary->completionentries; | |
147 | $glossarydetails['section'] = $glossary->section; | |
148 | $glossarydetails['visible'] = $glossary->visible; | |
149 | $glossarydetails['groupmode'] = $glossary->groupmode; | |
150 | $glossarydetails['groupingid'] = $glossary->groupingid; | |
151 | } | |
152 | $arrglossaries[] = $glossarydetails; | |
153 | } | |
154 | } | |
155 | $result = array(); | |
156 | $result['glossaries'] = $arrglossaries; | |
157 | $result['warnings'] = $warnings; | |
158 | return $result; | |
159 | } | |
160 | /** | |
161 | * Describes the get_glossaries_by_courses return value. | |
162 | * | |
163 | * @return external_single_structure | |
164 | * @since Moodle 3.0 | |
165 | */ | |
166 | public static function get_glossaries_by_courses_returns() { | |
167 | return new external_single_structure( | |
168 | array( | |
169 | 'glossaries' => new external_multiple_structure( | |
170 | new external_single_structure( | |
171 | array( | |
172 | 'id' => new external_value(PARAM_INT, 'Glossary id'), | |
173 | 'coursemodule' => new external_value(PARAM_INT, 'Course module id'), | |
174 | 'course' => new external_value(PARAM_TEXT, 'Course id'), | |
175 | 'name' => new external_value(PARAM_TEXT, 'Glossary name'), | |
176 | 'intro' => new external_value(PARAM_RAW, 'The Glossary intro'), | |
177 | 'introformat' => new external_format_value('intro'), | |
178 | 'allowduplicatedentries' => new external_value(PARAM_INT, 'If enabled, multiple entries can have the'. | |
179 | ' same concept name'), | |
180 | 'displayformat' => new external_value(PARAM_TEXT, 'display format type'), | |
181 | 'mainglossary' => new external_value(PARAM_INT, 'main glossary'), | |
182 | 'showspecial' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by'. | |
183 | ' special characters, such as @ and #'), | |
184 | 'showalphabet' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by'. | |
185 | ' letters of the alphabet'), | |
186 | 'showall' => new external_value(PARAM_INT, 'If enabled, participants can browse all entries '. | |
187 | ' at once'), | |
188 | 'allowcomments' => new external_value(PARAM_INT, 'If enabled, all participants with permission to '. | |
189 | 'create comments will be able to add comments to glossary entries'), | |
190 | 'allowprintview' => new external_value(PARAM_INT, 'If enabled, students are provided with a link to a '. | |
191 | ' printer-friendly version of the glossary. The link is always available to teachers'), | |
192 | 'usedynalink' => new external_value(PARAM_INT, 'If site-wide glossary auto-linking has been enabled by'. | |
193 | ' an administrator and this checkbox is ticked, the entry will be automatically linked'. | |
194 | ' wherever the concept words and phrases appear throughout the rest of the course.'), | |
195 | 'defaultapproval' => new external_value(PARAM_INT, 'If set to no, entries require approving by a '. | |
196 | 'teacher before they are viewable by everyone.'), | |
197 | 'approvaldisplayformat' => new external_value(PARAM_TEXT, 'When approving glossary items you may wish'. | |
198 | ' to use a different display format'), | |
199 | 'globalglossary' => new external_value(PARAM_INT, ''), | |
200 | 'entbypage' => new external_value(PARAM_INT, 'Entries shown per page'), | |
201 | 'editalways' => new external_value(PARAM_INT, 'Always allow editing'), | |
202 | 'rsstype' => new external_value(PARAM_INT, 'To enable the RSS feed for this activity, select either'. | |
203 | ' concepts with author or concepts without author to be included in the feed'), | |
204 | 'rssarticles' => new external_value(PARAM_INT, 'This setting specifies the number of glossary entry'. | |
205 | ' concepts to include in the RSS feed. Between 5 and 20 generally acceptable'), | |
206 | 'assessed' => new external_value(PARAM_INT, 'assessed'), | |
207 | 'assesstimestart' => new external_value(PARAM_RAW, 'assess time start'), | |
208 | 'assesstimefinish' => new external_value(PARAM_RAW, 'assess time finish'), | |
209 | 'scale' => new external_value(PARAM_INT, 'scale'), | |
210 | 'timecreated' => new external_value(PARAM_RAW, 'time created', VALUE_OPTIONAL), | |
211 | 'timemodified' => new external_value(PARAM_RAW, 'time modified', VALUE_OPTIONAL), | |
212 | 'completionentries' => new external_value(PARAM_INT, 'completion entries', VALUE_OPTIONAL), | |
213 | 'section' => new external_value(PARAM_INT, 'section', VALUE_OPTIONAL), | |
214 | 'visible' => new external_value(PARAM_INT, 'visible', VALUE_OPTIONAL), | |
215 | 'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL), | |
216 | 'groupingid' => new external_value(PARAM_INT, 'grouping id', VALUE_OPTIONAL), | |
217 | ), 'Glossaries' | |
218 | ) | |
219 | ), | |
220 | 'warnings' => new external_warnings(), | |
221 | ) | |
222 | ); | |
223 | } | |
224 | } |