MDL-7077, MDL-10181, adding notes for students
[moodle.git] / notes / lib.php
1 <?php // $Id$\r
2 \r
3 /**\r
4  * Library of functions and constants for notes\r
5  */\r
6 \r
7 /**\r
8  * Constants for ratings.\r
9  */\r
10 define('NOTES_RATING_LOW', '1');\r
11 define('NOTES_RATING_BELOWNORMAL', '2');\r
12 define('NOTES_RATING_NORMAL', '3');\r
13 define('NOTES_RATING_ABOVENORMAL', '4');\r
14 define('NOTES_RATING_HIGH', '5');\r
15 \r
16 /**\r
17  * Constants for states.\r
18  */\r
19 define('NOTES_STATE_DRAFT', 'draft');\r
20 define('NOTES_STATE_PUBLIC', 'public');\r
21 define('NOTES_STATE_SITE', 'site');\r
22 \r
23 /**\r
24  * Constants for note parts (flags used by note_print and note_print_list).\r
25  */\r
26 define('NOTES_SHOW_FULL', 0x07);\r
27 define('NOTES_SHOW_HEAD', 0x02);\r
28 define('NOTES_SHOW_BODY', 0x01);\r
29 define('NOTES_SHOW_FOOT', 0x04);\r
30 \r
31 /**\r
32  * Retrieves a list of note objects with specific atributes.\r
33  *\r
34  * @param int    $courseid id of the course in which the notes were posted (0 means any)\r
35  * @param int    $userid id of the user to which the notes refer (0 means any)\r
36  * @param string $state state of the notes (i.e. draft, public, site) ('' means any)\r
37  * @param int    $author id of the user who modified the note last time (0 means any)\r
38  * @param string $order an order to sort the results in\r
39  * @param int    $limitfrom number of records to skip (offset)\r
40  * @param int    $limitnum number of records to fetch\r
41  * @return array of note objects\r
42  */\r
43 function note_list($courseid=0, $userid=0, $state = '', $author = 0, $order='lastmodified DESC', $limitfrom=0, $limitnum=0) {\r
44     // setup filters\r
45     $select = array();\r
46     if($courseid) {\r
47         $selects[] = 'courseid=' . $courseid;\r
48     }\r
49     if($userid) {\r
50         $selects[] = 'userid=' . $userid;\r
51     }\r
52     if($author) {\r
53         $selects[] = 'usermodified=' . $author;\r
54     }\r
55     if($state) {\r
56         $selects[] = 'publishstate="' . $state . '"';\r
57     }\r
58     $selects[] = 'module="notes"';\r
59     $select = implode(' AND ', $selects);\r
60     $fields = 'id,courseid,userid,content,format,rating,created,lastmodified,usermodified,publishstate';\r
61     // retrieve data\r
62     $rs =& get_recordset_select('post', $select, $order, $fields, $limitfrom, $limitnum);\r
63     return recordset_to_array($rs);\r
64 }\r
65 \r
66 /**\r
67  * Retrieves a note object based on its id.\r
68  *\r
69  * @param int    $note_id id of the note to retrieve\r
70  * @return note object\r
71  */\r
72 function note_load($note_id) {\r
73     $fields = 'id,courseid,userid,content,format,rating,created,lastmodified,usermodified,publishstate';\r
74     return get_record_select('post', 'id=' . $note_id . ' AND module="notes"', $fields);\r
75 }\r
76 \r
77 /**\r
78  * Saves a note object. The note object is passed by reference and its fields (i.e. id) \r
79  * might change during the save.\r
80  *\r
81  * @param note   $note object to save\r
82  * @return boolean true if the object was saved; false otherwise\r
83  */\r
84 function note_save(&$note) {\r
85     global $USER;\r
86     // setup & clean fields\r
87     $note->module = 'notes';\r
88     $note->lastmodified = time();\r
89     $note->usermodified = $USER->id;\r
90     if(empty($note->rating)) {\r
91         $note->rating = NOTES_RATING_NORMAL;\r
92     }\r
93     if(empty($note->format)) {\r
94         $note->format = FORMAT_PLAIN;\r
95     }\r
96     if(empty($note->publishstate)) {\r
97         $note->publishstate = NOTES_STATE_PUBLIC;\r
98     }\r
99     // save data\r
100     if(empty($note->id)) {\r
101         // insert new note\r
102         $note->created = $note->lastmodified;\r
103         if($id = insert_record('post', $note)) {\r
104             $note->id = $id;\r
105             $result = true;\r
106         } else {\r
107             $result = false;\r
108         }\r
109     } else {\r
110         // update old note\r
111         $result = update_record('post', $note);\r
112     }\r
113     unset($note->module);\r
114     return $result;\r
115 }\r
116 \r
117 /**\r
118  * Deletes a note object based on its id.\r
119  *\r
120  * @param int    $note_id id of the note to delete\r
121  * @return boolean true if the object was deleted; false otherwise\r
122  */\r
123 function note_delete($noteid) {\r
124     return delete_records_select('post', 'id=' . $noteid . ' AND module="notes"');\r
125 }\r
126 \r
127 /**\r
128  * Converts a rating value to its corespondent name\r
129  *\r
130  * @param int    $rating rating value to convert\r
131  * @return string corespondent rating name\r
132  */\r
133 function note_get_rating_name($rating) {\r
134     // cache rating names\r
135     static $ratings;\r
136     if (empty($ratings)) {\r
137         $ratings =& note_get_rating_names();\r
138     }\r
139     return @$ratings[$rating];\r
140 }\r
141 \r
142 /**\r
143  * Returns an array of mappings from rating values to rating names\r
144  *\r
145  * @return array of mappings\r
146  */\r
147 function note_get_rating_names() {\r
148     return array(\r
149         1 => get_string('low', 'notes'),\r
150         2 => get_string('belownormal', 'notes'),\r
151         3 => get_string('normal', 'notes'),\r
152         4 => get_string('abovenormal', 'notes'),\r
153         5 => get_string('high', 'notes'),\r
154     );\r
155 }\r
156 \r
157 /**\r
158  * Converts a state value to its corespondent name\r
159  *\r
160  * @param string  $state state value to convert\r
161  * @return string corespondent state name\r
162  */\r
163 function note_get_state_name($state) {\r
164     // cache state names\r
165     static $states;\r
166     if (empty($states)) {\r
167         $states = note_get_state_names();\r
168     }\r
169     return @$states[$state];\r
170 }\r
171 \r
172 /**\r
173  * Returns an array of mappings from state values to state names\r
174  *\r
175  * @return array of mappings\r
176  */\r
177 function note_get_state_names() {\r
178     return array(\r
179         NOTES_STATE_DRAFT => get_string('personal', 'notes'),\r
180         NOTES_STATE_PUBLIC => get_string('course', 'notes'),\r
181         NOTES_STATE_SITE => get_string('site', 'notes'),\r
182     );\r
183 }\r
184 \r
185 /**\r
186  * Prints a note object\r
187  *\r
188  * @param note  $note the note object to print\r
189  * @param int   $detail OR-ed NOTES_SHOW_xyz flags that specify which note parts to print\r
190  */\r
191 function note_print($note, $detail = NOTES_SHOW_FULL) {\r
192 \r
193     global $CFG, $USER;\r
194     $user = get_record('user','id',$note->userid);\r
195     $context = get_context_instance(CONTEXT_COURSE, $note->courseid);\r
196     $sitecontext = get_context_instance(CONTEXT_SYSTEM);\r
197     $authoring->name = fullname(get_record('user','id',$note->usermodified));\r
198     $authoring->date = userdate($note->lastmodified);\r
199     echo '<div class="notepost '. $note->publishstate . 'notepost' . \r
200         ($note->usermodified == $USER->id ? ' ownnotepost' : '')  .\r
201         '" id="note-'. $note->id .'">';\r
202 \r
203     // print note head (e.g. author, user refering to, rating, etc)\r
204     if($detail & NOTES_SHOW_HEAD) {\r
205         echo '<div class="header">';\r
206         echo '<div class="user">';\r
207         print_user_picture($user->id, $note->courseid, $user->picture);\r
208         echo fullname($user) . '</div>';\r
209         echo '<div class="rating rating' . $note->rating . '">' . get_string('rating', 'notes') . ': ' . note_get_rating_name($note->rating) . '</div>';\r
210         echo '<div class="info">' . \r
211             get_string('bynameondate', 'notes', $authoring) . \r
212             ' (' . get_string('created', 'notes') . ': ' . userdate($note->created) . ')</div>';\r
213         echo '</div>';\r
214     }\r
215     \r
216     // print note content\r
217     if($detail & NOTES_SHOW_BODY) {\r
218         echo '<div class="content">';\r
219         echo format_text($note->content, $note->format);\r
220         echo '</div>';\r
221     }\r
222     \r
223     // print note options (e.g. delete, edit)\r
224     if($detail & NOTES_SHOW_FOOT) {\r
225         if (has_capability('moodle/notes:manage', $sitecontext) && $note->publishstate == NOTES_STATE_SITE || \r
226             has_capability('moodle/notes:manage', $context) && ($note->publishstate == NOTES_STATE_PUBLIC || $note->usermodified == $USER->id)) {\r
227             echo '<div class="footer">';\r
228             echo '<a href="'.$CFG->wwwroot.'/notes/edit.php?note='.$note->id. '">'. get_string('edit') .'</a>';\r
229             echo '<a href="'.$CFG->wwwroot.'/notes/delete.php?note='.$note->id. '">'. get_string('delete') .'</a>';\r
230             echo '</div>';\r
231         }\r
232     }\r
233     echo '</div>';\r
234 }\r
235 \r
236 /**\r
237  * Prints a list of note objects\r
238  *\r
239  * @param array  $notes array of note objects to print\r
240  * @param int   $detail OR-ed NOTES_SHOW_xyz flags that specify which note parts to print\r
241  */\r
242 function note_print_list($notes, $detail = NOTES_SHOW_FULL) {\r
243 \r
244     /// Start printing of the note\r
245     echo '<div class="notelist">';\r
246     foreach ($notes as $note) {\r
247         note_print($note, $detail);\r
248     }\r
249     echo '</div>';\r
250 }\r
251 \r
252 /**\r
253  * Retrieves and prints a list of note objects with specific atributes.\r
254  *\r
255  * @param string  $header HTML to print above the list\r
256  * @param object  $context context in which the notes will be displayed (used to check capabilities)\r
257  * @param int     $courseid id of the course in which the notes were posted (0 means any)\r
258  * @param int     $userid id of the user to which the notes refer (0 means any)\r
259  * @param string  $state state of the notes (i.e. draft, public, site) ('' means any)\r
260  * @param int     $author id of the user who modified the note last time (0 means any)\r
261  */\r
262 function note_print_notes($header, $context, $courseid = 0, $userid = 0, $state = '', $author = 0)\r
263 {\r
264     global $CFG;\r
265     if ($header) {\r
266         echo '<h3 id="notestitle">' . $header . '</h3>';\r
267     }\r
268     if (has_capability('moodle/notes:view', $context)) {\r
269         $notes =& note_list($courseid, $userid, $state, $author);\r
270         if($notes) {\r
271             note_print_list($notes);\r
272         } else {\r
273             echo '<p>' . get_string('nonotes', 'notes') . '</p>';\r
274         }\r
275     } else {\r
276         echo '<p>' . get_string('notesnotvisible', 'notes') . '</p>';\r
277     }\r
278 }\r