[moodle.git] / mod / glossary / classes / external.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
/**
 * Glossary module external API
 *
 * @package    mod_glossary
 * @category   external
 * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @since      Moodle 3.0
 */
defined('MOODLE_INTERNAL') || die;
require_once("$CFG->libdir/externallib.php");
/**
 * Glossary module external functions
 *
 * @package    mod_glossary
 * @category   external
 * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @since      Moodle 3.0
 */
class mod_glossary_external extends external_api {
    /**
     * Describes the parameters for get_glossaries_by_courses.
     *
     * @return external_external_function_parameters
     * @since Moodle 3.0
     */
    public static function get_glossaries_by_courses_parameters() {
        return new external_function_parameters (
            array(
                'courseids' => new external_multiple_structure(
                    new external_value(PARAM_INT, 'course id'),
                    'Array of course ids', VALUE_DEFAULT, array()
                ),
            )
        );
    }
    /**
     * Returns a list of glossaries in a provided list of courses,
     * if no list is provided all glossaries that the user can view will be returned.
     *
     * @param array $courseids the course ids
     * @return array of glossaries details
     * @since Moodle 3.0
     */
    public static function get_glossaries_by_courses($courseids = array()) {
        global $CFG;
        $params = self::validate_parameters(self::get_glossaries_by_courses_parameters(), array('courseids' => $courseids));
        $warnings = array();
        if (!empty($params['courseids'])) {
            $courses = array();
            $courseids = $params['courseids'];
        } else {
            $courses = enrol_get_my_courses();
            $courseids = array_keys($courses);
        }
        // Array to store the glossaries to return.
        $arrglossaries = array();
        // Ensure there are courseids to loop through.
        if (!empty($courseids)) {
            // Array of the courses we are going to retrieve the glossaries from.
            $arraycourses = array();
            // Go through the courseids.
            foreach ($courseids as $cid) {
                // Check the user can function in this context.
                try {
                    $context = context_course::instance($cid);
                    self::validate_context($context);
                    if (has_capability('mod/glossary:view', $context)) {
                        // Check if this course was already loaded (by enrol_get_my_courses).
                        if (!isset($courses[$cid])) {
                            $courses[$cid] = get_course($cid);
                        }
                        $arraycourses[$cid] = $courses[$cid];
                    } else {
                        $warnings[] = array(
                            'item' => 'course',
                            'itemid' => $cid,
                            'warningcode' => '2',
                            'message' => get_string('missingrequiredcapability', 'webservice', 'mod/glossary:view')
                        );
                    }
                } catch (Exception $e) {
                    $warnings[] = array(
                        'item' => 'course',
                        'itemid' => $cid,
                        'warningcode' => '1',
                        'message' => 'No access rights in course context '.$e->getMessage()
                    );
                }
            }
            // Get the glossaries in this course, this function checks users visibility permissions.
            // We can avoid then additional validate_context calls.
            $glossaries = get_all_instances_in_courses("glossary", $arraycourses);
            foreach ($glossaries as $glossary) {
                $glossarycontext = context_module::instance($glossary->coursemodule);
                // Entry to return.
                $glossarydetails = array();
                // First, we return information that any user can see in the web interface.
                $glossarydetails['id'] = $glossary->id;
                $glossarydetails['coursemodule']      = $glossary->coursemodule;
                $glossarydetails['course']            = $glossary->course;
                $glossarydetails['name']              = $glossary->name;
                // Format intro.
                list($glossarydetails['intro'], $glossarydetails['introformat']) =
                    external_format_text($glossary->intro, $glossary->introformat,
                                            $glossarycontext->id, 'mod_glossary', 'intro', null);
                $glossarydetails['allowduplicatedentries'] = $glossary->allowduplicatedentries;
                $glossarydetails['displayformat']          = $glossary->displayformat;
                $glossarydetails['mainglossary']           = $glossary->mainglossary;
                $glossarydetails['showspecial']            = $glossary->showspecial;
                $glossarydetails['showalphabet']           = $glossary->showalphabet;
                $glossarydetails['showall']                = $glossary->showall;
                $glossarydetails['allowcomments']          = $glossary->allowcomments;
                $glossarydetails['allowprintview']         = $glossary->allowprintview;
                $glossarydetails['usedynalink']            = $glossary->usedynalink;
                $glossarydetails['defaultapproval']        = $glossary->defaultapproval;
                $glossarydetails['approvaldisplayformat']  = $glossary->approvaldisplayformat;
                $glossarydetails['globalglossary']         = $glossary->globalglossary;
                $glossarydetails['entbypage']              = $glossary->entbypage;
                $glossarydetails['editalways']             = $glossary->editalways;
                $glossarydetails['rsstype']                = $glossary->rsstype;
                $glossarydetails['rssarticles']            = $glossary->rssarticles;
                $glossarydetails['assessed']               = $glossary->assessed;
                $glossarydetails['assesstimestart']        = $glossary->assesstimestart;
                $glossarydetails['assesstimefinish']       = $glossary->assesstimefinish;
                $glossarydetails['scale']                  = $glossary->scale;
                if (has_capability('moodle/course:manageactivities', $glossarycontext)) {
                    $glossarydetails['timecreated']            = $glossary->timecreated;
                    $glossarydetails['timemodified']           = $glossary->timemodified;
                    $glossarydetails['completionentries']      = $glossary->completionentries;
                    $glossarydetails['section']                = $glossary->section;
                    $glossarydetails['visible']                = $glossary->visible;
                    $glossarydetails['groupmode']              = $glossary->groupmode;
                    $glossarydetails['groupingid']             = $glossary->groupingid;
                }
                $arrglossaries[] = $glossarydetails;
            }
        }
        $result = array();
        $result['glossaries'] = $arrglossaries;
        $result['warnings'] = $warnings;
        return $result;
    }
    /**
     * Describes the get_glossaries_by_courses return value.
     *
     * @return external_single_structure
     * @since Moodle 3.0
     */
    public static function get_glossaries_by_courses_returns() {
        return new external_single_structure(
            array(
                'glossaries' => new external_multiple_structure(
                    new external_single_structure(
                        array(
                            'id' => new external_value(PARAM_INT, 'Glossary id'),
                            'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
                            'course' => new external_value(PARAM_TEXT, 'Course id'),
                            'name' => new external_value(PARAM_TEXT, 'Glossary name'),
                            'intro' => new external_value(PARAM_RAW, 'The Glossary intro'),
                            'introformat' => new external_format_value('intro'),
                            'allowduplicatedentries' => new external_value(PARAM_INT, 'If enabled, multiple entries can have the'.
                                                                                                            ' same concept name'),
                            'displayformat' => new external_value(PARAM_TEXT, 'display format type'),
                            'mainglossary'  => new external_value(PARAM_INT, 'main glossary'),
                            'showspecial'   => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by'.
                                                                                           ' special characters, such as @ and #'),
                            'showalphabet'  => new external_value(PARAM_INT, 'If enabled, participants can browse the glossary by'.
                                                                                                       ' letters of the alphabet'),
                            'showall'       => new external_value(PARAM_INT, 'If enabled, participants can browse all entries '.
                                                                                                                     ' at once'),
                            'allowcomments' => new external_value(PARAM_INT, 'If enabled, all participants with permission to '.
                                                             'create comments will be able to add comments to glossary entries'),
                            'allowprintview' => new external_value(PARAM_INT, 'If enabled, students are provided with a link to a '.
                                             ' printer-friendly version of the glossary. The link is always available to teachers'),
                            'usedynalink' => new external_value(PARAM_INT, 'If site-wide glossary auto-linking has been enabled by'.
                                            ' an administrator and this checkbox is ticked, the entry will be automatically linked'.
                                               ' wherever the concept words and phrases appear throughout the rest of the course.'),
                            'defaultapproval' => new external_value(PARAM_INT, 'If set to no, entries require approving by a '.
                                                                              'teacher before they are viewable by everyone.'),
                            'approvaldisplayformat' => new external_value(PARAM_TEXT, 'When approving glossary items you may wish'.
                                                                                             ' to use a different display format'),
                            'globalglossary' => new external_value(PARAM_INT, ''),
                            'entbypage' => new external_value(PARAM_INT, 'Entries shown per page'),
                            'editalways' => new external_value(PARAM_INT, 'Always allow editing'),
                            'rsstype' => new external_value(PARAM_INT, 'To enable the RSS feed for this activity, select either'.
                                                   ' concepts with author or concepts without author to be included in the feed'),
                            'rssarticles' => new external_value(PARAM_INT, 'This setting specifies the number of glossary entry'.
                                                  ' concepts to include in the RSS feed. Between 5 and 20 generally acceptable'),
                            'assessed' => new external_value(PARAM_INT, 'assessed'),
                            'assesstimestart' => new external_value(PARAM_RAW, 'assess time start'),
                            'assesstimefinish' => new external_value(PARAM_RAW, 'assess time finish'),
                            'scale' => new external_value(PARAM_INT, 'scale'),
                            'timecreated' => new external_value(PARAM_RAW, 'time created', VALUE_OPTIONAL),
                            'timemodified' => new external_value(PARAM_RAW, 'time modified', VALUE_OPTIONAL),
                            'completionentries' => new external_value(PARAM_INT, 'completion entries', VALUE_OPTIONAL),
                            'section' => new external_value(PARAM_INT, 'section', VALUE_OPTIONAL),
                            'visible' => new external_value(PARAM_INT, 'visible', VALUE_OPTIONAL),
                            'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL),
                            'groupingid' => new external_value(PARAM_INT, 'grouping id', VALUE_OPTIONAL),
                        ), 'Glossaries'
                    )
                ),
                'warnings' => new external_warnings(),
            )
        );
    }
}
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	}