Description of the Discussion extension
From WikiCaptions
This is a documentation for version 1.0 and above. Documentation for older versions (<=0.3) is here.
General description
Installation instructions
Contents |
License
This extension is released under an MIT-like license with an extra condition asking to keep a link to http://en.wikicaptions.org/wiki/Extensions:Discussion in the Options panel. Details can be found here.
Usage
To add the discussion form to the article, add the following text to the body of your page:
<discussion />
Description
The extension uses Ajax for retrieving comments and for various actions (submitting comments, moderation, etc).
It supports the hierarchical tree structure. Each comment has a depth counter: comments posted via 'post comment' has depth 0, while replies to comments of depth d have depth d+1.
The discussion display has two modes:
- paged Display at most page_size comments whose depth does not exceed counted_depth. (The number of comments of larger depth is unlimited).
- show_all All comments are displayed at once.
In the paged mode newest comments are displayed first. Older comments are generally retrieved on demand.
Permissions and comment status
You can specify who can view comments, post messages and perform moderation tasks by setting 'view_group', 'post_group', 'restricted_post_group' and 'moderator_group' parameters. It can take the following values:
- '*': all users (anonymous and logged in).
- 'user': logged in users.
- 'sysop': wiki administrators.
- empty: the group is empty.
Viewing comments Each comment has a status, which is a number from 0 to 4. It controls which groups of users can view it:
- 0: default. Shown to moderator_group and to view_group.
- 1: blocked. moderator_group can see complete details (the author and the text), view_group can only see the line 'blocked'.
- 2: hidden. Shown only to moderator group. May only have hidden replies.
- 3: needs approval. Shown only to moderator_group. Cannot have any replies.
Posting comments Comments can be posted by users in the 'post_group' and 'restricted_post_group' groups. If the user belongs to the first group then the comment status will be '0' and thus it will be visible immediately. If the user belongs only to the second group then the comment status will be '3', which means that it should be approved by a moderator first.
Parameters
You can specify various parameters, e.g. as follows:
<discussion> post_group="user" characters_max=0 </discussion>
The list of parameters is below.
| Parameter | Description | Possible values | Default value | |
|---|---|---|---|---|
| General | id | Discussion identifier; allows to have several discussions on the same page. A page should not have the same identifier more than once. | String. Can contain alpha-numeric symbols, "-" and "_" (other symbols are stripped). Can be empty. | Empty |
| max_depth | Maximum allowed depth: replies to comments of depths max_depth will be displayed at the same depth. | Non-negative integer | 10 | |
| Permissions | view_group | See the 'Permissions' section above. | '*', 'user', 'sysop' or empty | * |
| post_group | * | |||
| restricted_post_group | empty | |||
| moderator_group | sysop | |||
| Comment display | counted_depth | See the 'Description' section above. | Non-negative integer | 10 |
| page_sizes | Positive integer, or a a sequence of positive integers separated by a comma. The first number in the sequence gives the default page size, other numbers give alternative page sizes to which the user can switch via the "Options" panel. | 10,15,20,25,30,50,100 | ||
| collapsed_depths | Specified comment depths which will NOT be expanded in the paged mode. | Sequence of non-negative integers separated by a comma | 2,5,8 | |
| show_all_page_size | Limits the number of comments per page in the show_all mode. (If there 10,000 comments then we may not want to retrieve and display all of them...) | Positive integer | 500 | |
| show_all_order | Affects the display of comments of depth 0 in the show_all mode: 0 - chronological, 1 - reverse chronological | 0 or 1 | 0 | |
| init_display | Specifies whether comments are hidden or not by default. Values 'show' and 'hide' are only suggestions; they can be overwritten by stored cookies. Values '!show' and '!hide' ignore cookies. | String: 'show', '!show', 'hide', or '!hide' | show | |
| time_display |
| 0 or 1 | 0 | |
| recent_link | If 1, display "Recent comments" in the bottom right corner | 0 or 1 | 1 | |
| Comment composition | characters_max | Maximum allowed number of characters per comment. If 0, then there are no restrictions. | Non-negative integer | 500 |
| author_characters_max | Maximum allowed number of characters for the name of anonymous users. | Positive integer | 30 | |
| quoting | If '1' then show the "Quote" button in the message composition window | 0 or 1 | 1 | |
| preview |
| 0,1 or 2 | 2 |
Technical details
Retrieving comments As mentioned above, comments are retrieved in bacgkround via Ajax. The javascript code on the client side keeps requesting comments from the server until it can display the required number of comments (determined by page_size). The server sends comments sequentially in the reverse chronological order. This may mean unnecessary traffic: some retrieved comments may never be displayed. Consider the following scenario: the 100 most recent comments were replies to a very old comment that does not appear on the first page. Then these 100 comments will be retrieved but not displayed (unless the user navigates to this old comment). It's not clear, however, how often this will happen in practice: arguably, visitors will tend to reply to comments visible on the first page, rather than to old comments.
| powered by commenterra | Recent comments |
