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