7ed5a556a7f6bff4fd30c423697022aa0dc3c447
[moodle.git] / 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/>.
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  */
25 /**
26  * Constants for states.
27  */
28 define('NOTES_STATE_DRAFT', 'draft');
29 define('NOTES_STATE_PUBLIC', 'public');
30 define('NOTES_STATE_SITE', 'site');
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);
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;
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';
77     $select = implode(' AND ', $selects);
78     $fields = 'id,courseid,userid,content,format,created,lastmodified,usermodified,publishstate';
80     return $DB->get_records_select('post', $select, $params, $order, $fields, $limitfrom, $limitnum);
81 }
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;
92     $fields = 'id,courseid,userid,content,format,created,lastmodified,usermodified,publishstate';
93     return $DB->get_record('post', array('id' => $noteid, 'module' => 'notes'), $fields);
94 }
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;
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     // Save data.
117     if (empty($note->id)) {
118         // Insert new note.
119         $note->created = $note->lastmodified;
120         $id = $DB->insert_record('post', $note);
121         $note = note_load($id);
123         // Trigger event.
124         $event = \core\event\note_created::create(array(
125             'objectid' => $note->id,
126             'courseid' => $note->courseid,
127             'relateduserid' => $note->userid,
128             'userid' => $note->usermodified,
129             'context' => context_course::instance($note->courseid),
130             'other' => array('publishstate' => $note->publishstate)
131         ));
132         $event->trigger();
133     } else {
134         // Update old note.
135         $DB->update_record('post', $note);
136         $note = note_load($note->id);
138         // Trigger event.
139         $event = \core\event\note_updated::create(array(
140             'objectid' => $note->id,
141             'courseid' => $note->courseid,
142             'relateduserid' => $note->userid,
143             'userid' => $note->usermodified,
144             'context' => context_course::instance($note->courseid),
145             'other' => array('publishstate' => $note->publishstate)
146         ));
147         $event->trigger();
148     }
149     unset($note->module);
150     return true;
153 /**
154  * Deletes a note object based on its id.
155  *
156  * @param int|object    $note id of the note to delete, or a note object which is to be deleted.
157  * @return boolean true if the object was deleted; false otherwise
158  */
159 function note_delete($note) {
160     global $DB;
161     if (is_int($note)) {
162         $noteid = $note;
163     } else {
164         $noteid = $note->id;
165     }
166     // Get the full record, note_load doesn't return everything.
167     $note = $DB->get_record('post', array('id' => $noteid), '*', MUST_EXIST);
168     $return = $DB->delete_records('post', array('id' => $note->id, 'module' => 'notes'));
170     // Trigger event.
171     $event = \core\event\note_deleted::create(array(
172         'objectid' => $note->id,
173         'courseid' => $note->courseid,
174         'relateduserid' => $note->userid,
175         'userid' => $note->usermodified,
176         'context' => context_course::instance($note->courseid),
177         'other' => array('publishstate' => $note->publishstate)
178     ));
179     $event->add_record_snapshot('post', $note);
180     $event->trigger();
182     return $return;
185 /**
186  * Converts a state value to its corespondent name
187  *
188  * @param string  $state state value to convert
189  * @return string corespondent state name
190  */
191 function note_get_state_name($state) {
192     // Cache state names.
193     static $states;
194     if (empty($states)) {
195         $states = note_get_state_names();
196     }
197     if (isset($states[$state])) {
198         return $states[$state];
199     } else {
200         return null;
201     }
204 /**
205  * Returns an array of mappings from state values to state names
206  *
207  * @return array of mappings
208  */
209 function note_get_state_names() {
210     return array(
211         NOTES_STATE_DRAFT => get_string('personal', 'notes'),
212         NOTES_STATE_PUBLIC => get_string('course', 'notes'),
213         NOTES_STATE_SITE => get_string('site', 'notes'),
214     );
217 /**
218  * Prints a note object
219  *
220  * @param note  $note the note object to print
221  * @param int   $detail OR-ed NOTES_SHOW_xyz flags that specify which note parts to print
222  */
223 function note_print($note, $detail = NOTES_SHOW_FULL) {
224     global $CFG, $USER, $DB, $OUTPUT;
226     if (!$user = $DB->get_record('user', array('id' => $note->userid))) {
227         debugging("User $note->userid not found");
228         return;
229     }
230     if (!$author = $DB->get_record('user', array('id' => $note->usermodified))) {
231         debugging("User $note->usermodified not found");
232         return;
233     }
234     $context = context_course::instance($note->courseid);
235     $systemcontext = context_system::instance();
237     $authoring = new stdClass();
238     $authoring->name = '<a href="' . $CFG->wwwroot . '/user/view.php?id=' . $author->id .
239         '&amp;course='.$note->courseid . '">' . fullname($author) . '</a>';
240     $authoring->date = userdate($note->lastmodified);
242     echo '<div class="notepost '. $note->publishstate . 'notepost' .
243         ($note->usermodified == $USER->id ? ' ownnotepost' : '')  .
244         '" id="note-' . $note->id . '">';
246     // Print note head (e.g. author, user refering to, etc).
247     if ($detail & NOTES_SHOW_HEAD) {
248         echo '<div class="header">';
249         echo '<div class="user">';
250         echo $OUTPUT->user_picture($user, array('courseid' => $note->courseid));
251         echo fullname($user) . '</div>';
252         echo '<div class="info">' .
253             get_string('bynameondate', 'notes', $authoring) .
254             ' (' . get_string('created', 'notes') . ': ' . userdate($note->created) . ')</div>';
255         echo '</div>';
256     }
258     // Print note content.
259     if ($detail & NOTES_SHOW_BODY) {
260         echo '<div class="content">';
261         echo format_text($note->content, $note->format, array('overflowdiv' => true));
262         echo '</div>';
263     }
265     // Print note options (e.g. delete, edit).
266     if ($detail & NOTES_SHOW_FOOT) {
267         if (has_capability('moodle/notes:manage', $systemcontext) && $note->publishstate == NOTES_STATE_SITE ||
268             has_capability('moodle/notes:manage', $context) &&
269             ($note->publishstate == NOTES_STATE_PUBLIC || $note->usermodified == $USER->id)) {
270             echo '<div class="footer"><p>';
271             echo '<a href="' . $CFG->wwwroot . '/notes/edit.php?id=' . $note->id. '">' . get_string('edit') . '</a> | ';
272             echo '<a href="' . $CFG->wwwroot . '/notes/delete.php?id=' . $note->id. '">' . get_string('delete') . '</a>';
273             echo '</p></div>';
274         }
275     }
276     echo '</div>';
279 /**
280  * Prints a list of note objects
281  *
282  * @param array  $notes array of note objects to print
283  * @param int   $detail OR-ed NOTES_SHOW_xyz flags that specify which note parts to print
284  */
285 function note_print_list($notes, $detail = NOTES_SHOW_FULL) {
287     echo '<div class="notelist">';
288     foreach ($notes as $note) {
289         note_print($note, $detail);
290     }
291     echo '</div>';
294 /**
295  * Retrieves and prints a list of note objects with specific atributes.
296  *
297  * @param string  $header HTML to print above the list
298  * @param int     $addcourseid id of the course for the add notes link (0 hide link)
299  * @param boolean $viewnotes true if the notes should be printed; false otherwise (print notesnotvisible string)
300  * @param int     $courseid id of the course in which the notes were posted (0 means any)
301  * @param int     $userid id of the user to which the notes refer (0 means any)
302  * @param string  $state state of the notes (i.e. draft, public, site) ('' means any)
303  * @param int     $author id of the user who modified the note last time (0 means any)
304  */
305 function note_print_notes($header, $addcourseid = 0, $viewnotes = true, $courseid = 0, $userid = 0, $state = '', $author = 0) {
306     global $CFG;
308     if ($header) {
309         echo '<h3 class="notestitle">' . $header . '</h3>';
310         echo '<div class="notesgroup">';
311     }
312     if ($addcourseid) {
313         if ($userid) {
314             echo '<p><a href="' . $CFG->wwwroot . '/notes/edit.php?courseid=' . $addcourseid . '&amp;userid=' . $userid .
315                 '&amp;publishstate=' . $state . '">' . get_string('addnewnote', 'notes') . '</a></p>';
316         } else {
317             echo '<p><a href="' . $CFG->wwwroot . '/user/index.php?id=' . $addcourseid. '">' .
318                 get_string('addnewnoteselect', 'notes') . '</a></p>';
319         }
320     }
321     if ($viewnotes) {
322         $notes = note_list($courseid, $userid, $state, $author);
323         if ($notes) {
324             note_print_list($notes);
325         }
326     } else {
327         echo '<p>' . get_string('notesnotvisible', 'notes') . '</p>';
328     }
329     if ($header) {
330         echo '</div>';  // The notesgroup div.
331     }
334 /**
335  * Delete all notes about users in course-
336  * @param int $courseid
337  * @return bool success
338  */
339 function note_delete_all($courseid) {
340     global $DB;
342     return $DB->delete_records('post', array('module' => 'notes', 'courseid' => $courseid));
345 /**
346  * Return a list of page types
347  * @param string $pagetype current page type
348  * @param stdClass $parentcontext Block's parent context
349  * @param stdClass $currentcontext Current context of block
350  */
351 function note_page_type_list($pagetype, $parentcontext, $currentcontext) {
352     return array('notes-*' => get_string('page-notes-x', 'notes'));
355 /**
356  * Trigger notes viewed event
357  *
358  * @param  stdClass $context context object
359  * @param  int $userid  user id (the user we are viewing the notes)
360  * @since Moodle 2.9
361  */
362 function note_view($context, $userid) {
364     $event = \core\event\notes_viewed::create(array(
365         'relateduserid' => $userid,
366         'context' => $context
367     ));
368     $event->trigger();
371 /**
372  * Add nodes to myprofile page.
373  *
374  * @param \core_user\output\myprofile\tree $tree Tree object
375  * @param stdClass $user user object
376  * @param bool $iscurrentuser
377  * @param stdClass $course Course object
378  *
379  * @return bool
380  */
381 function core_notes_myprofile_navigation(core_user\output\myprofile\tree $tree, $user, $iscurrentuser, $course) {
382     $url = new moodle_url("/notes/index.php", array('user' => $user->id));
383     $title = $iscurrentuser ? get_string('myprofileownnotes', 'core_notes') :
384             get_string('myprofileothernotes', 'core_notes', fullname($user));;
385     if (empty($course)) {
386         // Site level profile.
387         if (!has_capability('moodle/notes:view', context_system::instance())) {
388             // No cap, nothing to do.
389             return false;
390         }
391         $url->param('course', 0);
392     } else {
393         if (!has_capability('moodle/notes:view', context_course::instance($course->id))) {
394             // No cap, nothing to do.
395             return false;
396         }
397         $url->param('course', $course->id);
398     }
399     $notesnode = new core_user\output\myprofile\node('miscellaneous', 'notes', $title, null, $url);
400     $tree->add_node($notesnode);