|
|
| Line 1: |
Line 1: |
| {{Moodle 2.0}}==Objectives== | | {{Moodle 2.0}} |
| | {| style="border: 1px solid #aaaaff; background-color: #eeeeff; width: 80%; margin: 0 auto 1em auto; padding: .2em; text-align: {{{align|left}}}" |
| | |{{{image|}}} |
| | | '''WORK IN PROGRESS: I've currently just created a template, so please ignore this page until this wip notices has been removed.''' However, you are free to help in the construction of this page by improving it. Please review the [{{SERVER}}{{localurl:{{NAMESPACE}}:{{PAGENAME}}|ac tion=history}} edit history] if you would like to contact the user who put up this notice. If this article has not been edited by that user in a while, please remove this template. |
| | |} |
| | <noinclude> |
|
| |
|
| The goals of Comment API:
| |
|
| |
|
| * Manage comments centrally
| | ==Objectives== |
| * Use a consistent approach for all comments throughout Moodle
| | |
| * Easily integrate Comment API with existing modules
| | The goals of Preferences API: |
| * Works no matter Javascript is enabled or not | | |
| | * example goal |
|
| |
|
|
| |
|
| ==Overview== | | ==Overview== |
|
| |
|
| Comment API provides following functionalities:
| | Preference API provides following functionalities: |
| # Add comments | | # example functionality |
| # Manage comments
| |
| # Delete comments
| |
| | |
| And provides a fancy ajax interface to add/delete comments without reloading page.
| |
|
| |
|
| ==Comment API database table== | | ==Comment API database table== |
| Line 30: |
Line 31: |
| | int(10) | | | int(10) |
| | auto-incrementing | | | auto-incrementing |
| | The unique ID for this comment. | | | The unique ID for this preference. |
| |- | | |- |
| | userid | | | userid |
| | int(10) | | | int(10) |
| | | | | |
| | who wrote this comment | | | The user that the preference belongs to |
| |- | | |- |
| | contextid | | | examplefield |
| | 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 | | | timecreated |
| Line 61: |
Line 52: |
| | | | | |
| | | | | |
| |-
| |
| | content
| |
| | text
| |
| |
| |
| | content of comment
| |
| |} | | |} |
|
| |
|
| ==Use Comment API== | | ==Use Preference 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:
| | ===Title for the example goes here=== |
|
| |
|
| For example, using the following code in the forum module will add a comment icon to every post:
| | Description of the example: |
|
| |
|
| <code php> | | <code php> |
| $cmt = new stdclass;
| | shortexamplecode(); |
| $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 />";
| |
| </code> | | </code> |
|
| |
|
| ===Use comment class=== | | ===Title for the second example goes here=== |
| To use Comment API elsewhere, using following code:
| | |
| | Description of the example: |
| | |
| <code php> | | <code php> |
| $options->area = 'database_entry';
| | shortexamplecode(); |
| $options->context = $context;
| |
| $options->itemid = $record->id;
| |
| $options->showcount = true;
| |
| $comment = new comment($options);
| |
| $comment->output(false);
| |
| </code> | | </code> |
| If you are using Comment API in module context, you'd better add component option, it will help comment API find callback functions faster:
| |
| <code php>
| |
| $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);
| |
| </code>
| |
| ==Comment API overview==
| |
|
| |
| Generally speaking, only two functions you need to know to get comment API worked:
| |
| # Use comment::init to initialize Comment API
| |
| # 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.
| | ==Preference API overview== |
|
| |
|
| It will return the comment object.
| | The Preference API has been implemented in lib/moodlelib.php. |
|
| |
|
| === Define a comment template === | | ====examplefunction()==== |
| Modules can implement a function named '''pluginname_comment_template''', which allow modules define a comment template.
| | Example function description. |
| 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
| |
|
| |
|
| ==See also== | | ==See also== |
| * MDL-19118 - Comment API issue
| |
