Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/notes/ -> lib.php (source)
   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  }