ab154fbd8fe7fcc33522291edc59c460c57a8de2
[moodle.git] / comment / lib.php
1 <?php
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/>.
18 /**
19  * Comment is helper class to add/delete comments anywhere in moodle
20  *
21  * @package   comment
22  * @copyright 2010 Dongsheng Cai <dongsheng@moodle.com>
23  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 class comment {
27     /**
28      * @var integer
29      */
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;
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;
57     private $courseid;
58     /**
59      * course module object, only be used to help find pluginname automatically
60      * if pluginname is specified, it won't be used at all
61      * @var string
62      */
63     private $cm;
64     private $plugintype;
65     /**
66      * When used in module, it is recommended to use it
67      * @var string
68      */
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;
83     // static variable will be used by non-js comments UI
84     private static $nonjs = false;
85     private static $comment_itemid = null;
86     private static $comment_context = null;
87     private static $comment_area = null;
88         private static $comment_page = null;
89     /**
90      * Construct function of comment class, initialise
91      * class members
92      * @param object $options
93      */
94     public function __construct($options) {
95         global $CFG, $DB;
97         if (empty($CFG->commentsperpage)) {
98             $CFG->commentsperpage = 15;
99         }
101         $this->viewcap = false;
102         $this->postcap = false;
104         // setup client_id
105         if (!empty($options->client_id)) {
106             $this->cid = $options->client_id;
107         } else {
108             $this->cid = uniqid();
109         }
111         // setup context
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         }
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;
128         } else {
129             $this->courseid = SITEID;
130         }
132         if (!empty($options->pluginname)) {
133             $this->pluginname = $options->pluginname;
134         }
136         // setup coursemodule
137         if (!empty($options->cm)) {
138             $this->cm = $options->cm;
139         } else {
140             $this->cm = null;
141         }
143         // setup commentarea
144         if (!empty($options->area)) {
145             $this->commentarea = $options->area;
146         }
148         // setup itemid
149         if (!empty($options->itemid)) {
150             $this->itemid = $options->itemid;
151         } else {
152             $this->itemid = 0;
153         }
155         // setup env
156         if (!empty($options->env)) {
157             $this->env = $options->env;
158         } else {
159             $this->env = '';
160         }
162         // setup customized linktext
163         if (!empty($options->linktext)) {
164             $this->linktext = $options->linktext;
165         } else {
166             $this->linktext = get_string('comments');
167         }
168         // setting post and view permissions
169         $this->check_permissions();
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         }
182         $this->setup_plugin();
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;
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>
199 EOD;
200         if (!empty($this->plugintype)) {
201             $this->template = plugin_callback($this->plugintype, $this->pluginname, FEATURE_COMMENT, 'template', $this->args, $this->template);
202         }
204         unset($options);
205     }
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);
216                 self::$comment_page    = optional_param('comment_page',    '', PARAM_INT);
217         self::$comment_area    = optional_param('comment_area',    '', PARAM_ALPHAEXT);
219         $PAGE->requires->string_for_js('addcomment', 'moodle');
220         $PAGE->requires->string_for_js('deletecomment', 'moodle');
221         $PAGE->requires->string_for_js('comments', 'moodle');
222     }
224     /**
225      * Setup plugin type and plugin name
226      */
227     private function setup_plugin() {
228         global $DB;
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         }
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         }
246         if ($this->context->contextlevel == CONTEXT_MODULE && $this->env != 'block_comments') {
247             $this->plugintype = 'mod';
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             }
257         }
258     }
260     /**
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
265      */
266     private function check_permissions() {
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)) {
271             $permissions = plugin_callback($this->plugintype, $this->pluginname, FEATURE_COMMENT, 'permissions', $this->args, array('post'=>true, 'view'=>true));
272             $this->postcap = $this->postcap && $permissions['post'];
273             $this->viewcap = $this->viewcap && $permissions['view'];
274         }
275     }
277     /**
278      * Prepare comment code in html
279      * @param  boolean $return
280      * @return mixed
281      */
282     public function output($return = true) {
283         global $PAGE, $OUTPUT;
284                 static $template_printed;
286         $this->link = $PAGE->url;
287         $murl = new moodle_url($this->link);
288         $murl->remove_params('nonjscomment');
289         $murl->param('nonjscomment', 'true');
290         $murl->param('comment_itemid', $this->itemid);
291         $murl->param('comment_context', $this->context->id);
292         $murl->param('comment_area', $this->commentarea);
293         $murl->remove_params('comment_page');
294         $this->link = $murl->out();
296         $options = new stdclass;
297         $options->client_id = $this->cid;
298         $options->commentarea = $this->commentarea;
299         $options->itemid = $this->itemid;
300         $options->page   = 0;
301         $options->courseid = $this->courseid;
302         $options->contextid = $this->contextid;
303         $options->env = $this->env;
304         if ($this->env == 'block_comments') {
305             $options->autostart = true;
306             $options->notoggle = true;
307         }
309         $PAGE->requires->js_init_call('M.core_comment.init', array($options), true);
311         if (!empty(self::$nonjs)) {
312             // return non js comments interface
313             return $this->print_comments(self::$comment_page, $return, true);
314         }
316         $strsubmit = get_string('savecomment');
317         $strcancel = get_string('cancel');
318         $strshowcomments = get_string('showcommentsnonjs');
319         $sesskey = sesskey();
320         $html = '';
321         // print html template
322         // Javascript will use the template to render new comments
323         if (empty($template_printed) && !empty($this->viewcap)) {
324             $html .= '<div style="display:none" id="cmt-tmpl">' . $this->template . '</div>';
325             $template_printed = true;
326         }
328         if (!empty($this->viewcap)) {
329             // print commenting icon and tooltip
330             $icon = $OUTPUT->pix_url('t/collapsed');
331             $html .= <<<EOD
332 <div class="mdl-left">
333 <noscript>
334 <a href="{$this->link}">{$strshowcomments}</a>
335 </noscript>
336 <a id="comment-link-{$this->cid}" class="comment-link" href="#">
337     <img id="comment-img-{$this->cid}" src="$icon" alt="{$this->linktext}" title="{$this->linktext}" />
338     <span id="comment-link-text-{$this->cid}">{$this->linktext} {$this->count}</span>
339 </a>
340 <div id="comment-ctrl-{$this->cid}" class="comment-ctrl">
341     <ul id="comment-list-{$this->cid}" class="comment-list">
342 EOD;
343             // in comments block, we print comments list right away
344             if ($this->env == 'block_comments') {
345                 $html .= $this->print_comments(0, true, false);
346                 $html .= '</ul>';
347                 $html .= $this->get_pagination(0);
348             } else {
349                 $html .= <<<EOD
350     </ul>
351     <div id="comment-pagination-{$this->cid}" class="comment-pagination"></div>
352 EOD;
353             }
355             // print posting textarea
356             if (!empty($this->postcap)) {
357                 $html .= <<<EOD
358 <div class='comment-area'>
359     <div class="bd">
360         <textarea name="content" rows="2" id="dlg-content-{$this->cid}"></textarea>
361     </div>
362     <div class="fd" id="comment-action-{$this->cid}">
363         <a href="#" id="comment-action-post-{$this->cid}"> {$strsubmit} </a>
364 EOD;
365         if ($this->env != 'block_comments') {
366             $html .= <<<EOD
367         <span> | </span>
368         <a href="#" id="comment-action-cancel-{$this->cid}"> {$strcancel} </a>
369 EOD;
370         }
372         $html .= <<<EOD
373     </div>
374 </div>
375 <div class="clearer"></div>
376 EOD;
377             }
379             $html .= <<<EOD
380 </div><!-- end of comment-ctrl -->
381 </div>
382 EOD;
383         } else {
384             $html = '';
385         }
387         if ($return) {
388             return $html;
389         } else {
390             echo $html;
391         }
392     }
394     /**
395      * Return matched comments
396      *
397      * @param  int $page
398      * @return mixed
399      */
400     public function get_comments($page = '') {
401         global $DB, $CFG, $USER, $OUTPUT;
402         if (empty($this->viewcap)) {
403             return false;
404         }
405         if (!is_numeric($page)) {
406             $page = 0;
407         }
408         $this->page = $page;
409         $params = array();
410         $start = $page * $CFG->commentsperpage;
411         $ufields = user_picture::fields('u', array('username'));
412         $sql = "SELECT $ufields, c.id AS cid, c.content AS ccontent, c.format AS cformat, c.timecreated AS ctimecreated
413                   FROM {comments} c
414                   JOIN {user} u ON u.id = c.userid
415                  WHERE c.contextid = :contextid AND c.commentarea = :commentarea AND c.itemid = :itemid
416               ORDER BY c.timecreated DESC";
417         $params['contextid'] = $this->contextid;
418         $params['commentarea'] = $this->commentarea;
419         $params['itemid'] = $this->itemid;
421         $comments = array();
422         $candelete = has_capability('moodle/comment:delete', $this->context);
423         $rs = $DB->get_recordset_sql($sql, $params, $start, $CFG->commentsperpage);
424         foreach ($rs as $u) {
425             $c = new object();
426             $c->id          = $u->cid;
427             $c->content     = $u->ccontent;
428             $c->format      = $u->cformat;
429             $c->timecreated = $u->ctimecreated;
430             $url = new moodle_url('/user/view.php', array('id'=>$u->id, 'course'=>$this->courseid));
431             $c->username = $u->username;
432             $c->profileurl = $url;
433             $c->fullname = fullname($u);
434             $c->time = userdate($c->timecreated, get_string('strftimerecent', 'langconfig'));
435             $c->content = format_text($c->content, $c->format);
437             $c->avatar = $OUTPUT->user_picture($u, array('size'=>18));
438             if (($USER->id == $u->id) || !empty($candelete)) {
439                 $c->delete = true;
440             }
441             $comments[] = $c;
442         }
443         $rs->close();
445         if (!empty($this->plugintype)) {
446             // moodle module will filter comments
447             $comments = plugin_callback($this->plugintype, $this->pluginname, FEATURE_COMMENT, 'display', array($comments, $this->args), $comments);
448         }
450         return $comments;
451     }
453     public function count() {
454         global $DB;
455         if ($count = $DB->count_records('comments', array('itemid'=>$this->itemid, 'commentarea'=>$this->commentarea, 'contextid'=>$this->context->id))) {
456             return $count;
457         } else {
458             return 0;
459         }
460     }
462     public function get_pagination($page = 0) {
463         global $DB, $CFG, $OUTPUT;
464         $count = $this->count();
465         $pages = (int)ceil($count/$CFG->commentsperpage);
466         if ($pages == 1 || $pages == 0) {
467             return '';
468         }
469         if (!empty(self::$nonjs)) {
470             // used in non-js interface
471             return $OUTPUT->paging_bar($count, $page, $CFG->commentsperpage, $this->link, 'comment_page');
472         } else {
473             // return ajax paging bar
474             $str = '';
475             $str .= '<div class="comment-paging" id="comment-pagination-'.$this->cid.'">';
476             for ($p=0; $p<$pages; $p++) {
477                 if ($p == $page) {
478                     $class = 'curpage';
479                 } else {
480                     $class = 'pageno';
481                 }
482                 $str .= '<a href="#" class="'.$class.'" id="comment-page-'.$this->cid.'-'.$p.'">'.($p+1).'</a> ';
483             }
484             $str .= '</div>';
485         }
486         return $str;
487     }
489     /**
490      * Add a new comment
491      * @param string $content
492      * @return mixed
493      */
494     public function add($content, $format = FORMAT_MOODLE) {
495         global $CFG, $DB, $USER, $OUTPUT;
496         if (empty($this->postcap)) {
497             throw new comment_exception('nopermissiontocomment');
498         }
499         $now = time();
500         $newcmt = new stdclass;
501         $newcmt->contextid    = $this->contextid;
502         $newcmt->commentarea  = $this->commentarea;
503         $newcmt->itemid       = $this->itemid;
504         $newcmt->content      = $content;
505         $newcmt->format       = $format;
506         $newcmt->userid       = $USER->id;
507         $newcmt->timecreated  = $now;
509         if (!empty($this->plugintype)) {
510             // moodle module will check content
511             $ret = plugin_callback($this->plugintype, $this->pluginname, FEATURE_COMMENT, 'add', array(&$newcmt, $this->args), true);
512             if (!$ret) {
513                 throw new comment_exception('modulererejectcomment');
514             }
515         }
517         $cmt_id = $DB->insert_record('comments', $newcmt);
518         if (!empty($cmt_id)) {
519             $newcmt->id = $cmt_id;
520             $newcmt->time = userdate($now, get_string('strftimerecent', 'langconfig'));
521             $newcmt->username = $USER->username;
522             $newcmt->fullname = fullname($USER);
523             $url = new moodle_url('/user/view.php', array('id'=>$USER->id, 'course'=>$this->courseid));
524             $newcmt->profileurl = $url->out();
525             $newcmt->content = format_text($newcmt->content, $format);
526             $newcmt->avatar = $OUTPUT->user_picture($USER, array('size'=>16));
527             return $newcmt;
528         } else {
529             throw new comment_exception('dbupdatefailed');
530         }
531     }
533     /**
534      * delete by context, commentarea and itemid
535     * @param object $param {
536     *            contextid => int the context in which the comments exist [required]
537     *            commentarea => string the comment area [optional]
538     *            itemid => int comment itemid [optional]
539     * }
540      * @return boolean
541      */
542     public function delete_comments($param) {
543         global $DB;
544         $param = (array)$param;
545         if (empty($param['contextid'])) {
546             return false;
547         }
548         $DB->delete_records('comments', $param);
549         return true;
550     }
552     /**
553      * Delete a comment
554      * @param  int $commentid
555      * @return mixed
556      */
557     public function delete($commentid) {
558         global $DB, $USER;
559         $candelete = has_capability('moodle/comment:delete', $this->context);
560         if (!$comment = $DB->get_record('comments', array('id'=>$commentid))) {
561             throw new comment_exception('dbupdatefailed');
562         }
563         if (!($USER->id == $comment->userid || !empty($candelete))) {
564             throw new comment_exception('nopermissiontocomment');
565         }
566         $DB->delete_records('comments', array('id'=>$commentid));
567         return true;
568     }
570     /**
571      * Print comments
572      * @param int $page
573      * @param boolean $return return comments list string or print it out
574      * @param boolean $nonjs print nonjs comments list or not?
575      * @return mixed
576      */
577     public function print_comments($page = 0, $return = true, $nonjs = true) {
578         global $DB, $CFG, $PAGE;
579         $html = '';
580         if (!(self::$comment_itemid == $this->itemid &&
581             self::$comment_context == $this->context->id &&
582             self::$comment_area == $this->commentarea)) {
583             $page = 0;
584         }
585         $comments = $this->get_comments($page);
587         $html = '';
588         if ($nonjs) {
589             $html .= '<h3>'.get_string('comments').'</h3>';
590             $html .= "<ul id='comment-list-$this->cid' class='comment-list'>";
591         }
592         $results = array();
593         $list = '';
595         foreach ($comments as $cmt) {
596             $list = '<li id="comment-'.$cmt->id.'-'.$this->cid.'">'.$this->print_comment($cmt, $nonjs).'</li>' . $list;
597         }
598         $html .= $list;
599         if ($nonjs) {
600             $html .= '</ul>';
601             $html .= $this->get_pagination($page);
602         }
603         $sesskey = sesskey();
604         $returnurl = $PAGE->url;
605         $strsubmit = get_string('submit');
606         if ($nonjs) {
607         $html .= <<<EOD
608 <form method="POST" action="{$CFG->wwwroot}/comment/comment_post.php">
609 <textarea name="content" rows="2"></textarea>
610 <input type="hidden" name="contextid" value="$this->contextid" />
611 <input type="hidden" name="action" value="add" />
612 <input type="hidden" name="area" value="$this->commentarea" />
613 <input type="hidden" name="itemid" value="$this->itemid" />
614 <input type="hidden" name="courseid" value="{$this->courseid}" />
615 <input type="hidden" name="sesskey" value="{$sesskey}" />
616 <input type="hidden" name="returnurl" value="{$returnurl}" />
617 <input type="submit" value="{$strsubmit}" />
618 </form>
619 EOD;
620         }
621         if ($return) {
622             return $html;
623         } else {
624             echo $html;
625         }
626     }
628     public function print_comment($cmt, $nonjs = true) {
629         global $OUTPUT;
630         $patterns = array();
631         $replacements = array();
633         if (!empty($cmt->delete) && empty($nonjs)) {
634             $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;
635             // add the button
636         }
637         $patterns[] = '___picture___';
638         $patterns[] = '___name___';
639         $patterns[] = '___content___';
640         $patterns[] = '___time___';
641         $replacements[] = $cmt->avatar;
642         $replacements[] = html_writer::link($cmt->profileurl, $cmt->fullname);
643         $replacements[] = $cmt->content;
644         $replacements[] = userdate($cmt->timecreated, get_string('strftimerecent', 'langconfig'));
646         // use html template to format a single comment.
647         return str_replace($patterns, $replacements, $this->template);
648     }
651 class comment_exception extends moodle_exception {
652     public $message;
653     function __construct($errorcode) {
654         $this->errorcode = $errorcode;
655         $this->message = get_string($errorcode, 'error');
656     }