notes/externallib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * External notes API
  20  *
  21  * @package    moodlecore
  22  * @subpackage notes
  23  * @copyright  2011 Moodle Pty Ltd (http://moodle.com)
  24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26 require_once("$CFG->libdir/externallib.php");
  27
  28 /**
  29  * Notes functions
  30  */
  31 class core_notes_external extends external_api {
  32
  33     /**
  34      * Returns description of method parameters
  35      * @return external_function_parameters
  36      */
  37     public static function create_notes_parameters() {
  38         return new external_function_parameters(
  39             array(
  40                 'notes' => new external_multiple_structure(
  41                     new external_single_structure(
  42                         array(
  43                             'userid' => new external_value(PARAM_INT, 'id of the user the note is about'),
  44                             'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\''),
  45                             '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)'),
  46                             'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML'),
  47                             'format' => new external_value(PARAM_ALPHA, '\'text\' or \'html\'', VALUE_DEFAULT, 'text'),
  48                             '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),
  49                         )
  50                     )
  51                 )
  52             )
  53         );
  54     }
  55
  56     /**
  57      * Create notes about some users
  58      * Note: code should be matching the /notes/edit.php checks
  59      * and the /user/addnote.php checks. (they are similar cheks)
  60      * @param array $notes  An array of notes to create.
  61      * @return array (success infos and fail infos)
  62      */
  63     public static function create_notes($notes = array()) {
  64         global $CFG, $DB;
  65         require_once($CFG->dirroot . "/notes/lib.php");
  66
  67         $params = self::validate_parameters(self::create_notes_parameters(), array('notes' => $notes));
  68
  69         //check if note system is enabled
  70         if (!$CFG->enablenotes) {
  71             throw new moodle_exception('notesdisabled', 'notes');
  72         }
  73
  74         //retrieve all courses
  75         $courseids = array();
  76         foreach($params['notes'] as $note) {
  77             $courseids[] = $note['courseid'];
  78         }
  79         $courses = $DB->get_records_list("course", "id", $courseids);
  80
  81         //retrieve all users of the notes
  82         $userids = array();
  83         foreach($params['notes'] as $note) {
  84             $userids[] = $note['userid'];
  85         }
  86         list($sqluserids, $sqlparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'userid_');
  87         $users = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
  88
  89         $resultnotes = array();
  90         foreach ($params['notes'] as $note) {
  91
  92             $success = true;
  93             $resultnote = array(); //the infos about the success of the operation
  94
  95             //check the course exists
  96             if (empty($courses[$note['courseid']])) {
  97                 $success = false;
  98                 $errormessage = get_string('invalidcourseid', 'notes', $note['courseid']);
  99             } else {
 100                 // Ensure the current user is allowed to run this function
 101                 $context = get_context_instance(CONTEXT_COURSE, $note['courseid']);
 102                 self::validate_context($context);
 103                 require_capability('moodle/notes:manage', $context);
 104             }
 105
 106             //check the user exists
 107             if (empty($users[$note['userid']])) {
 108                 $success = false;
 109                 $errormessage = get_string('invaliduserid', 'notes', $note['userid']);
 110             }
 111
 112             //build the resultnote
 113             if (isset($note['clientnoteid'])) {
 114                 $resultnote['clientnoteid'] = $note['clientnoteid'];
 115             }
 116
 117             if ($success) {
 118                 //now we can create the note
 119                 $dbnote = new stdClass;
 120                 $dbnote->courseid = $note['courseid'];
 121                 $dbnote->userid = $note['userid'];
 122                 //clean param text and set format accordingly
 123                 switch (strtolower($note['format'])) {
 124                     case 'html':
 125                         $dbnote->content = clean_param($note['text'], PARAM_CLEANHTML);
 126                         $dbnote->format = FORMAT_HTML;
 127                         break;
 128                     case 'text':
 129                     default:
 130                         $dbnote->content = clean_param($note['text'], PARAM_TEXT);
 131                         $dbnote->format = FORMAT_PLAIN;
 132                         break;
 133                 }
 134
 135                 //get the state ('personal', 'course', 'site')
 136                 switch ($note['publishstate']) {
 137                     case 'personal':
 138                         $dbnote->publishstate = NOTES_STATE_DRAFT;
 139                         break;
 140                     case 'course':
 141                         $dbnote->publishstate = NOTES_STATE_PUBLIC;
 142                         break;
 143                     case 'site':
 144                         $dbnote->publishstate = NOTES_STATE_SITE;
 145                         $dbnote->courseid = SITEID;
 146                         break;
 147                     default:
 148                         break;
 149                 }
 150
 151                 //TODO: performance improvement - if possible create a bulk functions for saving multiple notes at once
 152                 if (note_save($dbnote)) { //note_save attribut an id in case of success
 153                     add_to_log($dbnote->courseid, 'notes', 'add',
 154                             'index.php?course='.$dbnote->courseid.'&amp;user='.$dbnote->userid
 155                             . '#note-' . $dbnote->id , 'add note');
 156                     $success = $dbnote->id;
 157                 }
 158
 159                 $resultnote['noteid'] = $success;
 160             } else {
 161                 $resultnote['noteid'] = -1;
 162                 $resultnote['errormessage'] = $errormessage;
 163             }
 164
 165             $resultnotes[] = $resultnote;
 166         }
 167
 168         return $resultnotes;
 169     }
 170
 171     /**
 172      * Returns description of method result value
 173      * @return external_description
 174      */
 175     public static function create_notes_returns() {
 176         return new external_multiple_structure(
 177             new external_single_structure(
 178                 array(
 179                     'clientnoteid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the note', VALUE_OPTIONAL),
 180                     'noteid' => new external_value(PARAM_INT, 'test this to know if it success:  id of the created note when successed, -1 when failed'),
 181                     'errormessage' => new external_value(PARAM_TEXT, 'error message - if failed', VALUE_OPTIONAL)
 182                 )
 183             )
 184         );
 185     }
 186
 187 }
 188
 189 /**
 190  * Deprecated notes functions
 191  * @deprecated since Moodle 2.2 please use core_notes_external instead
 192  */
 193 class moodle_notes_external extends external_api {
 194
 195     /**
 196      * Returns description of method parameters
 197      * @deprecated since Moodle 2.2 please use core_notes_external::create_notes_parameters instead
 198      * @return external_function_parameters
 199      */
 200     public static function create_notes_parameters() {
 201         return core_notes_external::create_notes_parameters();
 202     }
 203
 204     /**
 205      * Create notes about some users
 206      * Note: code should be matching the /notes/edit.php checks
 207      * and the /user/addnote.php checks. (they are similar cheks)
 208      * @deprecated since Moodle 2.2 please use core_notes_external::create_notes instead
 209      * @param array $notes  An array of notes to create.
 210      * @return array (success infos and fail infos)
 211      */
 212     public static function create_notes($notes = array()) {
 213         return core_notes_external::create_notes($notes);
 214     }
 215
 216     /**
 217      * Returns description of method result value
 218      * @deprecated since Moodle 2.2 please use core_notes_external::create_notes_returns instead
 219      * @return external_description
 220      */
 221     public static function create_notes_returns() {
 222         return core_notes_external::create_notes_returns();
 223     }
 224
 225 }