2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
23 * @copyright 2011 Jerome Mouneyrac
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 require_once("$CFG->libdir/externallib.php");
30 * Notes external functions
34 * @copyright 2011 Jerome Mouneyrac
35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38 class core_notes_external
extends external_api
{
41 * Returns description of method parameters
43 * @return external_function_parameters
46 public static function create_notes_parameters() {
47 return new external_function_parameters(
49 'notes' => new external_multiple_structure(
50 new external_single_structure(
52 'userid' => new external_value(PARAM_INT
, 'id of the user the note is about'),
53 'publishstate' => new external_value(PARAM_ALPHA
, '\'personal\', \'course\' or \'site\''),
54 'courseid' => new external_value(PARAM_INT
, 'course id of the note (in Moodle a note can only be created into a course, even for site and personal notes)'),
55 'text' => new external_value(PARAM_RAW
, 'the text of the message - text or HTML'),
56 'format' => new external_format_value('text', VALUE_DEFAULT
),
57 'clientnoteid' => new external_value(PARAM_ALPHANUMEXT
, 'your own client id for the note. If this id is provided, the fail message id will be returned to you', VALUE_OPTIONAL
),
66 * Create notes about some users
67 * Note: code should be matching the /notes/edit.php checks
68 * and the /user/addnote.php checks. (they are similar cheks)
70 * @param array $notes An array of notes to create.
71 * @return array (success infos and fail infos)
74 public static function create_notes($notes = array()) {
76 require_once($CFG->dirroot
. "/notes/lib.php");
78 $params = self
::validate_parameters(self
::create_notes_parameters(), array('notes' => $notes));
80 // Check if note system is enabled.
81 if (!$CFG->enablenotes
) {
82 throw new moodle_exception('notesdisabled', 'notes');
85 // Retrieve all courses.
87 foreach ($params['notes'] as $note) {
88 $courseids[] = $note['courseid'];
90 $courses = $DB->get_records_list("course", "id", $courseids);
92 // Retrieve all users of the notes.
94 foreach ($params['notes'] as $note) {
95 $userids[] = $note['userid'];
97 list($sqluserids, $sqlparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED
, 'userid_');
98 $users = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
100 $resultnotes = array();
101 foreach ($params['notes'] as $note) {
104 $resultnote = array(); // The infos about the success of the operation.
106 // Check the course exists.
107 if (empty($courses[$note['courseid']])) {
109 $errormessage = get_string('invalidcourseid', 'error');
111 // Ensure the current user is allowed to run this function.
112 $context = context_course
::instance($note['courseid']);
113 self
::validate_context($context);
114 require_capability('moodle/notes:manage', $context);
117 // Check the user exists.
118 if (empty($users[$note['userid']])) {
120 $errormessage = get_string('invaliduserid', 'notes', $note['userid']);
123 // Build the resultnote.
124 if (isset($note['clientnoteid'])) {
125 $resultnote['clientnoteid'] = $note['clientnoteid'];
129 // Now we can create the note.
130 $dbnote = new stdClass
;
131 $dbnote->courseid
= $note['courseid'];
132 $dbnote->userid
= $note['userid'];
133 // Need to support 'html' and 'text' format values for backward compatibility.
134 switch (strtolower($note['format'])) {
136 $textformat = FORMAT_HTML
;
139 $textformat = FORMAT_PLAIN
;
141 $textformat = external_validate_format($note['format']);
144 $dbnote->content
= $note['text'];
145 $dbnote->format
= $textformat;
147 // Get the state ('personal', 'course', 'site').
148 switch ($note['publishstate']) {
150 $dbnote->publishstate
= NOTES_STATE_DRAFT
;
153 $dbnote->publishstate
= NOTES_STATE_PUBLIC
;
156 $dbnote->publishstate
= NOTES_STATE_SITE
;
157 $dbnote->courseid
= SITEID
;
163 // TODO MDL-31119 performance improvement - if possible create a bulk functions for saving multiple notes at once
164 if (note_save($dbnote)) { // Note_save attribut an id in case of success.
165 $success = $dbnote->id
;
168 $resultnote['noteid'] = $success;
170 // WARNINGS: for backward compatibility we return this errormessage.
171 // We should have thrown exceptions as these errors prevent results to be returned.
172 // See http://docs.moodle.org/dev/Errors_handling_in_web_services#When_to_send_a_warning_on_the_server_side .
173 $resultnote['noteid'] = -1;
174 $resultnote['errormessage'] = $errormessage;
177 $resultnotes[] = $resultnote;
184 * Returns description of method result value
186 * @return external_description
189 public static function create_notes_returns() {
190 return new external_multiple_structure(
191 new external_single_structure(
193 'clientnoteid' => new external_value(PARAM_ALPHANUMEXT
, 'your own id for the note', VALUE_OPTIONAL
),
194 'noteid' => new external_value(PARAM_INT
, 'ID of the created note when successful, -1 when failed'),
195 'errormessage' => new external_value(PARAM_TEXT
, 'error message - if failed', VALUE_OPTIONAL
)
202 * Returns description of delete_notes parameters
204 * @return external_function_parameters
207 public static function delete_notes_parameters() {
208 return new external_function_parameters(
210 "notes"=> new external_multiple_structure(
211 new external_value(PARAM_INT
, 'ID of the note to be deleted'), 'Array of Note Ids to be deleted.'
218 * Delete notes about users.
219 * Note: code should be matching the /notes/delete.php checks.
221 * @param array $notes An array of ids for the notes to delete.
225 public static function delete_notes($notes = array()) {
227 require_once($CFG->dirroot
. "/notes/lib.php");
229 $params = self
::validate_parameters(self
::delete_notes_parameters(), array('notes' => $notes));
231 // Check if note system is enabled.
232 if (!$CFG->enablenotes
) {
233 throw new moodle_exception('notesdisabled', 'notes');
236 foreach ($params['notes'] as $noteid) {
237 $note = note_load($noteid);
238 if (isset($note->id
)) {
239 // Ensure the current user is allowed to run this function.
240 $context = context_course
::instance($note->courseid
);
241 self
::validate_context($context);
242 require_capability('moodle/notes:manage', $context);
245 $warnings[] = array('item'=>'note', 'itemid'=>$noteid, 'warningcode'=>'badid', 'message'=>'Note does not exist');
252 * Returns description of delete_notes result value.
254 * @return external_description
257 public static function delete_notes_returns() {
258 return new external_warnings('item is always \'note\'',
259 'When errorcode is savedfailed the note could not be modified.' .
260 'When errorcode is badparam, an incorrect parameter was provided.' .
261 'When errorcode is badid, the note does not exist',
262 'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)');
267 * Returns description of get_notes parameters.
269 * @return external_function_parameters
272 public static function get_notes_parameters() {
273 return new external_function_parameters(
275 "notes"=> new external_multiple_structure(
276 new external_value(PARAM_INT
, 'ID of the note to be retrieved'), 'Array of Note Ids to be retrieved.'
283 * Get notes about users.
285 * @param array $notes An array of ids for the notes to retrieve.
289 public static function get_notes($notes) {
291 require_once($CFG->dirroot
. "/notes/lib.php");
293 $params = self
::validate_parameters(self
::get_notes_parameters(), array('notes' => $notes));
294 // Check if note system is enabled.
295 if (!$CFG->enablenotes
) {
296 throw new moodle_exception('notesdisabled', 'notes');
298 $resultnotes = array();
299 foreach ($params['notes'] as $noteid) {
300 $resultnote = array();
302 $note = note_load($noteid);
303 if (isset($note->id
)) {
304 // Ensure the current user is allowed to run this function.
305 $context = context_course
::instance($note->courseid
);
306 self
::validate_context($context);
307 require_capability('moodle/notes:view', $context);
308 list($gotnote['text'], $gotnote['format']) = external_format_text($note->content
,
314 $gotnote['noteid'] = $note->id
;
315 $gotnote['userid'] = $note->userid
;
316 $gotnote['publishstate'] = $note->publishstate
;
317 $gotnote['courseid'] = $note->courseid
;
318 $resultnotes["notes"][] = $gotnote;
320 $resultnotes["warnings"][] = array('item' => 'note',
322 'warningcode' => 'badid',
323 'message' => 'Note does not exist');
330 * Returns description of get_notes result value.
332 * @return external_description
335 public static function get_notes_returns() {
336 return new external_single_structure(
338 'notes' => new external_multiple_structure(
339 new external_single_structure(
341 'noteid' => new external_value(PARAM_INT
, 'id of the note', VALUE_OPTIONAL
),
342 'userid' => new external_value(PARAM_INT
, 'id of the user the note is about', VALUE_OPTIONAL
),
343 'publishstate' => new external_value(PARAM_ALPHA
, '\'personal\', \'course\' or \'site\'', VALUE_OPTIONAL
),
344 'courseid' => new external_value(PARAM_INT
, 'course id of the note', VALUE_OPTIONAL
),
345 'text' => new external_value(PARAM_RAW
, 'the text of the message - text or HTML', VALUE_OPTIONAL
),
346 'format' => new external_format_value('text', VALUE_OPTIONAL
),
350 'warnings' => new external_warnings('item is always \'note\'',
351 'When errorcode is savedfailed the note could not be modified.' .
352 'When errorcode is badparam, an incorrect parameter was provided.' .
353 'When errorcode is badid, the note does not exist',
354 'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)')
360 * Returns description of update_notes parameters.
362 * @return external_function_parameters
365 public static function update_notes_parameters() {
366 return new external_function_parameters(
368 'notes' => new external_multiple_structure(
369 new external_single_structure(
371 'id' => new external_value(PARAM_INT
, 'id of the note'),
372 'publishstate' => new external_value(PARAM_ALPHA
, '\'personal\', \'course\' or \'site\''),
373 'text' => new external_value(PARAM_RAW
, 'the text of the message - text or HTML'),
374 'format' => new external_format_value('text', VALUE_DEFAULT
),
376 ), "Array of Notes", VALUE_DEFAULT
, array()
383 * Update notes about users.
385 * @param array $notes An array of ids for the notes to update.
386 * @return array fail infos.
389 public static function update_notes($notes = array()) {
391 require_once($CFG->dirroot
. "/notes/lib.php");
393 $params = self
::validate_parameters(self
::update_notes_parameters(), array('notes' => $notes));
395 // Check if note system is enabled.
396 if (!$CFG->enablenotes
) {
397 throw new moodle_exception('notesdisabled', 'notes');
401 foreach ($params['notes'] as $note) {
402 $notedetails = note_load($note['id']);
403 if (isset($notedetails->id
)) {
404 // Ensure the current user is allowed to run this function.
405 $context = context_course
::instance($notedetails->courseid
);
406 self
::validate_context($context);
407 require_capability('moodle/notes:manage', $context);
409 $dbnote = new stdClass
;
410 $dbnote->id
= $note['id'];
411 $dbnote->content
= $note['text'];
412 $dbnote->format
= external_validate_format($note['format']);
413 // Get the state ('personal', 'course', 'site').
414 switch ($note['publishstate']) {
416 $dbnote->publishstate
= NOTES_STATE_DRAFT
;
419 $dbnote->publishstate
= NOTES_STATE_PUBLIC
;
422 $dbnote->publishstate
= NOTES_STATE_SITE
;
423 $dbnote->courseid
= SITEID
;
426 $warnings[] = array('item' => 'note',
427 'itemid' => $note["id"],
428 'warningcode' => 'badparam',
429 'message' => 'Provided publishstate incorrect');
432 if (!note_save($dbnote)) {
433 $warnings[] = array('item' => 'note',
434 'itemid' => $note["id"],
435 'warningcode' => 'savedfailed',
436 'message' => 'Note could not be modified');
439 $warnings[] = array('item' => 'note',
440 'itemid' => $note["id"],
441 'warningcode' => 'badid',
442 'message' => 'Note does not exist');
449 * Returns description of update_notes result value.
451 * @return external_description
454 public static function update_notes_returns() {
455 return new external_warnings('item is always \'note\'',
456 'When errorcode is savedfailed the note could not be modified.' .
457 'When errorcode is badparam, an incorrect parameter was provided.' .
458 'When errorcode is badid, the note does not exist',
459 'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)');
464 * Deprecated notes external functions
466 * @package core_notes
467 * @copyright 2011 Jerome Mouneyrac
468 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
470 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
471 * @see core_notes_external
473 class moodle_notes_external
extends external_api
{
476 * Returns description of method parameters
478 * @return external_function_parameters
480 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
481 * @see core_notes_external::create_notes_parameters()
483 public static function create_notes_parameters() {
484 return core_notes_external
::create_notes_parameters();
488 * Create notes about some users
489 * Note: code should be matching the /notes/edit.php checks
490 * and the /user/addnote.php checks. (they are similar cheks)
492 * @param array $notes An array of notes to create.
493 * @return array (success infos and fail infos)
495 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
496 * @see core_notes_external::create_notes()
498 public static function create_notes($notes = array()) {
499 return core_notes_external
::create_notes($notes);
503 * Returns description of method result value
505 * @return external_description
507 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
508 * @see core_notes_external::create_notes_returns()
510 public static function create_notes_returns() {
511 return core_notes_external
::create_notes_returns();