notes/lib.php

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