Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Comment API: Difference between revisions

From MoodleDocs
mNo edit summary
(ja link)
 
(15 intermediate revisions by 7 users not shown)
Line 1: Line 1:
==Objectives==
{{Moodle 2.0}}==Objectives==


The goals of comments 2.0:
The goals of Comment API:


* Manage comments centrally
* Manage comments centrally
* Use a consistent approach for all comments throughout Moodle
* Use a consistent approach for all comments throughout Moodle
* Easily integrate comments 2.0 with existing modules
* Easily integrate Comment API with existing modules
* Works no matter Javascript is enabled or not
* Works no matter Javascript is enabled or not


Line 11: Line 11:
==Overview==
==Overview==


The comments 2.0 provides APIs to:
Comment API provides following functionalities:
# Add comments
# Add comments
# Manage comments
# Manage comments
# Delete comments
# Delete comments


And provides a fancy ajax interface to add/delete comments without loading a new page.
And provides a fancy ajax interface to add/delete comments without reloading page.


==Comments database table==
==Comment API database table==


{| class="nicetable"
{| class="wikitable"
|-
|-
! Field
! Field
Line 68: Line 68:
|}
|}


==Use Comments API==
==Use Comment API==


===Add an option to format_text function===
===Add an option to format_text function===
Line 76: Line 76:
For example, using the following code in the forum module will add a comment icon to every post:
For example, using the following code in the forum module will add a comment icon to every post:


<code php>
<syntaxhighlight lang="php">
$to = new stdclass;
$cmt = new stdclass;
$cmt->contextid = $modcontext->id;
$cmt->contextid = $modcontext->id;
$cmt->area      = 'format_post';
$cmt->area      = 'format_post';
Line 83: Line 83:
$options->comments = $cmt;
$options->comments = $cmt;
echo format_text($post->message, $post->messageformat, $options, $course->id)."<hr />";
echo format_text($post->message, $post->messageformat, $options, $course->id)."<hr />";
</code>
</syntaxhighlight>


===Use comment class===
===Use comment class===
To use Comments API elsewhere, using following code:
To use Comment API elsewhere, using following code:
<code php>
<syntaxhighlight lang="php">
$options->area    = 'database_entry';
$options->area    = 'database_entry';
$options->context = $context;
$options->context = $context;
$options->itemid  = $record->id;
$options->itemid  = $record->id;
$options->component = 'mod_data';
$options->showcount = true;
$options->showcount = true;
$comment = new comment($options);
$comment = new comment($options);
$comment->output(false);
$comment->output(false);
</code>
</syntaxhighlight>


==Comments API overview==
==Comment API overview==


Generally speaking, only two functions you need to know to get comments 2.0 worked:
Generally speaking, only two functions you need to know to get comment API worked:
# Use comment::init to initialize comments 2.0
# Use comment::init to initialize Comment API
# Use $comment->output to display comments
# Use $comment->output to display comments


Line 129: Line 130:


==Javascript API==
==Javascript API==
Comments 2.0 implemented a YUI3 module M.core_comment to deal with the communication between browsers and moodle.
Comment API implemented a YUI3 module M.core_comment to deal with the communication between browsers and moodle.
It can be found in comment/comment.js
It can be found in comment/comment.js


Line 135: Line 136:


== Moodle modules callback ==
== Moodle modules callback ==
Comments API allows modules/blocks/blog to how comments display.
Comment API allows modules/blocks/blog to decide how comments display.
 
=== Data validation ===
This callback method is required, it must be implemented. Otherwise, new comment will be rejected by default.
Plugins must implement pluginname_comment_validate callback to validate comments parameters, it must return true to pass validation.


===Permission control===
===Permission control===
Modules can implement a function named '''modname_comment_permissions''' to control post and view permission.
Modules must implement function '''pluginname_comment_permissions''' to return post and view permission.


Blocks need to overwrite '''comment_permissions''' function of block_base.
Blocks need to overwrite '''blockname_comment_permissions''' function of block_base.


Blog need to implement '''blog_comment_permissions''' function.
Blog need to implement '''blog_comment_permissions''' function.
Line 148: Line 153:
=== Check new added comment ===
=== Check new added comment ===
The callback function allows you to change the comment content before inserting into database or reject this comment.
The callback function allows you to change the comment content before inserting into database or reject this comment.
It takes two arguments, the comment object which contains comment details, and $params which contains context and course information.


Modules can implement a function named '''modname_comment_add'''.
Modules can implement a function named '''modname_comment_add'''.


Blocks need to overwrite '''comment_add''' function.
Blocks need to overwrite '''blockname_comment_add''' function.


Blog need to implement '''blog_comment_add''' function.
Blog need to implement '''blog_comment_add''' function.
This function should return a boolean value.


=== Filter/format comments ===
=== Filter/format comments ===
This callback allows modules check/format comments when user request to display comments.
This callback allows modules check/format comments when user request to display comments.


Modules can implement a function named '''modname_comment_display'''.
It takes the same arguments as pluginname_comment_add


Blocks need to overwrite '''comment_display''' function.
Modules can implement a function named '''pluginname_comment_display'''.
 
Blocks need to overwrite '''blockname_comment_display''' function.


Blog need to implement '''blog_comment_display''' function.
Blog need to implement '''blog_comment_display''' function.


It will return the comment object.


=== Define a comment template ===
=== Define a comment template ===
Modules can implement a function named '''modname_comment_template''', which allow modules define a comment template.
Modules can implement a function named '''pluginname_comment_template''', which allow modules define a comment template.
The template must have 4 embedding variables, ___id___, ___content___, ___time___, ___name___, they will be replaced with html id, comments content, comment time and commenter name
The template must have 4 embedding variables, ___id___, ___content___, ___time___, ___name___, they will be replaced with html id, comments content, comment time and commenter name
== Backup and Restore ==
Comments will automatically be included in the activity/course backups and restored provided the itemids can be updated during the restore process. To do this either:
* do not use item ids and rely just on the context
* make the commentarea the same as one of the mappings in the restore (set_mapping); or
* override the function "get_comment_mapping_itemname" in the restore activity class
If you do not do one of these the comments will be silently ignored on restore.


==See also==
==See also==
* MDL-19118 - Comments 2.0 issue
* [[Core APIs]]
* MDL-19118 - Comment API issue
 
[[Category:API]]
 
[[ja:コメントAPI]]

Latest revision as of 15:08, 19 May 2023

Moodle 2.0

Objectives

The goals of Comment API:

  • Manage comments centrally
  • Use a consistent approach for all comments throughout Moodle
  • Easily integrate Comment API with existing modules
  • Works no matter Javascript is enabled or not


Overview

Comment API provides following functionalities:

  1. Add comments
  2. Manage comments
  3. Delete comments

And provides a fancy ajax interface to add/delete comments without reloading page.

Comment API database table

Field Type Default Info
id int(10) auto-incrementing The unique ID for this comment.
userid int(10) who wrote this comment
contextid int(10) The context id defined in context table - identifies the instance of plugin owning the comment.
itemid int(10) Some plugin specific item id (eg. forum post, blog entry or assignment submission)
commentarea int(10) for example, in user profile, you can comment user's description or interests, but they share the same itemid(==userid), we need comment_area to separate them
timecreated int(10)
timemodified int(10)
content text content of comment

Use Comment API

Add an option to format_text function

Using this format_text function will add a comment icon automatically at the end of the text:

For example, using the following code in the forum module will add a comment icon to every post:

$cmt = new stdclass;
$cmt->contextid = $modcontext->id;
$cmt->area      = 'format_post';
$cmt->itemid    = $post->id;
$options->comments = $cmt;
echo format_text($post->message, $post->messageformat, $options, $course->id)."<hr />";

Use comment class

To use Comment API elsewhere, using following code:

$options->area    = 'database_entry';
$options->context = $context;
$options->itemid  = $record->id;
$options->component = 'mod_data';
$options->showcount = true;
$comment = new comment($options);
$comment->output(false);

Comment API overview

Generally speaking, only two functions you need to know to get comment API worked:

  1. Use comment::init to initialize Comment API
  2. Use $comment->output to display comments

The comment class has been implemented in comment/lib.php.

class comment()

__construct($contextid, $comment_area, $itemid))

Initialize class members

init()

It is a static function used to initialize comments, setting up languages, which must be called before html head printed

output($return = false)

Will print the html snippet for commenting interface, if set $return as true, it will return html string instead of printing out.

print_comments($params = array())

Used by non-javascript comment interface, will print a list of comments.

add($content)

Public instance funciton, add a comment to database, used in comment/comment_ajax.php

count()

Counting the number of comments

delete($id)

Delete a comment from database, used in comment/comment_ajax.php

delete_comments

Delete all comments in a specific contexts (like all comments belonging to a forum post)

Javascript API

Comment API implemented a YUI3 module M.core_comment to deal with the communication between browsers and moodle. It can be found in comment/comment.js

Call M.core_comment.init will create an instance of CommentHelper class. You don't need to make any calls to this instance, it simply works out of box.

Moodle modules callback

Comment API allows modules/blocks/blog to decide how comments display.

Data validation

This callback method is required, it must be implemented. Otherwise, new comment will be rejected by default. Plugins must implement pluginname_comment_validate callback to validate comments parameters, it must return true to pass validation.

Permission control

Modules must implement function pluginname_comment_permissions to return post and view permission.

Blocks need to overwrite blockname_comment_permissions function of block_base.

Blog need to implement blog_comment_permissions function.

This function will return an array: array('post'=>true, 'view'=>true)

Check new added comment

The callback function allows you to change the comment content before inserting into database or reject this comment.

It takes two arguments, the comment object which contains comment details, and $params which contains context and course information.

Modules can implement a function named modname_comment_add.

Blocks need to overwrite blockname_comment_add function.

Blog need to implement blog_comment_add function.

This function should return a boolean value.

Filter/format comments

This callback allows modules check/format comments when user request to display comments.

It takes the same arguments as pluginname_comment_add

Modules can implement a function named pluginname_comment_display.

Blocks need to overwrite blockname_comment_display function.

Blog need to implement blog_comment_display function.

It will return the comment object.

Define a comment template

Modules can implement a function named pluginname_comment_template, which allow modules define a comment template. The template must have 4 embedding variables, ___id___, ___content___, ___time___, ___name___, they will be replaced with html id, comments content, comment time and commenter name

Backup and Restore

Comments will automatically be included in the activity/course backups and restored provided the itemids can be updated during the restore process. To do this either:

  • do not use item ids and rely just on the context
  • make the commentarea the same as one of the mappings in the restore (set_mapping); or
  • override the function "get_comment_mapping_itemname" in the restore activity class

If you do not do one of these the comments will be silently ignored on restore.

See also