Skip to content

Commit 0f3cf05

Browse files
author
“Filippo”
committed
[docs] Comment API
1 parent 3504e0b commit 0f3cf05

File tree

3 files changed

+193
-1
lines changed

3 files changed

+193
-1
lines changed

‎data/migratedPages.yml

+3
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,9 @@ Coding:
9797
Coding_style:
9898
- filePath: "/general/development/policies/codingstyle/index.md"
9999
slug: "/general/development/policies/codingstyle"
100+
Comment_API:
101+
- filePath: "/docs/apis/core/comment/index.md"
102+
slug: "/docs/apis/core/comment/"
100103
Communication_Between_Components:
101104
- filePath: "/general/development/policies/component-communication/index.md"
102105
slug: "/general/development/policies/component-communication"

‎docs/apis.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ The [Check API](./apis/subsystems/check/index.md) allows you to add security, pe
9090

9191
### Comment API (comment)
9292

93-
The [Comment API](https://docs.moodle.org/dev/Comment_API) allows you to save and retrieve user comments, so that you can easily add commenting to any of your code.
93+
The [Comment API](./api/core/comment) allows you to save and retrieve user comments, so that you can easily add commenting to any of your code.
9494

9595
### Competency API (competency)
9696

‎docs/apis/core/comment/index.md

+189
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: Comment API
3+
tags:
4+
- API
5+
---
6+
import { Since } from '@site/src/components';
7+
8+
<Since versions={["2.0"]} />
9+
10+
## Objectives
11+
12+
The goals of Comment API:
13+
14+
- Manage comments centrally
15+
- Use a consistent approach for all comments throughout Moodle
16+
- Easily integrate Comment API with existing modules
17+
- Works no matter JavaScript is enabled or not
18+
19+
## Overview
20+
21+
Comment API provides following functionalities:
22+
23+
1. Add comments
24+
1. Manage comments
25+
1. Delete comments
26+
27+
And provides a fancy ajax interface to add/delete comments without reloading page.
28+
29+
## Comment API database table
30+
31+
| Field | Type | Default | Info |
32+
| --- | --- | --- | --- |
33+
| id | int(10) | auto-incrementing | The unique ID for this comment. |
34+
| userid | int(10) | | who wrote this comment |
35+
| contextid | int(10) | | The context id defined in context table - identifies the instance of plugin owning the comment. |
36+
| itemid | int(10) | | Some plugin specific item id (eg. forum post, blog entry or assignment submission) |
37+
| 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 |
38+
| timecreated | int(10) | | |
39+
| timemodified | int(10) | | |
40+
| content | text | | content of comment |
41+
42+
## Use Comment API
43+
44+
### Add an option to format_text function
45+
46+
Using this `format_text` function will add a comment icon automatically at the end of the text:
47+
48+
For example, using the following code in the forum module will add a comment icon to every post:
49+
50+
```php
51+
$cmt = new stdclass;
52+
$cmt->contextid = $modcontext->id;
53+
$cmt->area = 'format_post';
54+
$cmt->itemid = $post->id;
55+
$options->comments = $cmt;
56+
echo format_text($post->message, $post->messageformat, $options, $course->id)."<hr />";
57+
```
58+
59+
### Use comment class
60+
61+
To use Comment API elsewhere, using following code:
62+
63+
```php
64+
$options->area = 'database_entry';
65+
$options->context = $context;
66+
$options->itemid = $record->id;
67+
$options->component = 'mod_data';
68+
$options->showcount = true;
69+
$comment = new comment($options);
70+
$comment->output(false);
71+
```
72+
73+
## Comment API overview
74+
75+
Generally speaking, only two functions you need to know to get comment API worked:
76+
77+
1. Use `comment::init` to initialize Comment API
78+
1. Use `$comment->output` to display comments
79+
80+
The comment class has been implemented in `comment/lib.php`.
81+
82+
### class comment()
83+
84+
#### __construct($contextid, $comment_area, $itemid))
85+
86+
Initialize class members.
87+
88+
#### init()
89+
90+
It is a static function used to initialize comments, setting up languages, which must be called before html head printed.
91+
92+
#### output($return = false)
93+
94+
Will print the html snippet for commenting interface, if set `$return` as true, it will return html string instead of printing out.
95+
96+
#### print_comments($params = array())
97+
98+
Used by non-JavaScript comment interface, will print a list of comments.
99+
100+
#### add($content)
101+
102+
Public instance funciton, add a comment to database, used in `comment/comment_ajax.php`.
103+
104+
#### count()
105+
106+
Counting the number of comments.
107+
108+
#### delete($id)
109+
110+
Delete a comment from database, used in `comment/comment_ajax.php`
111+
112+
#### delete_comments
113+
114+
Delete all comments in a specific contexts (like all comments belonging to a forum post).
115+
116+
## JavaScript API
117+
118+
Comment API implemented a YUI3 module M.core_comment to deal with the communication between browsers and moodle.
119+
It can be found in `comment/comment.js`.
120+
121+
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.
122+
123+
## Moodle modules callback
124+
125+
Comment API allows `modules/blocks/blog` to decide how comments display.
126+
127+
### Data validation
128+
129+
This callback method is required, it must be implemented. Otherwise, new comment will be rejected by default.
130+
Plugins must implement `pluginname_comment_validate` callback to validate comments parameters, it must return true to pass validation.
131+
132+
### Permission control
133+
134+
Modules must implement function `pluginname_comment_permissions` to return post and view permission.
135+
136+
Blocks need to overwrite `blockname_comment_permissions` function of block_base.
137+
138+
Blog need to implement `blog_comment_permissions` function.
139+
140+
This function will return an array: `array('post'=>true, 'view'=>true)`.
141+
142+
### Check new added comment
143+
144+
The callback function allows you to change the comment content before inserting into database or reject this comment.
145+
146+
It takes two arguments, the comment object which contains comment details, and $params which contains context and course information.
147+
148+
Modules can implement a function named `modname_comment_add`.
149+
150+
Blocks need to overwrite `blockname_comment_add` function.
151+
152+
Blog need to implement `blog_comment_add` function.
153+
154+
This function should return a boolean value.
155+
156+
### Filter/format comments
157+
158+
This callback allows modules check/format comments when user request to display comments.
159+
160+
It takes the same arguments as `pluginname_comment_add`.
161+
162+
Modules can implement a function named `pluginname_comment_display`.
163+
164+
Blocks need to overwrite `blockname_comment_display` function.
165+
166+
Blog need to implement `blog_comment_display` function.
167+
168+
It will return the comment object.
169+
170+
### Define a comment template
171+
172+
Modules can implement a function named `pluginname_comment_template`, which allow modules define a comment template.
173+
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
174+
175+
## Backup and Restore
176+
177+
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:
178+
179+
- do not use item ids and rely just on the context
180+
- make the commentarea the same as one of the mappings in the restore (set_mapping); or
181+
- override the function `get_comment_mapping_itemname` in the restore activity class
182+
183+
If you do not do one of these the comments will be silently ignored on restore.
184+
185+
## See also
186+
187+
- [Core APIs](../../../apis.md)
188+
- [MDL-19118](https://tracker.moodle.org/browse/MDL-19118) - Comment API issue
189+
- [コメントAPI](https://docs.moodle.org/ja/コメントAPI)

0 commit comments

Comments
 (0)