The secure CMS.

Welcome to Geeklog, Anonymous Saturday, December 21 2024 @ 10:28 pm EST

Comment Plugin API in Geeklog 1.4

  • Monday, November 21 2005 @ 02:23 pm EST
  • Contributed by:
  • Views: 44,266
Geeklog

The comment plugin API for previous versions of Geeklog has been bothering me for a long time. There were some fundamental problems that prevented plugin authors from exercising full control over their comments. To correct these deficiencies and to hopefully make development of plugins using comments simpler, we've revamped the comment API making it more powerful and at the same time easier to use.

Below is a description of the new plugin comment engine and how to use it in the development of Geeklog plugins. Those unfamiliar with plugin development in Geeklog may first want to read Geeklog's Plugin Development Guide.

Plugin Comment Engine

This section will describe and documents how to enable your plugin to use the Geeklog comment engine. This is a key feature of plugin functionality for many developers and it has been designed to be easy to integrate into your plugin. We have done our best to make this straight forward and enabled the API calls into comment related functions.

NOTE: You will need to be using Geeklog version 1.4 or later to successfully use the current Comment APIs. The plugin comment API has been completely redesigned from previous versions of Geeklog. Comment systems on plugins that predate 1.4 will no longer work.

There are four (4) plugin functions that are required to support comments in a plugin. The example functions that are used for explanation in this section and included in this kit are very complete. You should only need to edit them for your plugin name and table names. The following table summarizes the functions:

  Function Description of Function
1 plugin_deletecomment_<plugin name> This function expects two parameters: comment id and plugin item identifier. This function is called when a request to delete a comment is received by comment.php. It is up to the plugin to make sure that the requesting user has sufficient permissions to perform the deletion. It should return a HTML string (COM_refresh) redirecting to the plugin page containing the item to which the deleted comment belonged.
2 plugin_savecomment_<plugin name> This function expects five (5) parameters: comment title, comment text, id of associated story, parent comment id, and post mode (either 'text' or 'html'). This function is called when a request to save a comment is received by comment.php. It is up to the plugin to make sure that the requesting user has sufficient permissions to save the comment. It should return a HTML string (COM_refresh) redirecting to the plugin page containing the item to which the saved comment belongs.
3 plugin_displaycomment_<plugin name> This function expects seven (7) parameters: item id, comment id, title, display order, display format, page number and view type. This function is called when a request to display a comment is received. It is up to the plugin to make sure that the requesting user has sufficient permission to view the comments and then to call COM_userComments to format the comments for display. It should return false if there was some error, otherwise it should return a HTML string that contains comments to display (excluding COM_header and COM_footer).
4 plugin_getcommenturlid_<plugin name> This function should not expect any parameters. The functions purpose is to return the URL to the plugins primary item view page and a string of containing the name of the unique identifier for plugin items. It is called during the generation of the comment bar so links back to the plugin will work correctly. The results should be returned in the form of an array with the 0 index containing the url and the 1 index containing the unique id name. This function is optional. If not implemented (or if no results are returned) the default values, '$_CONF['site_url'] . "/$type/index.php"' and 'id' respectively, will be used.

How to Call the Comment Engine

You can optionally use the following URL to link to the comment form for your plugin: http://<site_url>/comment.php?type=<plugin_name>&sid=<unique_plugin_id>. You can also choose to use the CMT_userComments function to display comments on your plugin's item's pages (this will include the display of the comment bar which includes a "reply" button).

The comment bar has been programmed to conveniently link back to the record of the plugin it is displaying. By default, the link should look something like this: http://<site_url>/<plugin_name>/index.php?id=<unique_plugin_id>. The plugin_getcommenturlid_<plugin_name> function can be used to override the defaults. This will allow comments displayed on the comment.php page to link back to your plugin.

Additional details on the comment table: The comment table has a unique primary key called cid that is an auto_increment date type. The field type will contain the name of our plugin. The field sid (story-id) is the unique identifier for plugin record with which the comment is associated. The field pid is used to indicate the parent comment id and is 0 for 'top-level' comments (replys directly to the plugin record) or, in the case of a threaded comment, it is set to the cid (the record id in the comment table) for the comment of which it is a child. For information on the 'leftIndex' and 'rightIndex' fields of the comment table see this article on hierarchical structures in databases

Plugin Database Changes

Optionally, you may want to add a field in your plugin to keep track of the number of comments for each item. You can update this count in the plugin_handlecomment() function to keep it accurate and later use the field to quickly check how many comments have been left for the item.

Function Details and Examples

Examples provided here have been gleaned from the polls plugin that is distributed with Geeklog.

1) The plugin_deletecomment_<plugin name> function is called by comment.php when a comment delete occurs on a comment for your plugin. You need to make sure that the current user has adequate permissions to delete the comment. You should then call the comment function CMT_deleteComment() to delete the comment.

/** * polls: delete a comment * * @param int $cid Comment to be deleted * @param string $id Item id to which $cid belongs * @return mixed false for failure, HTML string (redirect?) for success */ function plugin_deletecomment_polls($cid, $id) { global $_CONF, $_TABLES, $_USER; $retval = ''; $has_editPermissions = SEC_hasRights ('polls.edit'); $result = DB_query ("SELECT owner_id,group_id,perm_owner,perm_group,perm_members,perm_anon " . "FROM {$_TABLES['pollquestions']} WHERE qid = '{$id}'"); $A = DB_fetchArray ($result); if ($has_editPermissions && SEC_hasAccess ($A['owner_id'], $A['group_id'], $A['perm_owner'], $A['perm_group'], $A['perm_members'], $A['perm_anon']) == 3) { CMT_deleteComment($cid, $id, 'polls'); $retval .= COM_refresh ($_CONF['site_url'] . "/polls/index.php?qid=$id&aid=-1"); } else { COM_errorLog ("User {$_USER['username']} (IP: {$_SERVER['REMOTE_ADDR']}) " . "tried to illegally delete comment $cid from poll $id"); $retval .= COM_refresh ($_CONF['site_url'] . '/index.php'); } return $retval; }

2) The plugin_savecomment_<plugin name> function is called by comment.php when a comment save occurs on a comment for your plugin. You need to make sure that the current user has adequate permissions to save the comment. You should then call the comment function CMT_saveComment() to save the comment.

/** * Poll saves a comment * * @param string $type Plugin to save comment * @param string $title comment title * @param string $comment comment text * @param string $id Item id to which $cid belongs * @param int $pid comment parent * @param string $postmode 'html' or 'text' * @return mixed false for failure, HTML string (redirect?) for success */ function plugin_savecomment_polls($title, $comment, $id, $pid, $postmode) { global $_CONF, $_TABLES, $LANG03, $_USER; $retval = ''; $commentcode = DB_getItem ($_TABLES['pollquestions'], 'commentcode', "qid = '$id'"); if ($commentcode < 0) { return COM_refresh ($_CONF['site_url'] . '/index.php'); } $ret = CMT_saveComment ($title, $comment, $id, $pid, 'polls', $postmode); if ($ret > 0) { // failure $retval .= COM_siteHeader() . CMT_commentForm ($_USER['uid'], $title, $comment, $id, $pid, 'polls', $LANG03[14], $postmode) . COM_siteFooter(); } else { // success $retval = COM_refresh ($_CONF['site_url'] . "/polls/index.php?qid=$id&aid=-1"); } return $retval; }

3) The plugin_displaycomment_<plugin name> function is called by comment.php when a request is made to display a comment for your plugin. You need to make sure that the current user has sufficient access to view the comment(s). You should then call the comment display function (CMT_userComments()) and return the results.

/** * Plugin should display [a] comment[s] * * @param string $id Unique idenifier for item comment belongs to * @param int $cid Comment id to display (possibly including sub-comments) * @param string $title Page/comment title * @param string $order 'ASC' or 'DSC' or blank * @param string $format 'threaded', 'nested', or 'flat' * @param int $page Page number of comments to display * @param boolean $view True to view comment (by cid), false to display (by $pid) * @return mixed results of calling the plugin_displaycomment_ function */ function plugin_displaycomment_polls($id, $cid, $title, $order, $format, $page, $view) { global $_TABLES, $LANG_ACCESS; $retval = ''; $sql = "SELECT COUNT(*) AS count, owner_id, group_id, perm_owner, perm_group, perm_members, perm_anon " . "FROM {$_TABLES['pollquestions']} WHERE (qid = '$id')" . COM_getPermSQL('AND') . ' GROUP BY qid'; $result = DB_query ($sql); $A = DB_fetchArray ($result); $allowed = $A['count']; if ($allowed == 1) { $delete_option = (SEC_hasRights ('polls.edit') && (SEC_hasAccess ($A['owner_id'], $A['group_id'], $A['perm_owner'], $A['perm_group'], $A['perm_members'], $A['perm_anon']) == 3)); $retval .= CMT_userComments ($id, $title, 'polls', $order, $format, $cid, $page, $view, $delete_option); } else { $retval .= COM_startBlock ($LANG_ACCESS['accessdenied'], '', COM_getBlockTemplate ('_msg_block', 'header')) . $LANG_ACCESS['storydenialmsg'] . COM_endBlock (COM_getBlockTemplate ('_msg_block', 'footer')); } return $retval; }

4) The plugin_getcommenturlid_<plugin name> (optional) function is called from the comment bar creation function to get the URL of the plugin's main item page and the name of the unique id that should be used to specify items. You should return this information in an array, with the index 0 value pointing the URL and the index 1 value pointing to the unique id name.

/** * polls - get comment url and unique id * * @return array An array containing main plugin item URL and the unqiue id */ function plugin_getcommenturlid_polls() { global $_CONF; return array($_CONF['site_url'] . '/polls/index.php', 'qid'); }