MDL-50540 mod_glossary: Final clean up of new external function
[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/>.
17 /**
18  * Glossary module external API.
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
24  * @since      Moodle 3.1
25  */
26 defined('MOODLE_INTERNAL') || die;
27 require_once($CFG->libdir . '/externallib.php');
29 /**
30  * Glossary module external functions.
31  *
32  * @package    mod_glossary
33  * @category   external
34  * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  * @since      Moodle 3.1
37  */
38 class mod_glossary_external extends external_api {
40     /**
41      * Describes the parameters for get_glossaries_by_courses.
42      *
43      * @return external_external_function_parameters
44      * @since Moodle 3.1
45      */
46     public static function get_glossaries_by_courses_parameters() {
47         return new external_function_parameters (
48             array(
49                 'courseids' => new external_multiple_structure(
50                     new external_value(PARAM_INT, 'course id'),
51                     'Array of course IDs', VALUE_DEFAULT, array()
52                 ),
53             )
54         );
55     }
57     /**
58      * Returns a list of glossaries in a provided list of courses.
59      *
60      * If no list is provided all glossaries that the user can view will be returned.
61      *
62      * @param array $courseids the course IDs.
63      * @return array of glossaries
64      * @since Moodle 3.1
65      */
66     public static function get_glossaries_by_courses($courseids = array()) {
67         $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids));
69         $warnings = array();
70         $courses = array();
71         $courseids = $params['courseids'];
73         if (empty($courseids)) {
74             $courses = enrol_get_my_courses();
75             $courseids = array_keys($courses);
76         }
78         // Array to store the glossaries to return.
79         $glossaries = array();
81         // Ensure there are courseids to loop through.
82         if (!empty($courseids)) {
83             list($courses, $warnings) = external_util::validate_courses($courseids, $courses);
85             // Get the glossaries in these courses, this function checks users visibility permissions.
86             $glossaries = get_all_instances_in_courses('glossary', $courses);
87             foreach ($glossaries as $glossary) {
88                 $context = context_module::instance($glossary->coursemodule);
89                 $glossary->name = external_format_string($glossary->name, $context->id);
90                 list($glossary->intro, $glossary->introformat) = external_format_text($glossary->intro, $glossary->introformat,
91                     $context->id, 'mod_glossary', 'intro', null);
92             }
93         }
95         $result = array();
96         $result['glossaries'] = $glossaries;
97         $result['warnings'] = $warnings;
98         return $result;
99     }
101     /**
102      * Describes the get_glossaries_by_courses return value.
103      *
104      * @return external_single_structure
105      * @since Moodle 3.1
106      */
107     public static function get_glossaries_by_courses_returns() {
108         return new external_single_structure(array(
109             'glossaries' => new external_multiple_structure(
110                 new external_single_structure(array(
111                     'id' => new external_value(PARAM_INT, 'Glossary id'),
112                     'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
113                     'course' => new external_value(PARAM_INT, 'Course id'),
114                     'name' => new external_value(PARAM_RAW, 'Glossary name'),
115                     'intro' => new external_value(PARAM_RAW, 'The Glossary intro'),
116                     'introformat' => new external_format_value('intro'),
117                     'allowduplicatedentries' => new external_value(PARAM_INT, 'If enabled, multiple entries can have the' .
118                         ' same concept name'),
119                     'displayformat' => new external_value(PARAM_TEXT, 'Display format type'),
120                     'mainglossary' => new external_value(PARAM_INT, 'If enabled this glossary is a main glossary.'),
121                     'showspecial' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' .
122                         ' special characters, such as @ and #'),
123                     'showalphabet' => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by' .
124                         ' letters of the alphabet'),
125                     'showall' => new external_value(PARAM_INT, 'If enabled, participants can browse all entries at once'),
126                     'allowcomments' => new external_value(PARAM_INT, 'If enabled, all participants with permission to' .
127                         ' create comments will be able to add comments to glossary entries'),
128                     'allowprintview' => new external_value(PARAM_INT, 'If enabled, students are provided with a link to a' .
129                         ' printer-friendly version of the glossary. The link is always available to teachers'),
130                     'usedynalink' => new external_value(PARAM_INT, 'If site-wide glossary auto-linking has been enabled' .
131                         ' by an administrator and this checkbox is ticked, the entry will be automatically linked' .
132                         ' wherever the concept words and phrases appear throughout the rest of the course.'),
133                     'defaultapproval' => new external_value(PARAM_INT, 'If set to no, entries require approving by a' .
134                         ' teacher before they are viewable by everyone.'),
135                     'approvaldisplayformat' => new external_value(PARAM_TEXT, 'When approving glossary items you may wish' .
136                         ' to use a different display format'),
137                     'globalglossary' => new external_value(PARAM_INT, ''),
138                     'entbypage' => new external_value(PARAM_INT, 'Entries shown per page'),
139                     'editalways' => new external_value(PARAM_INT, 'Always allow editing'),
140                     'rsstype' => new external_value(PARAM_INT, 'To enable the RSS feed for this activity, select either' .
141                         ' concepts with author or concepts without author to be included in the feed'),
142                     'rssarticles' => new external_value(PARAM_INT, 'This setting specifies the number of glossary entry' .
143                         ' concepts to include in the RSS feed. Between 5 and 20 generally acceptable'),
144                     'assessed' => new external_value(PARAM_INT, 'Aggregate type'),
145                     'assesstimestart' => new external_value(PARAM_INT, 'Restrict rating to items created after this'),
146                     'assesstimefinish' => new external_value(PARAM_INT, 'Restrict rating to items created before this'),
147                     'scale' => new external_value(PARAM_INT, 'Scale ID'),
148                     'timecreated' => new external_value(PARAM_INT, 'Time created'),
149                     'timemodified' => new external_value(PARAM_INT, 'Time modified'),
150                     'completionentries' => new external_value(PARAM_INT, 'Number of entries to complete'),
151                     'section' => new external_value(PARAM_INT, 'Section'),
152                     'visible' => new external_value(PARAM_INT, 'Visible'),
153                     'groupmode' => new external_value(PARAM_INT, 'Group mode'),
154                     'groupingid' => new external_value(PARAM_INT, 'Grouping ID'),
155                 ), 'Glossaries')
156             ),
157             'warnings' => new external_warnings())
158         );
159     }