MDL-19524 updating version info too
[moodle.git] / comment / lib.php
CommitLineData
1bcb7eb5 1<?php
2
36051c9e
DC
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
1bcb7eb5 18/**
36051c9e 19 * Comment is helper class to add/delete comments anywhere in moodle
1bcb7eb5 20 *
36051c9e
DC
21 * @package comment
22 * @copyright 2010 Dongsheng Cai <dongsheng@moodle.com>
1bcb7eb5 23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 */
1bcb7eb5 25
36051c9e 26class comment {
1bcb7eb5 27 /**
36051c9e 28 * @var integer
1bcb7eb5 29 */
36051c9e
DC
30 private $page;
31 /**
32 * there may be several comment box in one page
33 * so we need a client_id to recognize them
34 * @var integer
35 */
36 private $cid;
37 private $contextid;
38 /**
39 * commentarea is used to specify different
40 * parts shared the same itemid
41 * @var string
42 */
43 private $commentarea;
44 /**
45 * itemid is used to associate with commenting content
46 * @var integer
47 */
48 private $itemid;
49
50 /**
51 * this html snippet will be used as a template
52 * to build comment content
53 * @var string
54 */
55 private $template;
56 private $context;
866354a9 57 private $courseid;
36051c9e 58 /**
866354a9
DC
59 * course module object, only be used to help find pluginname automatically
60 * if pluginname is specified, it won't be used at all
36051c9e
DC
61 * @var string
62 */
63 private $cm;
64 private $plugintype;
866354a9
DC
65 /**
66 * When used in module, it is recommended to use it
67 * @var string
68 */
36051c9e
DC
69 private $pluginname;
70 private $viewcap;
71 private $postcap;
72 /**
73 * to tell comments api where it is used
74 * @var string
75 */
76 private $env;
77 /**
78 * to costomize link text
79 * @var string
80 */
81 private $linktext;
866354a9
DC
82
83 // static variable will be used by non-js comments UI
36051c9e 84 private static $nonjs = false;
36051c9e
DC
85 private static $comment_itemid = null;
86 private static $comment_context = null;
87 private static $comment_area = null;
a5306210 88 private static $comment_page = null;
36051c9e 89 /**
866354a9 90 * Construct function of comment class, initialise
36051c9e
DC
91 * class members
92 * @param object $options
93 */
94 public function __construct($options) {
95 global $CFG, $DB;
76951100 96
c794595d
DC
97 if (empty($CFG->commentsperpage)) {
98 $CFG->commentsperpage = 15;
99 }
100
36051c9e
DC
101 $this->viewcap = false;
102 $this->postcap = false;
76951100 103
866354a9 104 // setup client_id
36051c9e
DC
105 if (!empty($options->client_id)) {
106 $this->cid = $options->client_id;
107 } else {
108 $this->cid = uniqid();
109 }
866354a9
DC
110
111 // setup context
36051c9e
DC
112 if (!empty($options->context)) {
113 $this->context = $options->context;
114 $this->contextid = $this->context->id;
115 } else if(!empty($options->contextid)) {
116 $this->contextid = $options->contextid;
117 $this->context = get_context_instance_by_id($this->contextid);
118 } else {
119 print_error('invalidcontext');
120 }
76951100 121
866354a9
DC
122 // setup course
123 // course will be used to generate user profile link
124 if (!empty($options->course)) {
125 $this->courseid = $options->course->id;
126 } else if (!empty($options->courseid)) {
127 $this->courseid = $options->courseid;
5b95daec 128 } else {
fe40925a 129 $this->courseid = SITEID;
866354a9
DC
130 }
131
132 if (!empty($options->pluginname)) {
133 $this->pluginname = $options->pluginname;
134 }
135
136 // setup coursemodule
137 if (!empty($options->cm)) {
138 $this->cm = $options->cm;
139 } else {
140 $this->cm = null;
141 }
142
143 // setup commentarea
36051c9e
DC
144 if (!empty($options->area)) {
145 $this->commentarea = $options->area;
146 }
76951100 147
866354a9 148 // setup itemid
36051c9e
DC
149 if (!empty($options->itemid)) {
150 $this->itemid = $options->itemid;
467c85d7
DC
151 } else {
152 $this->itemid = 0;
36051c9e 153 }
76951100 154
866354a9 155 // setup env
36051c9e
DC
156 if (!empty($options->env)) {
157 $this->env = $options->env;
1bcb7eb5 158 } else {
08a22be6 159 $this->env = '';
1bcb7eb5 160 }
1bcb7eb5 161
866354a9 162 // setup customized linktext
36051c9e
DC
163 if (!empty($options->linktext)) {
164 $this->linktext = $options->linktext;
165 } else {
166 $this->linktext = get_string('comments');
167 }
866354a9
DC
168 // setting post and view permissions
169 $this->check_permissions();
170
171 if (!empty($options->showcount)) {
172 $count = $this->count();
173 if (empty($count)) {
174 $this->count = '';
175 } else {
176 $this->count = '('.$count.')';
177 }
178 } else {
179 $this->count = '';
180 }
36051c9e 181
05fe3ab5 182 $this->setup_plugin();
36051c9e 183
866354a9
DC
184 // setup options for callback functions
185 $this->args = new stdclass;
186 $this->args->context = $this->context;
187 $this->args->courseid = $this->courseid;
188 $this->args->cm = $this->cm;
189 $this->args->commentarea = $this->commentarea;
190 $this->args->itemid = $this->itemid;
36051c9e
DC
191
192 // load template
193 $this->template = <<<EOD
194<div class="comment-userpicture">___picture___</div>
195<div class="comment-content">
196 ___name___ - <span>___time___</span>
197 <div>___content___</div>
198</div>
199EOD;
200 if (!empty($this->plugintype)) {
866354a9 201 $this->template = plugin_callback($this->plugintype, $this->pluginname, FEATURE_COMMENT, 'template', $this->args, $this->template);
1bcb7eb5 202 }
203
36051c9e
DC
204 unset($options);
205 }
206
207 /**
208 * Receive nonjs comment parameters
209 */
210 public static function init() {
211 global $PAGE, $CFG;
212 // setup variables for non-js interface
213 self::$nonjs = optional_param('nonjscomment', '', PARAM_ALPHA);
214 self::$comment_itemid = optional_param('comment_itemid', '', PARAM_INT);
215 self::$comment_context = optional_param('comment_context', '', PARAM_INT);
a5306210 216 self::$comment_page = optional_param('comment_page', '', PARAM_INT);
36051c9e
DC
217 self::$comment_area = optional_param('comment_area', '', PARAM_ALPHAEXT);
218
219 $PAGE->requires->string_for_js('addcomment', 'moodle');
220 $PAGE->requires->string_for_js('deletecomment', 'moodle');
221 $PAGE->requires->string_for_js('comments', 'moodle');
1bcb7eb5 222 }
223
36051c9e 224 /**
866354a9 225 * Setup plugin type and plugin name
36051c9e 226 */
05fe3ab5 227 private function setup_plugin() {
1bcb7eb5 228 global $DB;
36051c9e
DC
229 // blog needs to set env as "blog"
230 if ($this->env == 'blog') {
231 $this->plugintype = 'moodle';
232 $this->pluginname = 'blog';
233 }
234 // tag page needs to set env as "tag"
235 if ($this->env == 'tag') {
236 $this->plugintype = 'moodle';
237 $this->pluginname = 'tag';
238 }
1bcb7eb5 239 if ($this->context->contextlevel == CONTEXT_BLOCK) {
240 if ($block = $DB->get_record('block_instances', array('id'=>$this->context->instanceid))) {
241 $this->plugintype = 'block';
242 $this->pluginname = $block->blockname;
243 }
244 }
866354a9 245
cdbf0f5a 246 if ($this->context->contextlevel == CONTEXT_MODULE && $this->env != 'block_comments') {
1bcb7eb5 247 $this->plugintype = 'mod';
866354a9
DC
248 // to improve performance, pluginname should be assigned before initilise comment object
249 // if it is empty, we will try to guess, it will rarely be used.
250 if (empty($this->pluginname)) {
251 if (empty($this->course)) {
252 $this->course = $DB->get_record('course', array('id'=>$this->courseid), '*', MUST_EXIST);
253 }
254 $this->modinfo = get_fast_modinfo($this->course);
255 $this->pluginname = $this->modinfo->cms[$this->cm->id]->modname;
256 }
1bcb7eb5 257 }
258 }
259
260 /**
36051c9e
DC
261 * check posting comments permission
262 * It will check based on user roles and ask modules
263 * If you need to check permission by modules, a
264 * function named $pluginname_check_comment_post must be implemented
1bcb7eb5 265 */
05fe3ab5 266 private function check_permissions() {
36051c9e
DC
267 global $CFG;
268 $this->postcap = has_capability('moodle/comment:post', $this->context);
269 $this->viewcap = has_capability('moodle/comment:view', $this->context);
270 if (!empty($this->plugintype)) {
866354a9 271 $permissions = plugin_callback($this->plugintype, $this->pluginname, FEATURE_COMMENT, 'permissions', $this->args, array('post'=>true, 'view'=>true));
36051c9e
DC
272 $this->postcap = $this->postcap && $permissions['post'];
273 $this->viewcap = $this->viewcap && $permissions['view'];
6f5e0852 274 }
1bcb7eb5 275 }
276
277 /**
36051c9e
DC
278 * Prepare comment code in html
279 * @param boolean $return
280 * @return mixed
1bcb7eb5 281 */
36051c9e 282 public function output($return = true) {
4b201bc6
DC
283 global $PAGE, $OUTPUT;
284 static $template_printed;
36051c9e 285
5dce9d1b 286 $this->link = $PAGE->url;
36051c9e
DC
287 $murl = new moodle_url($this->link);
288 $murl->remove_params('nonjscomment');
289 $murl->param('nonjscomment', 'true');
866354a9
DC
290 $murl->param('comment_itemid', $this->itemid);
291 $murl->param('comment_context', $this->context->id);
292 $murl->param('comment_area', $this->commentarea);
a5306210 293 $murl->remove_params('comment_page');
36051c9e 294 $this->link = $murl->out();
76951100 295
36051c9e
DC
296 $options = new stdclass;
297 $options->client_id = $this->cid;
298 $options->commentarea = $this->commentarea;
299 $options->itemid = $this->itemid;
300 $options->page = 0;
866354a9 301 $options->courseid = $this->courseid;
36051c9e 302 $options->contextid = $this->contextid;
76951100 303 $options->env = $this->env;
36051c9e
DC
304 if ($this->env == 'block_comments') {
305 $options->autostart = true;
306 $options->notoggle = true;
307 }
308
309 $PAGE->requires->js_init_call('M.core_comment.init', array($options), true);
310
311 if (!empty(self::$nonjs)) {
76951100 312 // return non js comments interface
a5306210 313 return $this->print_comments(self::$comment_page, $return, true);
36051c9e 314 }
76951100 315
36051c9e
DC
316 $strsubmit = get_string('submit');
317 $strcancel = get_string('cancel');
318 $sesskey = sesskey();
4b201bc6 319 $html = '';
36051c9e 320 // print html template
76951100 321 // Javascript will use the template to render new comments
4b201bc6
DC
322 if (empty($template_printed) && !empty($this->viewcap)) {
323 $html .= '<div style="display:none" id="cmt-tmpl">' . $this->template . '</div>';
324 $template_printed = true;
36051c9e
DC
325 }
326
327 if (!empty($this->viewcap)) {
328 // print commenting icon and tooltip
07eebf20 329 $icon = $OUTPUT->pix_url('t/collapsed');
4b201bc6 330 $html .= <<<EOD
b1d124d1 331<div class="mdl-left">
36051c9e 332<a id="comment-link-{$this->cid}" href="{$this->link}">
07eebf20 333 <img id="comment-img-{$this->cid}" src="$icon" alt="{$this->linktext}" title="{$this->linktext}" />
76951100 334 <span id="comment-link-text-{$this->cid}">{$this->linktext} {$this->count}</span>
36051c9e
DC
335</a>
336<div id="comment-ctrl-{$this->cid}" class="comment-ctrl">
337 <ul id="comment-list-{$this->cid}" class="comment-list">
76951100
DC
338EOD;
339 // in comments block, we print comments list right away
340 if ($this->env == 'block_comments') {
341 $html .= $this->print_comments(0, true, false);
3e34183a
DC
342 $html .= '</ul>';
343 $html .= $this->get_pagination(0);
344 } else {
345 $html .= <<<EOD
36051c9e
DC
346 </ul>
347 <div id="comment-pagination-{$this->cid}" class="comment-pagination"></div>
348EOD;
3e34183a 349 }
36051c9e
DC
350
351 // print posting textarea
352 if (!empty($this->postcap)) {
353 $html .= <<<EOD
354<div class='comment-area'>
355 <div class="bd">
76951100 356 <textarea name="content" rows="2" id="dlg-content-{$this->cid}"></textarea>
36051c9e
DC
357 </div>
358 <div class="fd" id="comment-action-{$this->cid}">
1150c1bd 359 <a href="#" id="comment-action-post-{$this->cid}"> {$strsubmit} </a>
36051c9e
DC
360EOD;
361 if ($this->env != 'block_comments') {
362 $html .= <<<EOD
363 <span> | </span>
1150c1bd 364 <a href="#" id="comment-action-cancel-{$this->cid}"> {$strcancel} </a>
36051c9e
DC
365EOD;
366 }
367
368 $html .= <<<EOD
369 </div>
370</div>
b1d124d1 371<div class="clearer"></div>
36051c9e
DC
372EOD;
373 }
374
375 $html .= <<<EOD
76951100 376</div><!-- end of comment-ctrl -->
36051c9e
DC
377</div>
378EOD;
379 } else {
380 $html = '';
381 }
382
383 if ($return) {
384 return $html;
385 } else {
386 echo $html;
1bcb7eb5 387 }
1bcb7eb5 388 }
36051c9e 389
1bcb7eb5 390 /**
36051c9e
DC
391 * Return matched comments
392 * @param int $page
393 * @return mixed
1bcb7eb5 394 */
36051c9e
DC
395 public function get_comments($page = '') {
396 global $DB, $CFG, $USER, $OUTPUT;
397 if (empty($this->viewcap)) {
398 return false;
399 }
36051c9e
DC
400 if (!is_numeric($page)) {
401 $page = 0;
402 }
403 $this->page = $page;
404 $params = array();
405 $start = $page * $CFG->commentsperpage;
406 $sql = "SELECT c.id, c.userid, c.content, c.format, c.timecreated, u.picture, u.imagealt, u.username, u.firstname, u.lastname
407 FROM {comments} c, {user} u WHERE u.id=c.userid AND c.contextid=? AND c.commentarea=? AND c.itemid=?
408 ORDER BY c.timecreated DESC";
409 $params[] = $this->contextid;
410 $params[] = $this->commentarea;
411 $params[] = $this->itemid;
412
413 $comments = array();
414 $candelete = has_capability('moodle/comment:delete', $this->context);
415 if ($records = $DB->get_records_sql($sql, $params, $start, $CFG->commentsperpage)) {
416 foreach ($records as &$c) {
866354a9 417 $url = $CFG->httpswwwroot.'/user/view.php?id='.$c->userid.'&amp;course='.$this->courseid;
36051c9e
DC
418 $c->username = '<a href="'.$url.'">'.fullname($c).'</a>';
419 $c->time = userdate($c->timecreated, get_string('strftimerecent', 'langconfig'));
420 $user = new stdclass;
421 $user->id = $c->userid;
422 $user->picture = $c->picture;
423 $user->firstname = $c->firstname;
424 $user->lastname = $c->lastname;
425 $user->imagealt = $c->imagealt;
426 $c->content = format_text($c->content, $c->format);
427 $c->avatar = $OUTPUT->user_picture($user, array('size'=>18));
428 if (($USER->id == $c->userid) || !empty($candelete)) {
429 $c->delete = true;
430 }
431 $comments[] = $c;
432 }
433 }
36051c9e
DC
434 if (!empty($this->plugintype)) {
435 // moodle module will filter comments
866354a9 436 $comments = plugin_callback($this->plugintype, $this->pluginname, FEATURE_COMMENT, 'display', array($comments, $this->args), $comments);
36051c9e
DC
437 }
438
439 return $comments;
440 }
441
442 public function count() {
1bcb7eb5 443 global $DB;
36051c9e
DC
444 if ($count = $DB->count_records('comments', array('itemid'=>$this->itemid, 'commentarea'=>$this->commentarea, 'contextid'=>$this->context->id))) {
445 return $count;
446 } else {
447 return 0;
448 }
449 }
450
451 public function get_pagination($page = 0) {
452 global $DB, $CFG, $OUTPUT;
453 $count = $this->count();
454 $pages = (int)ceil($count/$CFG->commentsperpage);
455 if ($pages == 1 || $pages == 0) {
456 return '';
457 }
458 if (!empty(self::$nonjs)) {
459 // used in non-js interface
a5306210 460 return $OUTPUT->paging_bar($count, $page, $CFG->commentsperpage, $this->link, 'comment_page');
36051c9e
DC
461 } else {
462 // return ajax paging bar
463 $str = '';
3e34183a 464 $str .= '<div class="comment-paging" id="comment-pagination-'.$this->cid.'">';
36051c9e 465 for ($p=0; $p<$pages; $p++) {
36051c9e 466 if ($p == $page) {
c794595d
DC
467 $class = 'curpage';
468 } else {
469 $class = 'pageno';
1bcb7eb5 470 }
1150c1bd 471 $str .= '<a href="#" class="'.$class.'" id="comment-page-'.$this->cid.'-'.$p.'">'.($p+1).'</a> ';
36051c9e
DC
472 }
473 $str .= '</div>';
474 }
475 return $str;
476 }
477
478 /**
479 * Add a new comment
480 * @param string $content
481 * @return mixed
482 */
483 public function add($content, $format = FORMAT_MOODLE) {
484 global $CFG, $DB, $USER, $OUTPUT;
485 if (empty($this->postcap)) {
486 throw new comment_exception('nopermissiontocomment');
487 }
488 $now = time();
489 $newcmt = new stdclass;
490 $newcmt->contextid = $this->contextid;
491 $newcmt->commentarea = $this->commentarea;
492 $newcmt->itemid = $this->itemid;
493 $newcmt->content = $content;
494 $newcmt->format = $format;
495 $newcmt->userid = $USER->id;
496 $newcmt->timecreated = $now;
497
498 if (!empty($this->plugintype)) {
499 // moodle module will check content
866354a9 500 $ret = plugin_callback($this->plugintype, $this->pluginname, FEATURE_COMMENT, 'add', array(&$newcmt, $this->args), true);
36051c9e
DC
501 if (!$ret) {
502 throw new comment_exception('modulererejectcomment');
1bcb7eb5 503 }
504 }
36051c9e
DC
505
506 $cmt_id = $DB->insert_record('comments', $newcmt);
507 if (!empty($cmt_id)) {
508 $newcmt->id = $cmt_id;
509 $newcmt->time = userdate($now, get_string('strftimerecent', 'langconfig'));
510 $newcmt->username = fullname($USER);
511 $newcmt->content = format_text($newcmt->content);
512 $newcmt->avatar = $OUTPUT->user_picture($USER, array('size'=>16));
513 return $newcmt;
514 } else {
515 throw new comment_exception('dbupdatefailed');
516 }
517 }
518
519 /**
520 * delete by context, commentarea and itemid
521 *
522 */
523 public function delete_comments() {
524 global $DB;
b9a689e8 525 $DB->delete_records('comments', array(
36051c9e
DC
526 'contextid'=>$this->context->id,
527 'commentarea'=>$this->commentarea,
528 'itemid'=>$this->itemid)
529 );
b9a689e8 530 return true;
36051c9e
DC
531 }
532
533 /**
534 * Delete a comment
535 * @param int $commentid
536 * @return mixed
537 */
538 public function delete($commentid) {
539 global $DB, $USER;
540 $candelete = has_capability('moodle/comment:delete', $this->context);
541 if (!$comment = $DB->get_record('comments', array('id'=>$commentid))) {
542 throw new comment_exception('dbupdatefailed');
543 }
544 if (!($USER->id == $comment->userid || !empty($candelete))) {
545 throw new comment_exception('nopermissiontocomment');
546 }
b9a689e8
DC
547 $DB->delete_records('comments', array('id'=>$commentid));
548 return true;
36051c9e
DC
549 }
550
76951100
DC
551 /**
552 * Print comments
553 * @param int $page
554 * @param boolean $return return comments list string or print it out
555 * @param boolean $nonjs print nonjs comments list or not?
556 * @return mixed
557 */
558 public function print_comments($page = 0, $return = true, $nonjs = true) {
5dce9d1b 559 global $DB, $CFG, $PAGE;
36051c9e 560 $html = '';
866354a9
DC
561 if (!(self::$comment_itemid == $this->itemid &&
562 self::$comment_context == $this->context->id &&
563 self::$comment_area == $this->commentarea)) {
36051c9e
DC
564 $page = 0;
565 }
566 $comments = $this->get_comments($page);
567
76951100
DC
568 $html = '';
569 if ($nonjs) {
570 $html .= '<h3>'.get_string('comments').'</h3>';
571 $html .= "<ul id='comment-list-$this->cid' class='comment-list'>";
572 }
36051c9e
DC
573 $results = array();
574 $list = '';
76951100 575
36051c9e 576 foreach ($comments as $cmt) {
76951100 577 $list = '<li id="comment-'.$cmt->id.'-'.$this->cid.'">'.$this->print_comment($cmt, $nonjs).'</li>' . $list;
36051c9e
DC
578 }
579 $html .= $list;
76951100
DC
580 if ($nonjs) {
581 $html .= '</ul>';
3e34183a 582 $html .= $this->get_pagination($page);
76951100 583 }
36051c9e 584 $sesskey = sesskey();
5dce9d1b 585 $returnurl = $PAGE->url;
36051c9e 586 $strsubmit = get_string('submit');
76951100 587 if ($nonjs) {
36051c9e
DC
588 $html .= <<<EOD
589<form method="POST" action="{$CFG->wwwroot}/comment/comment_post.php">
76951100 590<textarea name="content" rows="2"></textarea>
36051c9e
DC
591<input type="hidden" name="contextid" value="$this->contextid" />
592<input type="hidden" name="action" value="add" />
593<input type="hidden" name="area" value="$this->commentarea" />
594<input type="hidden" name="itemid" value="$this->itemid" />
866354a9 595<input type="hidden" name="courseid" value="{$this->courseid}" />
36051c9e
DC
596<input type="hidden" name="sesskey" value="{$sesskey}" />
597<input type="hidden" name="returnurl" value="{$returnurl}" />
598<input type="submit" value="{$strsubmit}" />
599</form>
600EOD;
76951100 601 }
36051c9e
DC
602 if ($return) {
603 return $html;
604 } else {
605 echo $html;
606 }
607 }
608
76951100
DC
609 public function print_comment($cmt, $nonjs = true) {
610 global $OUTPUT;
36051c9e
DC
611 $patterns = array();
612 $replacements = array();
613
76951100 614 if (!empty($cmt->delete) && empty($nonjs)) {
1150c1bd 615 $cmt->content = '<div class="comment-delete"><a href="#" id ="comment-delete-'.$this->cid.'-'.$cmt->id.'"><img src="'.$OUTPUT->pix_url('t/delete').'" /></a></div>' . $cmt->content;
76951100
DC
616 // add the button
617 }
36051c9e
DC
618 $patterns[] = '___picture___';
619 $patterns[] = '___name___';
620 $patterns[] = '___content___';
621 $patterns[] = '___time___';
622 $replacements[] = $cmt->avatar;
623 $replacements[] = fullname($cmt);
624 $replacements[] = $cmt->content;
625 $replacements[] = userdate($cmt->timecreated, get_string('strftimerecent', 'langconfig'));
626
627 // use html template to format a single comment.
628 return str_replace($patterns, $replacements, $this->template);
629 }
630}
631
632class comment_exception extends moodle_exception {
633 public $message;
634 function __construct($errorcode) {
635 $this->errorcode = $errorcode;
636 $this->message = get_string($errorcode, 'error');
1bcb7eb5 637 }
638}