Merge branch 'MDL-33671-master-3' of git://github.com/peterRd/moodle
[moodle.git] / comment / lib.php
blob58f8151d380b38f0e44153a2f29abf4df331414c
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.
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 * Functions and classes for commenting
20 * @package core
21 * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 defined('MOODLE_INTERNAL') || die();
26 /**
27 * Comment is helper class to add/delete comments anywhere in moodle
29 * @package core
30 * @category comment
31 * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
32 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
34 class comment {
35 /** @var int there may be several comment box in one page so we need a client_id to recognize them */
36 private $cid;
37 /** @var string commentarea is used to specify different parts shared the same itemid */
38 private $commentarea;
39 /** @var int itemid is used to associate with commenting content */
40 private $itemid;
41 /** @var string this html snippet will be used as a template to build comment content */
42 private $template;
43 /** @var int The context id for comments */
44 private $contextid;
45 /** @var stdClass The context itself */
46 private $context;
47 /** @var int The course id for comments */
48 private $courseid;
49 /** @var stdClass course module object, only be used to help find pluginname automatically */
50 private $cm;
51 /**
52 * The component that this comment is for.
54 * It is STRONGLY recommended to set this.
55 * Added as a database field in 2.9, old comments will have a null component.
57 * @var string
59 private $component;
60 /** @var string This is calculated by normalising the component */
61 private $pluginname;
62 /** @var string This is calculated by normalising the component */
63 private $plugintype;
64 /** @var bool Whether the user has the required capabilities/permissions to view comments. */
65 private $viewcap = false;
66 /** @var bool Whether the user has the required capabilities/permissions to post comments. */
67 private $postcap = false;
68 /** @var string to customize link text */
69 private $linktext;
70 /** @var bool If set to true then comment sections won't be able to be opened and closed instead they will always be visible. */
71 protected $notoggle = false;
72 /** @var bool If set to true comments are automatically loaded as soon as the page loads. */
73 protected $autostart = false;
74 /** @var bool If set to true the total count of comments is displayed when displaying comments. */
75 protected $displaytotalcount = false;
76 /** @var bool If set to true a cancel button will be shown on the form used to submit comments. */
77 protected $displaycancel = false;
78 /** @var int The number of comments associated with this comments params */
79 protected $totalcommentcount = null;
81 /**
82 * Set to true to remove the col attribute from the textarea making it full width.
83 * @var bool
85 protected $fullwidth = false;
87 /** @var bool Use non-javascript UI */
88 private static $nonjs = false;
89 /** @var int comment itemid used in non-javascript UI */
90 private static $comment_itemid = null;
91 /** @var int comment context used in non-javascript UI */
92 private static $comment_context = null;
93 /** @var string comment area used in non-javascript UI */
94 private static $comment_area = null;
95 /** @var string comment page used in non-javascript UI */
96 private static $comment_page = null;
97 /** @var string comment itemid component in non-javascript UI */
98 private static $comment_component = null;
101 * Construct function of comment class, initialise
102 * class members
104 * @param stdClass $options {
105 * context => context context to use for the comment [required]
106 * component => string which plugin will comment being added to [required]
107 * itemid => int the id of the associated item (forum post, glossary item etc) [required]
108 * area => string comment area
109 * cm => stdClass course module
110 * course => course course object
111 * client_id => string an unique id to identify comment area
112 * autostart => boolean automatically expend comments
113 * showcount => boolean display the number of comments
114 * displaycancel => boolean display cancel button
115 * notoggle => boolean don't show/hide button
116 * linktext => string title of show/hide button
119 public function __construct(stdClass $options) {
120 $this->viewcap = false;
121 $this->postcap = false;
123 // setup client_id
124 if (!empty($options->client_id)) {
125 $this->cid = $options->client_id;
126 } else {
127 $this->cid = uniqid();
130 // setup context
131 if (!empty($options->context)) {
132 $this->context = $options->context;
133 $this->contextid = $this->context->id;
134 } else if(!empty($options->contextid)) {
135 $this->contextid = $options->contextid;
136 $this->context = context::instance_by_id($this->contextid);
137 } else {
138 print_error('invalidcontext');
141 if (!empty($options->component)) {
142 // set and validate component
143 $this->set_component($options->component);
144 } else {
145 // component cannot be empty
146 throw new comment_exception('invalidcomponent');
149 // setup course
150 // course will be used to generate user profile link
151 if (!empty($options->course)) {
152 $this->courseid = $options->course->id;
153 } else if (!empty($options->courseid)) {
154 $this->courseid = $options->courseid;
155 } else {
156 if ($coursecontext = $this->context->get_course_context(false)) {
157 $this->courseid = $coursecontext->instanceid;
158 } else {
159 $this->courseid = SITEID;
163 // setup coursemodule
164 if (!empty($options->cm)) {
165 $this->cm = $options->cm;
166 } else {
167 $this->cm = null;
170 // setup commentarea
171 if (!empty($options->area)) {
172 $this->commentarea = $options->area;
175 // setup itemid
176 if (!empty($options->itemid)) {
177 $this->itemid = $options->itemid;
178 } else {
179 $this->itemid = 0;
182 // setup customized linktext
183 if (!empty($options->linktext)) {
184 $this->linktext = $options->linktext;
185 } else {
186 $this->linktext = get_string('comments');
189 // setup options for callback functions
190 $this->comment_param = new stdClass();
191 $this->comment_param->context = $this->context;
192 $this->comment_param->courseid = $this->courseid;
193 $this->comment_param->cm = $this->cm;
194 $this->comment_param->commentarea = $this->commentarea;
195 $this->comment_param->itemid = $this->itemid;
197 // setup notoggle
198 if (!empty($options->notoggle)) {
199 $this->set_notoggle($options->notoggle);
202 // setup notoggle
203 if (!empty($options->autostart)) {
204 $this->set_autostart($options->autostart);
207 // setup displaycancel
208 if (!empty($options->displaycancel)) {
209 $this->set_displaycancel($options->displaycancel);
212 // setup displaytotalcount
213 if (!empty($options->showcount)) {
214 $this->set_displaytotalcount($options->showcount);
217 // setting post and view permissions
218 $this->check_permissions();
220 // load template
221 $this->template = html_writer::start_tag('div', array('class' => 'comment-message'));
223 $this->template .= html_writer::start_tag('div', array('class' => 'comment-message-meta mr-3'));
225 $this->template .= html_writer::tag('span', '___picture___', array('class' => 'picture'));
226 $this->template .= html_writer::tag('span', '___name___', array('class' => 'user')) . ' - ';
227 $this->template .= html_writer::tag('span', '___time___', array('class' => 'time'));
229 $this->template .= html_writer::end_tag('div'); // .comment-message-meta
230 $this->template .= html_writer::tag('div', '___content___', array('class' => 'text'));
232 $this->template .= html_writer::end_tag('div'); // .comment-message
234 if (!empty($this->plugintype)) {
235 $this->template = plugin_callback($this->plugintype, $this->pluginname, 'comment', 'template', array($this->comment_param), $this->template);
238 unset($options);
242 * Receive nonjs comment parameters
244 * @param moodle_page $page The page object to initialise comments within
245 * If not provided the global $PAGE is used
247 public static function init(moodle_page $page = null) {
248 global $PAGE;
250 if (empty($page)) {
251 $page = $PAGE;
253 // setup variables for non-js interface
254 self::$nonjs = optional_param('nonjscomment', '', PARAM_ALPHANUM);
255 self::$comment_itemid = optional_param('comment_itemid', '', PARAM_INT);
256 self::$comment_component = optional_param('comment_component', '', PARAM_COMPONENT);
257 self::$comment_context = optional_param('comment_context', '', PARAM_INT);
258 self::$comment_page = optional_param('comment_page', '', PARAM_INT);
259 self::$comment_area = optional_param('comment_area', '', PARAM_AREA);
261 $page->requires->strings_for_js(array(
262 'addcomment',
263 'comments',
264 'commentscount',
265 'commentsrequirelogin',
266 'deletecommentbyon'
268 'moodle'
273 * Sets the component.
275 * This method shouldn't be public, changing the component once it has been set potentially
276 * invalidates permission checks.
277 * A coding_error is now thrown if code attempts to change the component.
279 * @throws coding_exception if you try to change the component after it has been set.
280 * @param string $component
282 public function set_component($component) {
283 if (!empty($this->component) && $this->component !== $component) {
284 throw new coding_exception('You cannot change the component of a comment once it has been set');
286 $this->component = $component;
287 list($this->plugintype, $this->pluginname) = core_component::normalize_component($component);
291 * Determines if the user can view the comment.
293 * @param bool $value
295 public function set_view_permission($value) {
296 $this->viewcap = (bool)$value;
300 * Determines if the user can post a comment
302 * @param bool $value
304 public function set_post_permission($value) {
305 $this->postcap = (bool)$value;
309 * check posting comments permission
310 * It will check based on user roles and ask modules
311 * If you need to check permission by modules, a
312 * function named $pluginname_check_comment_post must be implemented
314 private function check_permissions() {
315 $this->postcap = has_capability('moodle/comment:post', $this->context);
316 $this->viewcap = has_capability('moodle/comment:view', $this->context);
317 if (!empty($this->plugintype)) {
318 $permissions = plugin_callback($this->plugintype, $this->pluginname, 'comment', 'permissions', array($this->comment_param), array('post'=>false, 'view'=>false));
319 $this->postcap = $this->postcap && $permissions['post'];
320 $this->viewcap = $this->viewcap && $permissions['view'];
325 * Gets a link for this page that will work with JS disabled.
327 * @global moodle_page $PAGE
328 * @param moodle_page $page
329 * @return moodle_url
331 public function get_nojslink(moodle_page $page = null) {
332 if ($page === null) {
333 global $PAGE;
334 $page = $PAGE;
337 $link = new moodle_url($page->url, array(
338 'nonjscomment' => true,
339 'comment_itemid' => $this->itemid,
340 'comment_context' => $this->context->id,
341 'comment_component' => $this->get_component(),
342 'comment_area' => $this->commentarea,
344 $link->remove_params(array('comment_page'));
345 return $link;
349 * Sets the value of the notoggle option.
351 * If set to true then the user will not be able to expand and collase
352 * the comment section.
354 * @param bool $newvalue
356 public function set_notoggle($newvalue = true) {
357 $this->notoggle = (bool)$newvalue;
361 * Sets the value of the autostart option.
363 * If set to true then the comments will be loaded during page load.
364 * Normally this happens only once the user expands the comment section.
366 * @param bool $newvalue
368 public function set_autostart($newvalue = true) {
369 $this->autostart = (bool)$newvalue;
373 * Sets the displaycancel option
375 * If set to true then a cancel button will be shown when using the form
376 * to post comments.
378 * @param bool $newvalue
380 public function set_displaycancel($newvalue = true) {
381 $this->displaycancel = (bool)$newvalue;
385 * Sets the displaytotalcount option
387 * If set to true then the total number of comments will be displayed
388 * when printing comments.
390 * @param bool $newvalue
392 public function set_displaytotalcount($newvalue = true) {
393 $this->displaytotalcount = (bool)$newvalue;
397 * Initialises the JavaScript that enchances the comment API.
399 * @param moodle_page $page The moodle page object that the JavaScript should be
400 * initialised for.
402 public function initialise_javascript(moodle_page $page) {
404 $options = new stdClass;
405 $options->client_id = $this->cid;
406 $options->commentarea = $this->commentarea;
407 $options->itemid = $this->itemid;
408 $options->page = 0;
409 $options->courseid = $this->courseid;
410 $options->contextid = $this->contextid;
411 $options->component = $this->component;
412 $options->notoggle = $this->notoggle;
413 $options->autostart = $this->autostart;
415 $page->requires->js_init_call('M.core_comment.init', array($options), true);
417 return true;
421 * Prepare comment code in html
422 * @param boolean $return
423 * @return string|void
425 public function output($return = true) {
426 global $PAGE, $OUTPUT;
427 static $template_printed;
429 $this->initialise_javascript($PAGE);
431 if (!empty(self::$nonjs)) {
432 // return non js comments interface
433 return $this->print_comments(self::$comment_page, $return, true);
436 $html = '';
438 // print html template
439 // Javascript will use the template to render new comments
440 if (empty($template_printed) && $this->can_view()) {
441 $html .= html_writer::tag('div', $this->template, array('style' => 'display:none', 'id' => 'cmt-tmpl'));
442 $template_printed = true;
445 if ($this->can_view()) {
446 // print commenting icon and tooltip
447 $html .= html_writer::start_tag('div', array('class' => 'mdl-left'));
448 $html .= html_writer::link($this->get_nojslink($PAGE), get_string('showcommentsnonjs'), array('class' => 'showcommentsnonjs'));
450 if (!$this->notoggle) {
451 // If toggling is enabled (notoggle=false) then print the controls to toggle
452 // comments open and closed
453 $countstring = '';
454 if ($this->displaytotalcount) {
455 $countstring = '('.$this->count().')';
457 $collapsedimage= 't/collapsed';
458 if (right_to_left()) {
459 $collapsedimage= 't/collapsed_rtl';
460 } else {
461 $collapsedimage= 't/collapsed';
463 $html .= html_writer::start_tag('a', array(
464 'class' => 'comment-link',
465 'id' => 'comment-link-'.$this->cid,
466 'href' => '#',
467 'role' => 'button',
468 'aria-expanded' => 'false')
470 $html .= $OUTPUT->pix_icon($collapsedimage, $this->linktext);
471 $html .= html_writer::tag('span', $this->linktext.' '.$countstring, array('id' => 'comment-link-text-'.$this->cid));
472 $html .= html_writer::end_tag('a');
475 $html .= html_writer::start_tag('div', array('id' => 'comment-ctrl-'.$this->cid, 'class' => 'comment-ctrl'));
477 if ($this->autostart) {
478 // If autostart has been enabled print the comments list immediatly
479 $html .= html_writer::start_tag('ul', array('id' => 'comment-list-'.$this->cid, 'class' => 'comment-list comments-loaded'));
480 $html .= html_writer::tag('li', '', array('class' => 'first'));
481 $html .= $this->print_comments(0, true, false);
482 $html .= html_writer::end_tag('ul'); // .comment-list
483 $html .= $this->get_pagination(0);
484 } else {
485 $html .= html_writer::start_tag('ul', array('id' => 'comment-list-'.$this->cid, 'class' => 'comment-list'));
486 $html .= html_writer::tag('li', '', array('class' => 'first'));
487 $html .= html_writer::end_tag('ul'); // .comment-list
488 $html .= html_writer::tag('div', '', array('id' => 'comment-pagination-'.$this->cid, 'class' => 'comment-pagination'));
491 if ($this->can_post()) {
492 // print posting textarea
493 $textareaattrs = array(
494 'name' => 'content',
495 'rows' => 2,
496 'id' => 'dlg-content-'.$this->cid,
497 'aria-label' => get_string('addcomment')
499 if (!$this->fullwidth) {
500 $textareaattrs['cols'] = '20';
501 } else {
502 $textareaattrs['class'] = 'fullwidth';
505 $html .= html_writer::start_tag('div', array('class' => 'comment-area'));
506 $html .= html_writer::start_tag('div', array('class' => 'db'));
507 $html .= html_writer::tag('textarea', '', $textareaattrs);
508 $html .= html_writer::end_tag('div'); // .db
510 $html .= html_writer::start_tag('div', array('class' => 'fd', 'id' => 'comment-action-'.$this->cid));
511 $html .= html_writer::link('#', get_string('savecomment'), array('id' => 'comment-action-post-'.$this->cid));
513 if ($this->displaycancel) {
514 $html .= html_writer::tag('span', ' | ');
515 $html .= html_writer::link('#', get_string('cancel'), array('id' => 'comment-action-cancel-'.$this->cid));
518 $html .= html_writer::end_tag('div'); // .fd
519 $html .= html_writer::end_tag('div'); // .comment-area
520 $html .= html_writer::tag('div', '', array('class' => 'clearer'));
523 $html .= html_writer::end_tag('div'); // .comment-ctrl
524 $html .= html_writer::end_tag('div'); // .mdl-left
525 } else {
526 $html = '';
529 if ($return) {
530 return $html;
531 } else {
532 echo $html;
537 * Return matched comments
539 * @param int $page
540 * @param str $sortdirection sort direction, ASC or DESC
541 * @return array
543 public function get_comments($page = '', $sortdirection = 'DESC') {
544 global $DB, $CFG, $USER, $OUTPUT;
545 if (!$this->can_view()) {
546 return false;
548 if (!is_numeric($page)) {
549 $page = 0;
551 $params = array();
552 $perpage = (!empty($CFG->commentsperpage))?$CFG->commentsperpage:15;
553 $start = $page * $perpage;
554 $ufields = user_picture::fields('u');
556 list($componentwhere, $component) = $this->get_component_select_sql('c');
557 if ($component) {
558 $params['component'] = $component;
561 $sortdirection = ($sortdirection === 'ASC') ? 'ASC' : 'DESC';
562 $sql = "SELECT $ufields, c.id AS cid, c.content AS ccontent, c.format AS cformat, c.timecreated AS ctimecreated
563 FROM {comments} c
564 JOIN {user} u ON u.id = c.userid
565 WHERE c.contextid = :contextid AND
566 c.commentarea = :commentarea AND
567 c.itemid = :itemid AND
568 $componentwhere
569 ORDER BY c.timecreated $sortdirection, c.id $sortdirection";
570 $params['contextid'] = $this->contextid;
571 $params['commentarea'] = $this->commentarea;
572 $params['itemid'] = $this->itemid;
574 $comments = array();
575 $formatoptions = array('overflowdiv' => true, 'blanktarget' => true);
576 $rs = $DB->get_recordset_sql($sql, $params, $start, $perpage);
577 foreach ($rs as $u) {
578 $c = new stdClass();
579 $c->id = $u->cid;
580 $c->content = $u->ccontent;
581 $c->format = $u->cformat;
582 $c->timecreated = $u->ctimecreated;
583 $c->strftimeformat = get_string('strftimerecentfull', 'langconfig');
584 $url = new moodle_url('/user/view.php', array('id'=>$u->id, 'course'=>$this->courseid));
585 $c->profileurl = $url->out(false); // URL should not be escaped just yet.
586 $c->fullname = fullname($u);
587 $c->time = userdate($c->timecreated, $c->strftimeformat);
588 $c->content = format_text($c->content, $c->format, $formatoptions);
589 $c->avatar = $OUTPUT->user_picture($u, array('size'=>18));
590 $c->userid = $u->id;
592 $candelete = $this->can_delete($c->id);
593 if (($USER->id == $u->id) || !empty($candelete)) {
594 $c->delete = true;
596 $comments[] = $c;
598 $rs->close();
600 if (!empty($this->plugintype)) {
601 // moodle module will filter comments
602 $comments = plugin_callback($this->plugintype, $this->pluginname, 'comment', 'display', array($comments, $this->comment_param), $comments);
605 return $comments;
609 * Returns an SQL fragment and param for selecting on component.
610 * @param string $alias
611 * @return array
613 protected function get_component_select_sql($alias = '') {
614 $component = $this->get_component();
615 if ($alias) {
616 $alias = $alias.'.';
618 if (empty($component)) {
619 $componentwhere = "{$alias}component IS NULL";
620 $component = null;
621 } else {
622 $componentwhere = "({$alias}component IS NULL OR {$alias}component = :component)";
624 return array($componentwhere, $component);
628 * Returns the number of comments associated with the details of this object
630 * @global moodle_database $DB
631 * @return int
633 public function count() {
634 global $DB;
635 if ($this->totalcommentcount === null) {
636 list($where, $component) = $this->get_component_select_sql();
637 $where .= ' AND itemid = :itemid AND commentarea = :commentarea AND contextid = :contextid';
638 $params = array(
639 'itemid' => $this->itemid,
640 'commentarea' => $this->commentarea,
641 'contextid' => $this->context->id,
643 if ($component) {
644 $params['component'] = $component;
647 $this->totalcommentcount = $DB->count_records_select('comments', $where, $params);
649 return $this->totalcommentcount;
653 * Returns HTML to display a pagination bar
655 * @global stdClass $CFG
656 * @global core_renderer $OUTPUT
657 * @param int $page
658 * @return string
660 public function get_pagination($page = 0) {
661 global $CFG, $OUTPUT;
662 $count = $this->count();
663 $perpage = (!empty($CFG->commentsperpage))?$CFG->commentsperpage:15;
664 $pages = (int)ceil($count/$perpage);
665 if ($pages == 1 || $pages == 0) {
666 return html_writer::tag('div', '', array('id' => 'comment-pagination-'.$this->cid, 'class' => 'comment-pagination'));
668 if (!empty(self::$nonjs)) {
669 // used in non-js interface
670 return $OUTPUT->paging_bar($count, $page, $perpage, $this->get_nojslink(), 'comment_page');
671 } else {
672 // return ajax paging bar
673 $str = '';
674 $str .= '<div class="comment-paging" id="comment-pagination-'.$this->cid.'">';
675 for ($p=0; $p<$pages; $p++) {
676 if ($p == $page) {
677 $class = 'curpage';
678 } else {
679 $class = 'pageno';
681 $str .= '<a href="#" class="'.$class.'" id="comment-page-'.$this->cid.'-'.$p.'">'.($p+1).'</a> ';
683 $str .= '</div>';
685 return $str;
689 * Add a new comment
691 * @global moodle_database $DB
692 * @param string $content
693 * @param int $format
694 * @return stdClass
696 public function add($content, $format = FORMAT_MOODLE) {
697 global $CFG, $DB, $USER, $OUTPUT;
698 if (!$this->can_post()) {
699 throw new comment_exception('nopermissiontocomment');
701 $now = time();
702 $newcmt = new stdClass;
703 $newcmt->contextid = $this->contextid;
704 $newcmt->commentarea = $this->commentarea;
705 $newcmt->itemid = $this->itemid;
706 $newcmt->component = !empty($this->component) ? $this->component : null;
707 $newcmt->content = $content;
708 $newcmt->format = $format;
709 $newcmt->userid = $USER->id;
710 $newcmt->timecreated = $now;
712 // This callback allow module to modify the content of comment, such as filter or replacement
713 plugin_callback($this->plugintype, $this->pluginname, 'comment', 'add', array(&$newcmt, $this->comment_param));
715 $cmt_id = $DB->insert_record('comments', $newcmt);
716 if (!empty($cmt_id)) {
717 $newcmt->id = $cmt_id;
718 $newcmt->strftimeformat = get_string('strftimerecentfull', 'langconfig');
719 $newcmt->fullname = fullname($USER);
720 $url = new moodle_url('/user/view.php', array('id' => $USER->id, 'course' => $this->courseid));
721 $newcmt->profileurl = $url->out();
722 $formatoptions = array('overflowdiv' => true, 'blanktarget' => true);
723 $newcmt->content = format_text($newcmt->content, $newcmt->format, $formatoptions);
724 $newcmt->avatar = $OUTPUT->user_picture($USER, array('size'=>16));
726 $commentlist = array($newcmt);
728 if (!empty($this->plugintype)) {
729 // Call the display callback to allow the plugin to format the newly added comment.
730 $commentlist = plugin_callback($this->plugintype,
731 $this->pluginname,
732 'comment',
733 'display',
734 array($commentlist, $this->comment_param),
735 $commentlist);
736 $newcmt = $commentlist[0];
738 $newcmt->time = userdate($newcmt->timecreated, $newcmt->strftimeformat);
740 // Trigger comment created event.
741 if (core_component::is_core_subsystem($this->component)) {
742 $eventclassname = '\\core\\event\\' . $this->component . '_comment_created';
743 } else {
744 $eventclassname = '\\' . $this->component . '\\event\comment_created';
746 if (class_exists($eventclassname)) {
747 $event = $eventclassname::create(
748 array(
749 'context' => $this->context,
750 'objectid' => $newcmt->id,
751 'other' => array(
752 'itemid' => $this->itemid
755 $event->trigger();
758 return $newcmt;
759 } else {
760 throw new comment_exception('dbupdatefailed');
765 * delete by context, commentarea and itemid
766 * @param stdClass|array $param {
767 * contextid => int the context in which the comments exist [required]
768 * commentarea => string the comment area [optional]
769 * itemid => int comment itemid [optional]
771 * @return boolean
773 public static function delete_comments($param) {
774 global $DB;
775 $param = (array)$param;
776 if (empty($param['contextid'])) {
777 return false;
779 $DB->delete_records('comments', $param);
780 return true;
784 * Delete page_comments in whole course, used by course reset
786 * @param stdClass $context course context
788 public static function reset_course_page_comments($context) {
789 global $DB;
790 $contexts = array();
791 $contexts[] = $context->id;
792 $children = $context->get_child_contexts();
793 foreach ($children as $c) {
794 $contexts[] = $c->id;
796 list($ids, $params) = $DB->get_in_or_equal($contexts);
797 $DB->delete_records_select('comments', "commentarea='page_comments' AND contextid $ids", $params);
801 * Delete a comment
803 * @param int $commentid
804 * @return bool
806 public function delete($commentid) {
807 global $DB, $USER;
808 $candelete = has_capability('moodle/comment:delete', $this->context);
809 if (!$comment = $DB->get_record('comments', array('id'=>$commentid))) {
810 throw new comment_exception('dbupdatefailed');
812 if (!($USER->id == $comment->userid || !empty($candelete))) {
813 throw new comment_exception('nopermissiontocomment');
815 $DB->delete_records('comments', array('id'=>$commentid));
816 // Trigger comment delete event.
817 if (core_component::is_core_subsystem($this->component)) {
818 $eventclassname = '\\core\\event\\' . $this->component . '_comment_deleted';
819 } else {
820 $eventclassname = '\\' . $this->component . '\\event\comment_deleted';
822 if (class_exists($eventclassname)) {
823 $event = $eventclassname::create(
824 array(
825 'context' => $this->context,
826 'objectid' => $commentid,
827 'other' => array(
828 'itemid' => $this->itemid
831 $event->add_record_snapshot('comments', $comment);
832 $event->trigger();
834 return true;
838 * Print comments
840 * @param int $page
841 * @param bool $return return comments list string or print it out
842 * @param bool $nonjs print nonjs comments list or not?
843 * @return string|void
845 public function print_comments($page = 0, $return = true, $nonjs = true) {
846 global $DB, $CFG, $PAGE;
848 if (!$this->can_view()) {
849 return '';
852 if (!(self::$comment_itemid == $this->itemid &&
853 self::$comment_context == $this->context->id &&
854 self::$comment_area == $this->commentarea &&
855 self::$comment_component == $this->component
856 )) {
857 $page = 0;
859 $comments = $this->get_comments($page);
861 $html = '';
862 if ($nonjs) {
863 $html .= html_writer::tag('h3', get_string('comments'));
864 $html .= html_writer::start_tag('ul', array('id' => 'comment-list-'.$this->cid, 'class' => 'comment-list'));
866 // Reverse the comments array to display them in the correct direction
867 foreach (array_reverse($comments) as $cmt) {
868 $html .= html_writer::tag('li', $this->print_comment($cmt, $nonjs), array('id' => 'comment-'.$cmt->id.'-'.$this->cid));
870 if ($nonjs) {
871 $html .= html_writer::end_tag('ul');
872 $html .= $this->get_pagination($page);
874 if ($nonjs && $this->can_post()) {
875 // Form to add comments
876 $html .= html_writer::start_tag('form', array('method' => 'post', 'action' => new moodle_url('/comment/comment_post.php')));
877 // Comment parameters
878 $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'contextid', 'value' => $this->contextid));
879 $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'action', 'value' => 'add'));
880 $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'area', 'value' => $this->commentarea));
881 $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'component', 'value' => $this->component));
882 $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'itemid', 'value' => $this->itemid));
883 $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'courseid', 'value' => $this->courseid));
884 $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'sesskey', 'value' => sesskey()));
885 $html .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => 'returnurl', 'value' => $PAGE->url));
886 // Textarea for the actual comment
887 $html .= html_writer::tag('textarea', '', array('name' => 'content', 'rows' => 2));
888 // Submit button to add the comment
889 $html .= html_writer::empty_tag('input', array('type' => 'submit', 'value' => get_string('submit')));
890 $html .= html_writer::end_tag('form');
892 if ($return) {
893 return $html;
894 } else {
895 echo $html;
900 * Returns an array containing comments in HTML format.
902 * @global core_renderer $OUTPUT
903 * @param stdClass $cmt {
904 * id => int comment id
905 * content => string comment content
906 * format => int comment text format
907 * timecreated => int comment's timecreated
908 * profileurl => string link to user profile
909 * fullname => comment author's full name
910 * avatar => string user's avatar
911 * delete => boolean does user have permission to delete comment?
913 * @param bool $nonjs
914 * @return array
916 public function print_comment($cmt, $nonjs = true) {
917 global $OUTPUT;
918 $patterns = array();
919 $replacements = array();
921 if (!empty($cmt->delete) && empty($nonjs)) {
922 $strdelete = get_string('deletecommentbyon', 'moodle', (object)['user' => $cmt->fullname, 'time' => $cmt->time]);
923 $deletelink = html_writer::start_tag('div', array('class'=>'comment-delete'));
924 $deletelink .= html_writer::start_tag('a', array('href' => '#', 'id' => 'comment-delete-'.$this->cid.'-'.$cmt->id,
925 'title' => $strdelete));
927 $deletelink .= $OUTPUT->pix_icon('t/delete', get_string('delete'));
928 $deletelink .= html_writer::end_tag('a');
929 $deletelink .= html_writer::end_tag('div');
930 $cmt->content = $deletelink . $cmt->content;
932 $patterns[] = '___picture___';
933 $patterns[] = '___name___';
934 $patterns[] = '___content___';
935 $patterns[] = '___time___';
936 $replacements[] = $cmt->avatar;
937 $replacements[] = html_writer::link($cmt->profileurl, $cmt->fullname);
938 $replacements[] = $cmt->content;
939 $replacements[] = $cmt->time;
941 // use html template to format a single comment.
942 return str_replace($patterns, $replacements, $this->template);
946 * Revoke validate callbacks
948 * @param stdClass $params addtionall parameters need to add to callbacks
950 protected function validate($params=array()) {
951 foreach ($params as $key=>$value) {
952 $this->comment_param->$key = $value;
954 $validation = plugin_callback($this->plugintype, $this->pluginname, 'comment', 'validate', array($this->comment_param), false);
955 if (!$validation) {
956 throw new comment_exception('invalidcommentparam');
961 * Returns true if the user is able to view comments
962 * @return bool
964 public function can_view() {
965 $this->validate();
966 return !empty($this->viewcap);
970 * Returns true if the user can add comments against this comment description
971 * @return bool
973 public function can_post() {
974 $this->validate();
975 return isloggedin() && !empty($this->postcap);
979 * Returns true if the user can delete this comment
980 * @param int $commentid
981 * @return bool
983 public function can_delete($commentid) {
984 $this->validate(array('commentid'=>$commentid));
985 return has_capability('moodle/comment:delete', $this->context);
989 * Returns the component associated with the comment.
991 * @return string
993 public function get_component() {
994 return $this->component;
998 * Do not call! I am a deprecated method because of the typo in my name.
999 * @deprecated since 2.9
1000 * @see comment::get_component()
1001 * @return string
1003 public function get_compontent() {
1004 return $this->get_component();
1008 * Returns the context associated with the comment
1009 * @return stdClass
1011 public function get_context() {
1012 return $this->context;
1016 * Returns the course id associated with the comment
1017 * @return int
1019 public function get_courseid() {
1020 return $this->courseid;
1024 * Returns the course module associated with the comment
1026 * @return stdClass
1028 public function get_cm() {
1029 return $this->cm;
1033 * Returns the item id associated with the comment
1035 * @return int
1037 public function get_itemid() {
1038 return $this->itemid;
1042 * Returns the comment area associated with the commentarea
1044 * @return stdClass
1046 public function get_commentarea() {
1047 return $this->commentarea;
1051 * Make the comments textarea fullwidth.
1053 * @since 2.8.1 + 2.7.4
1054 * @param bool $fullwidth
1056 public function set_fullwidth($fullwidth = true) {
1057 $this->fullwidth = (bool)$fullwidth;
1061 * Return the template.
1063 * @since 3.1
1064 * @return string
1066 public function get_template() {
1067 return $this->template;
1071 * Return the cid.
1073 * @since 3.1
1074 * @return string
1076 public function get_cid() {
1077 return $this->cid;
1081 * Return the link text.
1083 * @since 3.1
1084 * @return string
1086 public function get_linktext() {
1087 return $this->linktext;
1091 * Return no toggle.
1093 * @since 3.1
1094 * @return bool
1096 public function get_notoggle() {
1097 return $this->notoggle;
1101 * Return display total count.
1103 * @since 3.1
1104 * @return bool
1106 public function get_displaytotalcount() {
1107 return $this->displaytotalcount;
1111 * Return display cancel.
1113 * @since 3.1
1114 * @return bool
1116 public function get_displaycancel() {
1117 return $this->displaycancel;
1121 * Return fullwidth.
1123 * @since 3.1
1124 * @return bool
1126 public function get_fullwidth() {
1127 return $this->fullwidth;
1131 * Return autostart.
1133 * @since 3.1
1134 * @return bool
1136 public function get_autostart() {
1137 return $this->autostart;
1143 * Comment exception class
1145 * @package core
1146 * @copyright 2010 Dongsheng Cai {@link http://dongsheng.org}
1147 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1149 class comment_exception extends moodle_exception {