glFusion Wiki

Site Tools


glfusion:development:pluginapi:comment

Comment Functions

This section describes how to enable your plugin to use the glFusion comment engine. This is a key feature or plugin functionality for many developers and not very difficult to integrate into your project. The glFusion developers have made things very straight forward and enabled the API calls into comment related core programs. If you want your plugin to support comments and use the glFusion comment engine, then you need to implement these functions in your plugin's functions.inc file:

Displaying the comment bar within the plugin

The plugin simply needs to pass the right parameters to CMT_userComments. Until v1.3.0 it was called COM_userComments. For backward compatibility, COM_userComments still exists as a redirect function. Nevertheless, CMT_userComments accepts one more parameter (comments allowed: yes/no/closed) than COM_userComments, so it's best to do:

   if (floatval (VERSION) < 1.4) {
        if ($this_plugin_accepts_comments)
           if ($_PLG_MULTIFAQ['comments'])
                $display .= COM_userComments(...);
   } else {
         require_once $_CONF['path_system'] . 'lib-comment.php';
         $display .= CMT_userComments(..., !$this_plugin_accepts_comments);
    }

It is best to put the following code inside the already needed function plugin_displaycomment__<plugin name>, and just call that function from within the plugin or better yet, function PLG_displayComment($plugin, ...) whenever the following code is needed.

How to call the Comment Engine

After you implement the comment functions in your plugin, you will need to call the glFusion comment engine to create the comment or view the comments. This can be done by adding a link which redirects the user to public_html/comment.php with the necessary parameters from your plugin.

The example below was used by the FileMgmt plugin, where there was a link under each file listed. The link to comment.php needs to be passed with two parameters to indicate the type and cid. The cid is a unique comment ID. The following example shows how to call the comment engine from your plugin. The variable $myretval is assigning the formatted link to a variable which will be displayed as a link in the plugin display.

$myretval = "<a href='" . $_CONF[site_url] . "/comment.php?type=filemgmt&id=" . $lid . "'>" . $LANG_FM01['ENTERCOMMENT'] . "</a>"

The variable type is assigned the plugin type and ID is assigned a unique comment ID which in this case is the plugin record ID for this comment. In this example, the variable $lid is a unique record id in the Filemgmt plugin for each file in the repository. You will want to use your plugin variable in place of $lid. We will actually be inserting the plugin comment ID into the sid field in the comment table. This is where you see the comment engine was initially designed around stories; but no fear, the integration will be clean. The ID that our plugin uses as a reference will be passed thru comment.php to your plugin comment functions.

The following is a second example of enabling comments in the Journal Plugin. This was added to the display function for the journal entry where je_id is the primary key for the journal record.

$retval .= "</td></tr><tr><td><a href='" .$_CONF[site_url] ."/comment.php?type=journal&cid=" .$A['je_id']. "'>" . $LANG01[60] . "</a>"

The plugin API function PLG_callCommentForm is called in comment.php when the story-id is blank. This plugin API call in turns calls your plugin_commentform function if it exists. Additionally, the program public_html/article.php is called when the user presses reply on the comment bar or changes the comment view. In article.php PLG_callCommentForm is called with all the parameters such as mode, order and reply set. The sample completed plugin function in this kit shows how to pass these parameters on, and in doing so your plugin will have full support for the comment bar.

Additional Details on the Comment Table

The comment table has a unique primary key called cid that is an auto_increment data type. The field type will contain the name of our plugin. The field sid (story-id) is the identifier for the top level comment. We will update the sid field with the ID that links to our plugin record for which we are adding this comment. The field pid is used to indicate the parent comment ID and is 0 for the first comment or in the case of a threaded comment, it is set to the cid (the record ID in the comment table) for the main comment that it is related to.

Plugin Database Changes

You will want to add a field in your plugin to keep track of the number of comments for this item. It is updated by the plugin_commentsave() and can be used to quickly check if there are any comments.

plugin_savecomment_<plugin name>

This function is called when glFusion is asked to save a comment for this plugin.

Arguments

($title, $comment, $id, $pid, $postmode)

plugin_deletecomment_<plugin name>

This function is called when glFusion is asked to delete a comment from this plugin.

Arguments

($cid, $id)

plugin_displaycomment__<plugin name>

This function is called when glFusion is asked to display a direct comment URL (i.e. when the user directly clicked a comment's link).

Notes

It can also be called upon by the plugin itself (see previous) instead of having an additional internal function for displaying the comment bar within the plugin.

Arguments

($id, $cid, $title, $order, $format, $page, $view)

plugin_commentsupport_<plugin name>

This function does not take any parameters but simply returns true if this plugin supports comments. This call is made in glFusion code (i.e. article.php) to determine if it should redirect handling to the plugin.

Arguments

Code Example

The commentsupport function is a basic function that returns true or false to indicate to glFusion if this plugin supports comments or not. This function is currently only called from article.php. When the comment bar is used, it will call article.php. At the beginning of article.php this Plugin API function is used to see if it is being called from a plugin related comment and if so, then redirect it to the plugin function to handle the comment.

function plugin_commentsupport_filemgmt() {
// Filemgmt Module will use comments
    return true;
}

plugin_handlecomment_<plugin name>

This function expects the comment ID (primary index in the comment table) and type of operation (either 'save' or 'delete') to perform on the comment. It will update the plugin record with the total number of comments for this plugin item. It then handles the refresh or redirection of the user back to the plugin instead of the main site page.

Arguments

($id, $operation)

Code Example

The handlecomment function is called by comment.php to update your plugin record's field for total number of comments. You will need to add a field in your plugin's record but this is useful to quickly determine if this record has any comments or not, so it is advisable.

After the update, you want to redirect the program execution to a view of the single plugin record or another main page of your plugin.

The code to handle the save or delete operation may be the same but the API was designed to allow the developer to handle this differently if required.

function plugin_handlecomment_filemgmt($id, $operation){
    global $_CONF, $_FM_TABLES, $_TABLES;
    // Get the total number of comments now related to this comment id - which is also the plugin record id.
    $comments = DB_count($_TABLES['comments'], 'sid', $id);
    if ($operation == 'save') {
        // Update the the Filemgmt main record for this file with the number of related comments
        DB_change($_FM_TABLES['filemgmt_filedetail'], 'comments', $comments, lid', $id);
    } elseif ($operation == 'delete') {
	    DB_change($_FM_TABLES['filemgmt_filedetail'],'comments',$comments,'lid',$id);
	} else {
		COM_errorLOG("Illegal Comment operation sent to FileMgmt Pugin:" . $operation);
	}
    // Now redirect the program flow to the view of the file and its comments
	echo COM_refresh($_CONF['site_url'] . "/filemgmt/singlefile.php?lid='$id'");
	}
}

plugin_commentform_<plugin name>

This function expects a number of parameters and is called from glFusion article.php and comment.php. Parameters are: comment_id (primary key), comment_mode (nested, flat, threaded, none), order (ascending or descending) and reply (was the reply submit button used on the comment bar). Only comment_id is mandatory.

Arguments

($id, $commentmode, $order, $reply)

Code Example

The comment count for this plugin related record is retrieved to determine if this is the first comment for this plugin item.

If this is the first comment then redirect execution to comment.php and pass a valid sid set to the unique plugin item ID. The plugin key for this comment and type set to the plugin name. If this is not the first comment then you call COM_userComments. You can additionally call a function to display the plugin record above the comment bar and comments. In the example function, the return variable is being assigned the formatted HTML of the siteHeader, the plugin record and the results of the comments, and finally the site footer. In the comment display, the user has access to the comment bar to start a new comment or use the reply links under any comment.

function plugin_commentform_filemgmt($id,$commentmode='',$order='',$reply='') {
    global $_CONF,$_TABLES,$_FM_TABLES;
    $commentCount = DB_count($_TABLES['comments'],'sid',$id);
    $title = DB_getItem($_FM_TABLES['filemgmt_filedetail'],'title',"lid='''$id'''");
    if ($commentmode == "") {
		$commentmode = $_CONF['comment_mode'];
	}
	if ($order == "") {
		$order="ASC";
	}
	$type="filemgmt";
	if ($commentCount == 0 || $reply != "") {
		$pid=0;
		$type="filemgmt";
		echo COM_refresh($_CONF['site_url'] . "/comment.php?sid='$id'&pid='$pid'&type='$type'");
	} else {
		$display = COM_siteHeader() . plugin_commentparent_filemgmt($id) . COM_userComments($id,$title,$type,$order,$commentmode);
		$display .= COM_siteFooter();
	}
	return $display;
}

plugin_commentparent_<plugin name>

Optional function which can be called from your plugin_commentform function to also display the plugin parent above the comments. This is how glFusion stories are displayed, with the story and then the comment bar and associated comments.

Arguments

Code Example

The commentparent function is plugin specific and is really code that you likely already have to display a single record for your plugin. You may even call one of your existing plugin functions and not have to create it in the functions.inc file.

The following is another example of the two main comment functions that were used for the Journal Plugin. In this example, the commentparent function was not required, as the existing Journal logic to display the Journal record was already written as a function - printjournalentry($id).

Ensure that you replace $type in the plugin_commentform() function with the plugin name.

function plugin_handlecomment_journal($id,$operation) {
	global $_CONF,$_TABLES;
    // Get the total number of comments now related to this commment id - which is also the plugin record id.
    $comments = DB_count($_TABLES['comments'],'sid',$id);
    // Update the the Journal Entry record for this file with the number of related comments
	DB_change($_TABLES['journal_entry'],'je_comment', $comments, 'je_id',$id);
	// Now redirect the program flow to the view of the file and its comments
	echo COM_refresh($_CONF['site_url'] . "/journal/index.php?mode=read&type=entry&je_id=$id");
}
 
function plugin_commentform_journal($id,$commentmode='',$order='',$reply='') {
	global $_CONF,$_TABLES;
	$commentCount = DB_count($_TABLES['comments'],'sid',$id);
	$title = DB_getItem($_TABLES['journal_entry'],'je_summary',"je_id=$id");
	if ($commentmode == "") {
		$commentmode = $_CONF['comment_mode'];
	}
	if ($order == "") {
		$order="ASC";
	}
	$type="journal";
	if ($commentCount == 0 || $reply != "") {
		$pid=0;
		echo COM_refresh($_CONF['site_url'] . "/comment.php?sid=$id&amp;pid=$pid&amp;type=$type");
	} else {
		$display = COM_siteHeader() . printjournalentry($id) . COM_userComments($id,$title,$type,$order,$commentmode);
	    $display .= COM_siteFooter();
	}
	return $display;
}
glfusion/development/pluginapi/comment.txt · Last modified: 2017/04/12 21:13 (external edit)

Page Tools