MDL-50540 glossary: Unit test for mod_glossary_get_glossaries_by_courses
[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/>.
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 */
25defined('MOODLE_INTERNAL') || die;
26require_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 */
36class 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}