MDL-50540 glossary: New WS mod_glossary_get_glossaries_by_courses
[moodle.git] / mod / glossary / classes / external.php
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     }