weekly release 3.1dev
[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
CC
25 */
26defined('MOODLE_INTERNAL') || die;
bf5bbe01
FM
27require_once($CFG->libdir . '/externallib.php');
28
23da998f 29/**
bf5bbe01 30 * Glossary module external functions.
23da998f
CC
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
bf5bbe01 36 * @since Moodle 3.1
23da998f
CC
37 */
38class mod_glossary_external extends external_api {
bf5bbe01 39
23da998f
CC
40 /**
41 * Describes the parameters for get_glossaries_by_courses.
42 *
43 * @return external_external_function_parameters
bf5bbe01 44 * @since Moodle 3.1
23da998f
CC
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'),
bf5bbe01 51 'Array of course IDs', VALUE_DEFAULT, array()
23da998f
CC
52 ),
53 )
54 );
55 }
bf5bbe01 56
23da998f 57 /**
bf5bbe01 58 * Returns a list of glossaries in a provided list of courses.
23da998f 59 *
bf5bbe01
FM
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
23da998f
CC
65 */
66 public static function get_glossaries_by_courses($courseids = array()) {
23da998f 67 $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids));
bf5bbe01 68
23da998f 69 $warnings = array();
bf5bbe01
FM
70 $courses = array();
71 $courseids = $params['courseids'];
72
73 if (empty($courseids)) {
23da998f
CC
74 $courses = enrol_get_my_courses();
75 $courseids = array_keys($courses);
76 }
bf5bbe01 77
23da998f 78 // Array to store the glossaries to return.
bf5bbe01
FM
79 $glossaries = array();
80
23da998f
CC
81 // Ensure there are courseids to loop through.
82 if (!empty($courseids)) {
bf5bbe01
FM
83 list($courses, $warnings) = external_util::validate_courses($courseids, $courses);
84
85 // Get the glossaries in these courses, this function checks users visibility permissions.
86 $glossaries = get_all_instances_in_courses('glossary', $courses);
23da998f 87 foreach ($glossaries as $glossary) {
bf5bbe01
FM
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);
23da998f
CC
92 }
93 }
bf5bbe01 94
23da998f 95 $result = array();
bf5bbe01 96 $result['glossaries'] = $glossaries;
23da998f
CC
97 $result['warnings'] = $warnings;
98 return $result;
99 }
bf5bbe01 100
23da998f
CC
101 /**
102 * Describes the get_glossaries_by_courses return value.
103 *
104 * @return external_single_structure
bf5bbe01 105 * @since Moodle 3.1
23da998f
CC
106 */
107 public static function get_glossaries_by_courses_returns() {
bf5bbe01
FM
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())
23da998f
CC
158 );
159 }
160}