Automatically generated installer lang files
[moodle.git] / notes / externallib.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/>.
18 /**
19  * External notes API
20  *
21  * @package    core_notes
22  * @category   external
23  * @copyright  2011 Jerome Mouneyrac
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 require_once("$CFG->libdir/externallib.php");
29 /**
30  * Notes external functions
31  *
32  * @package    core_notes
33  * @category   external
34  * @copyright  2011 Jerome Mouneyrac
35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  * @since Moodle 2.2
37  */
38 class core_notes_external extends external_api {
40     /**
41      * Returns description of method parameters
42      *
43      * @return external_function_parameters
44      * @since Moodle 2.2
45      */
46     public static function create_notes_parameters() {
47         return new external_function_parameters(
48             array(
49                 'notes' => new external_multiple_structure(
50                     new external_single_structure(
51                         array(
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_value(PARAM_ALPHANUMEXT, // For backward compatibility it can not be PARAM_INT, so we don't use external_format_value.
57                                     'text format (' . FORMAT_HTML . ' = HTML, '
58                                     . FORMAT_MOODLE . ' = MOODLE, '
59                                     . FORMAT_PLAIN . ' = PLAIN or '
60                                     . FORMAT_MARKDOWN . ' = MARKDOWN)', VALUE_DEFAULT, FORMAT_HTML),
61                             '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),
62                         )
63                     )
64                 )
65             )
66         );
67     }
69     /**
70      * Create notes about some users
71      * Note: code should be matching the /notes/edit.php checks
72      * and the /user/addnote.php checks. (they are similar cheks)
73      *
74      * @param array $notes  An array of notes to create.
75      * @return array (success infos and fail infos)
76      * @since Moodle 2.2
77      */
78     public static function create_notes($notes = array()) {
79         global $CFG, $DB;
80         require_once($CFG->dirroot . "/notes/lib.php");
82         $params = self::validate_parameters(self::create_notes_parameters(), array('notes' => $notes));
84         //check if note system is enabled
85         if (!$CFG->enablenotes) {
86             throw new moodle_exception('notesdisabled', 'notes');
87         }
89         //retrieve all courses
90         $courseids = array();
91         foreach($params['notes'] as $note) {
92             $courseids[] = $note['courseid'];
93         }
94         $courses = $DB->get_records_list("course", "id", $courseids);
96         //retrieve all users of the notes
97         $userids = array();
98         foreach($params['notes'] as $note) {
99             $userids[] = $note['userid'];
100         }
101         list($sqluserids, $sqlparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'userid_');
102         $users = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
104         $resultnotes = array();
105         foreach ($params['notes'] as $note) {
107             $success = true;
108             $resultnote = array(); //the infos about the success of the operation
110             //check the course exists
111             if (empty($courses[$note['courseid']])) {
112                 $success = false;
113                 $errormessage = get_string('invalidcourseid', 'error');
114             } else {
115                 // Ensure the current user is allowed to run this function
116                 $context = get_context_instance(CONTEXT_COURSE, $note['courseid']);
117                 self::validate_context($context);
118                 require_capability('moodle/notes:manage', $context);
119             }
121             //check the user exists
122             if (empty($users[$note['userid']])) {
123                 $success = false;
124                 $errormessage = get_string('invaliduserid', 'notes', $note['userid']);
125             }
127             //build the resultnote
128             if (isset($note['clientnoteid'])) {
129                 $resultnote['clientnoteid'] = $note['clientnoteid'];
130             }
132             if ($success) {
133                 //now we can create the note
134                 $dbnote = new stdClass;
135                 $dbnote->courseid = $note['courseid'];
136                 $dbnote->userid = $note['userid'];
137                 // Need to support 'html' and 'text' format values for backward compatibility.
138                 switch (strtolower($note['format'])) {
139                     case 'html':
140                         $textformat = FORMAT_HTML;
141                         break;
142                     case 'text':
143                         $textformat = FORMAT_PLAIN;
144                     default:
145                         $textformat = external_validate_format($note['format']);
146                         break;
147                 }
148                 $dbnote->content = $note['text'];
149                 $dbnote->format = $textformat;
151                 //get the state ('personal', 'course', 'site')
152                 switch ($note['publishstate']) {
153                     case 'personal':
154                         $dbnote->publishstate = NOTES_STATE_DRAFT;
155                         break;
156                     case 'course':
157                         $dbnote->publishstate = NOTES_STATE_PUBLIC;
158                         break;
159                     case 'site':
160                         $dbnote->publishstate = NOTES_STATE_SITE;
161                         $dbnote->courseid = SITEID;
162                         break;
163                     default:
164                         break;
165                 }
167                 //TODO MDL-31119 performance improvement - if possible create a bulk functions for saving multiple notes at once
168                 if (note_save($dbnote)) { //note_save attribut an id in case of success
169                     add_to_log($dbnote->courseid, 'notes', 'add',
170                             'index.php?course='.$dbnote->courseid.'&amp;user='.$dbnote->userid
171                             . '#note-' . $dbnote->id , 'add note');
172                     $success = $dbnote->id;
173                 }
175                 $resultnote['noteid'] = $success;
176             } else {
177                 // WARNINGS: for backward compatibility we return this errormessage.
178                 //          We should have thrown exceptions as these errors prevent results to be returned.
179                 // See http://docs.moodle.org/dev/Errors_handling_in_web_services#When_to_send_a_warning_on_the_server_side .
180                 $resultnote['noteid'] = -1;
181                 $resultnote['errormessage'] = $errormessage;
182             }
184             $resultnotes[] = $resultnote;
185         }
187         return $resultnotes;
188     }
190     /**
191      * Returns description of method result value
192      *
193      * @return external_description
194      * @since Moodle 2.2
195      */
196     public static function create_notes_returns() {
197         return new external_multiple_structure(
198             new external_single_structure(
199                 array(
200                     'clientnoteid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the note', VALUE_OPTIONAL),
201                     'noteid' => new external_value(PARAM_INT, 'test this to know if it success:  id of the created note when successed, -1 when failed'),
202                     'errormessage' => new external_value(PARAM_TEXT, 'error message - if failed', VALUE_OPTIONAL)
203                 )
204             )
205         );
206     }
210 /**
211  * Deprecated notes external functions
212  *
213  * @package    core_notes
214  * @copyright  2011 Jerome Mouneyrac
215  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
216  * @since Moodle 2.1
217  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
218  * @todo MDL-31194 This will be deleted in Moodle 2.5.
219  * @see core_notes_external
220  */
221 class moodle_notes_external extends external_api {
223     /**
224      * Returns description of method parameters
225      *
226      * @return external_function_parameters
227      * @since Moodle 2.1
228      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
229      * @todo MDL-31194 This will be deleted in Moodle 2.5.
230      * @see core_notes_external::create_notes_parameters()
231      */
232     public static function create_notes_parameters() {
233         return core_notes_external::create_notes_parameters();
234     }
236     /**
237      * Create notes about some users
238      * Note: code should be matching the /notes/edit.php checks
239      * and the /user/addnote.php checks. (they are similar cheks)
240      *
241      * @param array $notes  An array of notes to create.
242      * @return array (success infos and fail infos)
243      * @since Moodle 2.1
244      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
245      * @todo MDL-31194 This will be deleted in Moodle 2.5.
246      * @see core_notes_external::create_notes()
247      */
248     public static function create_notes($notes = array()) {
249         return core_notes_external::create_notes($notes);
250     }
252     /**
253      * Returns description of method result value
254      *
255      * @return external_description
256      * @since Moodle 2.1
257      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
258      * @todo MDL-31194 This will be deleted in Moodle 2.5.
259      * @see core_notes_external::create_notes_returns()
260      */
261     public static function create_notes_returns() {
262         return core_notes_external::create_notes_returns();
263     }