notes/lib.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/>.
  16
  17 /**
  18  * Library of functions and constants for notes
  19  *
  20  * @package    core_notes
  21  * @copyright  2007 onwards Yu Zhang
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 /**
  26  * Constants for states.
  27  */
  28 define('NOTES_STATE_DRAFT', 'draft');
  29 define('NOTES_STATE_PUBLIC', 'public');
  30 define('NOTES_STATE_SITE', 'site');
  31
  32 /**
  33  * Constants for note parts (flags used by note_print and note_print_list).
  34  */
  35 define('NOTES_SHOW_FULL', 0x07);
  36 define('NOTES_SHOW_HEAD', 0x02);
  37 define('NOTES_SHOW_BODY', 0x01);
  38 define('NOTES_SHOW_FOOT', 0x04);
  39
  40 /**
  41  * Retrieves a list of note objects with specific atributes.
  42  *
  43  * @param int    $courseid id of the course in which the notes were posted (0 means any)
  44  * @param int    $userid id of the user to which the notes refer (0 means any)
  45  * @param string $state state of the notes (i.e. draft, public, site) ('' means any)
  46  * @param int    $author id of the user who modified the note last time (0 means any)
  47  * @param string $order an order to sort the results in
  48  * @param int    $limitfrom number of records to skip (offset)
  49  * @param int    $limitnum number of records to fetch
  50  * @return array of note objects
  51  */
  52 function note_list($courseid=0, $userid=0, $state = '', $author = 0, $order='lastmodified DESC', $limitfrom=0, $limitnum=0) {
  53     global $DB;
  54
  55     // Setup filters.
  56     $selects = array();
  57     $params = array();
  58     if ($courseid) {
  59         $selects[] = 'courseid=?';
  60         $params[]  = $courseid;
  61     }
  62     if ($userid) {
  63         $selects[] = 'userid=?';
  64         $params[]  = $userid;
  65     }
  66     if ($author) {
  67         $selects[] = 'usermodified=?';
  68         $params[]  = $author;
  69     }
  70     if ($state) {
  71         $selects[] = 'publishstate=?';
  72         $params[]  = $state;
  73     }
  74     $selects[] = "module=?";
  75     $params[]  = 'notes';
  76
  77     $select = implode(' AND ', $selects);
  78     $fields = 'id,courseid,userid,content,format,created,lastmodified,usermodified,publishstate';
  79
  80     return $DB->get_records_select('post', $select, $params, $order, $fields, $limitfrom, $limitnum);
  81 }
  82
  83 /**
  84  * Retrieves a note object based on its id.
  85  *
  86  * @param int $noteid ID of the note to retrieve
  87  * @return stdClass object
  88  */
  89 function note_load($noteid) {
  90     global $DB;
  91
  92     $fields = 'id,courseid,userid,content,format,created,lastmodified,usermodified,publishstate';
  93     return $DB->get_record('post', array('id' => $noteid, 'module' => 'notes'), $fields);
  94 }
  95
  96 /**
  97  * Saves a note object. The note object is passed by reference and its fields (i.e. id)
  98  * might change during the save.
  99  *
 100  * @param stdClass   $note object to save
 101  * @return boolean true if the object was saved; false otherwise
 102  */
 103 function note_save(&$note) {
 104     global $USER, $DB;
 105
 106     // Setup & clean fields.
 107     $note->module       = 'notes';
 108     $note->lastmodified = time();
 109     $note->usermodified = $USER->id;
 110     if (empty($note->format)) {
 111         $note->format = FORMAT_PLAIN;
 112     }
 113     if (empty($note->publishstate)) {
 114         $note->publishstate = NOTES_STATE_PUBLIC;
 115     }
 116
 117     if (empty(trim($note->content))) {
 118         // Don't save empty notes.
 119         return false;
 120     }
 121     // Save data.
 122     if (empty($note->id)) {
 123         // Insert new note.
 124         $note->created = $note->lastmodified;
 125         $id = $DB->insert_record('post', $note);
 126         $note = note_load($id);
 127
 128         // Trigger event.
 129         $event = \core\event\note_created::create(array(
 130             'objectid' => $note->id,
 131             'courseid' => $note->courseid,
 132             'relateduserid' => $note->userid,
 133             'userid' => $note->usermodified,
 134             'context' => context_course::instance($note->courseid),
 135             'other' => array('publishstate' => $note->publishstate)
 136         ));
 137         $event->trigger();
 138     } else {
 139         // Update old note.
 140         $DB->update_record('post', $note);
 141         $note = note_load($note->id);
 142
 143         // Trigger event.
 144         $event = \core\event\note_updated::create(array(
 145             'objectid' => $note->id,
 146             'courseid' => $note->courseid,
 147             'relateduserid' => $note->userid,
 148             'userid' => $note->usermodified,
 149             'context' => context_course::instance($note->courseid),
 150             'other' => array('publishstate' => $note->publishstate)
 151         ));
 152         $event->trigger();
 153     }
 154     unset($note->module);
 155     return true;
 156 }
 157
 158 /**
 159  * Deletes a note object based on its id.
 160  *
 161  * @param int|object    $note id of the note to delete, or a note object which is to be deleted.
 162  * @return boolean true always
 163  */
 164 function note_delete($note) {
 165     global $DB;
 166     if (is_int($note)) {
 167         $noteid = $note;
 168     } else {
 169         $noteid = $note->id;
 170     }
 171     // Get the full record, note_load doesn't return everything.
 172     $note = $DB->get_record('post', array('id' => $noteid), '*', MUST_EXIST);
 173     $return = $DB->delete_records('post', array('id' => $note->id, 'module' => 'notes'));
 174
 175     // Trigger event.
 176     $event = \core\event\note_deleted::create(array(
 177         'objectid' => $note->id,
 178         'courseid' => $note->courseid,
 179         'relateduserid' => $note->userid,
 180         'userid' => $note->usermodified,
 181         'context' => context_course::instance($note->courseid),
 182         'other' => array('publishstate' => $note->publishstate)
 183     ));
 184     $event->add_record_snapshot('post', $note);
 185     $event->trigger();
 186
 187     return $return;
 188 }
 189
 190 /**
 191  * Converts a state value to its corespondent name
 192  *
 193  * @param string  $state state value to convert
 194  * @return string corespondent state name
 195  */
 196 function note_get_state_name($state) {
 197     // Cache state names.
 198     static $states;
 199     if (empty($states)) {
 200         $states = note_get_state_names();
 201     }
 202     if (isset($states[$state])) {
 203         return $states[$state];
 204     } else {
 205         return null;
 206     }
 207 }
 208
 209 /**
 210  * Returns an array of mappings from state values to state names
 211  *
 212  * @return array of mappings
 213  */
 214 function note_get_state_names() {
 215     return array(
 216         NOTES_STATE_DRAFT => get_string('personal', 'notes'),
 217         NOTES_STATE_PUBLIC => get_string('course', 'notes'),
 218         NOTES_STATE_SITE => get_string('site', 'notes'),
 219     );
 220 }
 221
 222 /**
 223  * Prints a note object
 224  *
 225  * @param note  $note the note object to print
 226  * @param int   $detail OR-ed NOTES_SHOW_xyz flags that specify which note parts to print
 227  */
 228 function note_print($note, $detail = NOTES_SHOW_FULL) {
 229     global $CFG, $USER, $DB, $OUTPUT;
 230
 231     if (!$user = $DB->get_record('user', array('id' => $note->userid))) {
 232         debugging("User $note->userid not found");
 233         return;
 234     }
 235     if (!$author = $DB->get_record('user', array('id' => $note->usermodified))) {
 236         debugging("User $note->usermodified not found");
 237         return;
 238     }
 239     $context = context_course::instance($note->courseid);
 240     $systemcontext = context_system::instance();
 241
 242     $authoring = new stdClass();
 243     $authoring->name = '<a href="' . $CFG->wwwroot . '/user/view.php?id=' . $author->id .
 244         '&amp;course='.$note->courseid . '">' . fullname($author) . '</a>';
 245     $authoring->date = userdate($note->lastmodified);
 246
 247     echo '<div class="notepost '. $note->publishstate . 'notepost' .
 248         ($note->usermodified == $USER->id ? ' ownnotepost' : '')  .
 249         '" id="note-' . $note->id . '">';
 250
 251     // Print note head (e.g. author, user refering to, etc).
 252     if ($detail & NOTES_SHOW_HEAD) {
 253         echo '<div class="header">';
 254         echo '<div class="user">';
 255         echo $OUTPUT->user_picture($user, array('courseid' => $note->courseid));
 256         echo fullname($user) . '</div>';
 257         echo '<div class="info">' .
 258             get_string('bynameondate', 'notes', $authoring) .
 259             ' (' . get_string('created', 'notes') . ': ' . userdate($note->created) . ')</div>';
 260         echo '</div>';
 261     }
 262
 263     // Print note content.
 264     if ($detail & NOTES_SHOW_BODY) {
 265         echo '<div class="content">';
 266         echo format_text($note->content, $note->format, array('overflowdiv' => true));
 267         echo '</div>';
 268     }
 269
 270     // Print note options (e.g. delete, edit).
 271     if ($detail & NOTES_SHOW_FOOT) {
 272         if (has_capability('moodle/notes:manage', $systemcontext) && $note->publishstate == NOTES_STATE_SITE ||
 273             has_capability('moodle/notes:manage', $context) &&
 274             ($note->publishstate == NOTES_STATE_PUBLIC || $note->usermodified == $USER->id)) {
 275             echo '<div class="footer"><p>';
 276             echo '<a href="' . $CFG->wwwroot . '/notes/edit.php?id=' . $note->id. '">' . get_string('edit') . '</a> | ';
 277             echo '<a href="' . $CFG->wwwroot . '/notes/delete.php?id=' . $note->id. '">' . get_string('delete') . '</a>';
 278             echo '</p></div>';
 279         }
 280     }
 281     echo '</div>';
 282 }
 283
 284 /**
 285  * Prints a list of note objects
 286  *
 287  * @param array  $notes array of note objects to print
 288  * @param int   $detail OR-ed NOTES_SHOW_xyz flags that specify which note parts to print
 289  */
 290 function note_print_list($notes, $detail = NOTES_SHOW_FULL) {
 291
 292     echo '<div class="notelist">';
 293     foreach ($notes as $note) {
 294         note_print($note, $detail);
 295     }
 296     echo '</div>';
 297 }
 298
 299 /**
 300  * Retrieves and prints a list of note objects with specific atributes.
 301  *
 302  * @param string  $header HTML to print above the list
 303  * @param int     $addcourseid id of the course for the add notes link (0 hide link)
 304  * @param boolean $viewnotes true if the notes should be printed; false otherwise (print notesnotvisible string)
 305  * @param int     $courseid id of the course in which the notes were posted (0 means any)
 306  * @param int     $userid id of the user to which the notes refer (0 means any)
 307  * @param string  $state state of the notes (i.e. draft, public, site) ('' means any)
 308  * @param int     $author id of the user who modified the note last time (0 means any)
 309  */
 310 function note_print_notes($header, $addcourseid = 0, $viewnotes = true, $courseid = 0, $userid = 0, $state = '', $author = 0) {
 311     global $CFG;
 312
 313     if ($header) {
 314         echo '<h3 class="notestitle">' . $header . '</h3>';
 315         echo '<div class="notesgroup">';
 316     }
 317     if ($addcourseid) {
 318         if ($userid) {
 319             echo '<p><a href="' . $CFG->wwwroot . '/notes/edit.php?courseid=' . $addcourseid . '&amp;userid=' . $userid .
 320                 '&amp;publishstate=' . $state . '">' . get_string('addnewnote', 'notes') . '</a></p>';
 321         } else {
 322             echo '<p><a href="' . $CFG->wwwroot . '/user/index.php?id=' . $addcourseid. '">' .
 323                 get_string('addnewnoteselect', 'notes') . '</a></p>';
 324         }
 325     }
 326     if ($viewnotes) {
 327         $notes = note_list($courseid, $userid, $state, $author);
 328         if ($notes) {
 329             note_print_list($notes);
 330         }
 331     } else {
 332         echo '<p>' . get_string('notesnotvisible', 'notes') . '</p>';
 333     }
 334     if ($header) {
 335         echo '</div>';  // The notesgroup div.
 336     }
 337 }
 338
 339 /**
 340  * Delete all notes about users in course-
 341  * @param int $courseid
 342  * @return bool success
 343  */
 344 function note_delete_all($courseid) {
 345     global $DB;
 346
 347     return $DB->delete_records('post', array('module' => 'notes', 'courseid' => $courseid));
 348 }
 349
 350 /**
 351  * Return a list of page types
 352  * @param string $pagetype current page type
 353  * @param stdClass $parentcontext Block's parent context
 354  * @param stdClass $currentcontext Current context of block
 355  */
 356 function note_page_type_list($pagetype, $parentcontext, $currentcontext) {
 357     return array('notes-*' => get_string('page-notes-x', 'notes'));
 358 }
 359
 360 /**
 361  * Trigger notes viewed event
 362  *
 363  * @param  stdClass $context context object
 364  * @param  int $userid  user id (the user we are viewing the notes)
 365  * @since Moodle 2.9
 366  */
 367 function note_view($context, $userid) {
 368
 369     $event = \core\event\notes_viewed::create(array(
 370         'relateduserid' => $userid,
 371         'context' => $context
 372     ));
 373     $event->trigger();
 374 }
 375
 376 /**
 377  * Add nodes to myprofile page.
 378  *
 379  * @param \core_user\output\myprofile\tree $tree Tree object
 380  * @param stdClass $user user object
 381  * @param bool $iscurrentuser
 382  * @param stdClass $course Course object
 383  *
 384  * @return bool
 385  */
 386 function core_notes_myprofile_navigation(core_user\output\myprofile\tree $tree, $user, $iscurrentuser, $course) {
 387     global $CFG;
 388
 389     if (empty($CFG->enablenotes)) {
 390         // Notes are disabled, nothing to do.
 391         return false;
 392     }
 393
 394     if (isguestuser($user)) {
 395         // No notes for guest users.
 396         return false;
 397     }
 398
 399     $url = new moodle_url("/notes/index.php", array('user' => $user->id));
 400     $title = get_string('notes', 'core_notes');
 401     if (empty($course)) {
 402         // Site level profile.
 403         if (!has_capability('moodle/notes:view', context_system::instance())) {
 404             // No cap, nothing to do.
 405             return false;
 406         }
 407     } else {
 408         if (!has_capability('moodle/notes:view', context_course::instance($course->id))) {
 409             // No cap, nothing to do.
 410             return false;
 411         }
 412         $url->param('course', $course->id);
 413     }
 414     $notesnode = new core_user\output\myprofile\node('miscellaneous', 'notes', $title, null, $url);
 415     $tree->add_node($notesnode);
 416 }