Adding Moderation Capability - Revision history

Cordiste: Move explanations into the right paragraphs

2010-03-31T17:28:33Z

Move explanations into the right paragraphs

LWC: /* The functions */ Spaces

2009-05-30T09:42:19Z

‎The functions: Spaces

LWC: /* The functions */ Space

2009-05-30T09:41:36Z

‎The functions: Space

LWC: Formatted and fixed

2009-05-30T09:40:32Z

Formatted and fixed

Show changes

Dirk: fixed formatting of sample code

2009-05-05T09:02:20Z

fixed formatting of sample code

Show changes

Dirk: Changed category

2008-05-10T20:18:11Z

Changed category

Tomw at 14:00, 1 July 2004

2004-07-01T14:00:03Z

Tomw at 13:43, 30 June 2004

2004-06-30T13:43:13Z

New page

This section will describe and document how to enable your plugin to use the
Geeklog moderation engine. This set of functions is optional when creating your
plugin, but should be used when your plugin has functionality that includes
submitting of an item that needs to be reviewed by a site admin or plugin admin
before posting to the site. The Geeklog (GL) developers have made the implementation of this
API very straight forward and enabled the API calls into the moderation related
core programs.

'''NOTE: '''You will need to be using Geeklog version 1.3.7 or apply the
changes noted in the appendix to successfully use the Moderation API's, though
some functionality may work with previous versions of Geeklog. The changes with
1.3.7 release include the following programs: moderation.php, submit.php, plugin.class.php and lib-plugins.php.
Refer to the appendix if you have a previous release and want to review the needed changes.

There are six (6) plugin functions that are required for the moderation plugin
and two (2) optional functions. The example functions that are provided can be
used as guide, but they will required some changes to make them work for your plugin.
The following table summarizes the functions:

<table cellPadding="2" width="100%" border="1">
<tr>
<th width="4%"> </th>
<th width="32%">Function</th>
<th>Description of Function</th>
</tr>
<tr>
<td width="4%" align="center">1</td>
<td width="32%">plugin_ismoderator_<plugin name></td>
<td>Checks if the current user has rights to moderate for the plugin and returns true if this is the case, false otherwise.</td>
</tr>
<tr>
<td width="4%" align="center" >2</td>
<td width="32%" >plugin_submissioncount_<plugin name></td>
<td >Calculates the current number of submissions awaiting moderation and returns that number.</td>
</tr>
<tr>
<td width="4%" align="center" >3</td>
<td width="32%" >plugin_savesubmission_<plugin name></td>
<td >Takes the data input by the plugin submission form and populates the <plugin name>submission table with that data.</td>
</tr>
<tr>
<td width="4%" align="center">4</td>
<td width="32%">plugin_moderationvalues_<plugin name></td>
<td>Returns a list of important moderation values. The list contains (in order): the row 'id' label, the main plugin table name, comma separated string of moderation fields, and the plugin submission table name.</td>
</tr>
<tr>
<td width="4%" align="center" >5</td>
<td width="32%" >plugin_itemlist_<plugin name></td>
<td >Uses the plugin class to return data required by moderation.php to list plugin objects that need to be moderated.</td>
</tr>
<tr>
<td width="4%" align="center" >6</td>
<td width="32%" >plugin_submit_<plugin name></td>
<td >Returns a string containing the HTML to display the plugin submission form.</td>
</tr>
<tr>
<td width="4%" align="center">7</td>
<td width="32%">plugin_moderationapprove_<plugin name></td>
<td>This optional function supplements moderation.php. While moderation.php actually moves data from the <plugin name>submission table to the main <plugin name> table, this function executes all other submission approval tasks including any other database updates required by your plugin.</td>
</tr>
<tr>
<td width="4%" align="center" height="29">8</td>
<td width="32%" height="29">plugin_moderationdelete_<plugin name></td>
<td height="29">This optional function supplements moderation.php. While moderation.php actually removes data from the <plugin name>submission table, this function executes all other submission removal tasks including any other database updates required by your plugin.</td>
</tr>
</table>

=== How to call the Moderation Engine ===

After you implement the moderation functions in your plugin, you will need to
call the Geeklog moderation engine or program to create or moderate the submission.
This can be done by adding a link or button which redirects the user to submit.php
or moderate.php with the necessary parameters from your plugin.

The example below was used by the Mailing Lists plugin to link to the 'submit
new mailing list' page. The link to submit.php needs to be passed with the parameter
'''type''' to indicate which plugin's submission form should be displayed. The
variable $retval is assigned the formatted link which will be displayed as a
link in the plugin display.

$retval = "<a href='" . $_CONF['site_url'] . "/submit.php?type=lists'>" . $LANG_LISTS['SUBMITLIST'] . "</a>"

'''Admin interaction with the Moderation Engine:''' Once all the moderation
functions are implemented, the 'Submissions' link in the admin block will include
a list of all submissions to be moderated (they can be approved, removed or
edited). You must write you're own submission edit function located in
$_CONF['site_admin_url'] . '/plugins/<plugin name>/<plugin name>.php.
It will be passed the http variables id=<item id> and mode=editsubmission.

=== Plugin database changes ===

The table <plugin name>submission must be the name of your submission
table. This table can only contain a proper subset of the columns from the main
<plugin name> table. This allows the moderation.php script to
automatically copy those columns from the submission to the main table upon
approval. All data in columns of the submission table that are not in the main
table will be lost.

=== Function details and examples ===

This explanation of the plugin moderation API functions will use the Mailing
Lists plugin for examples and give a detailed description of each function.

plugin_ismoderator_lists() {
global $_USER, $_TABLES;
return SEC_hasRights('lists.admin');
}

1) The '''''plugin_ismoderator''''' function simply returns TRUE if
the current user has moderation privileges for the plugin. In the example
to the right, The mailing lists plugin simply uses the security function
SEC_hasRights to determine if a user has the required rights. The lists.admin
permission was installed with the plugin. You could use your own SQL query or some
other criteria to determine access rights.

function plugin_submissioncount_lists() {
global $_TABLES;
return DB_count($_TABLES['listssubmission']);
}

2) The''''' plugin_submissioncount''''' function returns the number of
submissions for this plugin that are awaiting moderation. This value is used
to indicate the number of waiting submissions in the admin block. A DB_count()
on the plugin submission table is usually sufficient for this.

function plugin_savesubmission_lists($A) {
global $_TABLES, $_USER, $_CONF;

// check for missing fields
if (empty($A['ml_name']) || empty($A['ml_descr'])) {
return false;
}

if (empty($_USER['uid'])) {
$owner_id = 1;
} else {
$owner_id = $_USER['uid'];
}

if (SEC_hasRights('links.admin')) {
$result = DB_getItem($_TABLES['groups'], '*', "grp_name = 'lists Admin'");
if ($_CONF['listsarchive'] == 'optional') {
$archive = $_CONF['listsarchivedefault'];
} elseif ($_CONF['listsarchive'] == 'no') {
$archive = 0;
} else { // $_CONF['listsarchive'] == 'yes'
$archive = 1;
}
DB_save($_TABLES['lists'], 'ml_id, ml_name, ml_descr, html, archive, owner_id, group_id',
"'" . COM_makeSid() . "', '" . $A['ml_name'] . "', '" . $A['ml_descr']
. "', " . $_CONF['listshtml'] . ", $archive, $owner_id, " . $result['grp_id']);
} elseif ($_CONF['listssubmission'] == 1) {
DB_save($_TABLES['listssubmission'],
'ml_id, ml_name, ml_descr',
"'" . COM_makeSid() . "', '" . $A['ml_name'] . "', '"
. $A['ml_descr'] . "'");
} else {
return false;
}

if (DB_error()) {
return false;
}

return true;
}

3) The '''''plugin_savesubmission''''' function takes data entered into
the submission form and saves it to the submission table. Optionally, this function
can use different logic for an admin or power user as seen in the Mailing Lists Plugin.
In addition to saving the information to the plugin's submission table, it must
also check data entered for validity. Upon failure the function should return false
or redirect to the submission form. If successful, the function should redirect
to a relevant page, or return true. In GL 1.3.7 the plugin API expects the function
to do a redirect (COM_refresh()). If it does not, a successful return from the function
will redirect the user back to the GL home page.

function plugin_moderationvalues_lists() {
global $_TABLES;
return array('ml_id', $_TABLES['lists'], 'ml_id, ml_name, ml_descr', $_TABLES['listssubmission']);
}

4) This '''''plugin_moderationvalues''''' function returns important information used by the
Plugin API to handle plugin submissions. It must return an array consisting
of the main column id (ml_id), the main table name ($_TABLES['lists']), a comma
separated list of columns that will be copied from the plugin submission table
to the main table (ml_id, ml_name, ml_descr), and the name of the submission
table ($_TABLE['listssubmission']). This information is used to automatically
copy information from the plugin submission table to the plugin main table when
a submission is approved.

function plugin_itemlist_lists() {
global $_TABLES;

if (plugin_ismoderator_lists()) {
$plugin = new Plugin();
$plugin->submissionlabel = 'Mailing List Submissions';
$plugin->getsubmissionssql = SELECT ml_id as id, ml_name, ml_descr FROM
. $_TABLES['listssubmission'];
$plugin->addSubmissionHeading('List Name');
$plugin->addSubmissionHeading('List Description');

return $plugin;
}
}

5) The function '''''plugin_itemlist''''' returns a Plugin() class containing information
that will displayed on the moderation.php page. The following member variables
of the Plugin class must be filled out:

*'''submissionlabel:''' The title that indicate the plugin submission section.
*'''getsubmissionsql:''' An SQL query that will select all the data that will
be displayed in the plugin submission section. NOTE: one item (the unique
id column) must be labeled id ('as id').
*'''addSubmissionHeading():''' This function must be called once for every field
besides the one labeled id. The parameter passed should be the column
name to be displayed.

function plugin_submit_lists() {
global $_CONF, $LANG12, $HTTP_POST_VARS;

if ($_CONF['listssubmission'] == 0 && !SEC_hasRights('lists.admin')) {
return "Submission queue disabled for mailing lists";
}

if ($HTTP_POST_VARS['mode'] == $LANG12[32]) { // preview
$A = $HTTP_POST_VARS;
$ml_id = $A['ml_id'];
} else {
$ml_id = COM_makesid();
}

$template = new Template($_CONF['path'] . "plugins/lists/templates/public");
$template->set_file(array('form' => 'submit_form.thtml'));
$template->set_var('site_url', $_CONF['site_url']);
$template->set_var('lang_name', 'List Name');
$template->set_var('ml_name', $A['ml_name']);
$template->set_var('lang_descr', 'Description');
$template->set_var('ml_descr', $A['ml_descr']);
$template->set_var('ml_id', $ml_id);
$template->set_var('lang_preview', $LANG12[32]);
$template->set_var('lang_save', $LANG12[8]);

return $template->parse('output', 'form');
}

6) The function '''''plugin_submit''''' creates HTML that contains the submission
form for the plugin. It is recommended to use the GL template functionality as
shown here to create the form. See the section of this manual on templates for
more information. When creating the form, be sure to include fields for each
variable you would like the user to fill along with preview and submit buttons.

function plugin_moderationapprove_lists($id) {
global $_TABLES, $_USER, $_CONF;

$result = DB_query("SELECT * FROM " . $_TABLES['groups']
. " WHERE grp_name = 'lists Admin'");
$group = DB_fetchArray($result);
if ($_CONF['listsarchive'] == 'optional') {
$archive = $_CONF['listsarchivedefault'];
} elseif ($_CONF['listsarchive'] == 'no') {
$archive = 0;
} else { // $_CONF['listsarchive'] == 'yes'
$archive = 1;
}
$sql = "UPDATE " . $_TABLES['lists'] . " SET owner_id = " . $_USER['uid']
. ", group_id = " . $group['grp_id'] . ", html = " . $_CONF['listshtml']
. ", archive = $archive WHERE ml_id = '$id'";
$result = DB_query($sql);

if (DB_error()) {
return 'Error';
}
return '';
}

7) Although the moderation.php script takes care of the work
of actually moving data from the plugin submission table to the main plugin table,
often times a plugin requires more to be done to the plugin tables or for other
information to be updated. GL provides the function '''''plugin_moderationapprove
'''''for these tasks. In the case of the lists plugin, the main plugin table is updated
with additional data that it is not desirable for a user to enter. Instead
this function takes care of placing that information into the table. As of now
the return value for this function is ignored.

function plugin_moderationdelete_lists($id) {
global $_TABLES;

// these tables should not contain any rows with ml_id = $id
// this is done 'just in case'
DB_delete($_TABLES['listsubscriptions'], 'ml_id', $id);
DB_delete($_TABLES['listarchive'], 'ml_id', $id);
DB_delete($_TABLES['listpermissions'], 'ml_id', $id);
}

8) Although the moderation.php script takes care of the work
of actually removing data from the plugin submission table for a submission
deletion, often times a plugin requires more to be done to the plugin tables or for other
information to be updated. GL provides the function '''''plugin_moderationdelete'''''
for these tasks. In the case of the lists plugin, tables are checked for
extraneous data (that should not exist in most cases) and that data is removed
if found. As of now the return value for this function is ignored.

@@ Line 84: / Line 84: @@
 ====plugin_ismoderator_<plugin name>====
 <pre>
 function plugin_ismoderator_lists()
@@ Line 94: / Line 100: @@
 ====plugin_submissioncount_<plugin name>====
-The '''''plugin_ismoderator'''''  function simply returns TRUE if
-the current user has moderation privileges for the plugin.  In the example
+The '''''plugin_submissioncount''''' function returns the number of
-to the right, The mailing lists plugin simply uses the security function
+submissions for this plugin that are awaiting moderation.  This value is used to indicate the number of waiting submissions in the admin block.  A DB_count() on the plugin submission table is usually sufficient for this.
 <pre>
@@ Line 109: / Line 114: @@
 ====plugin_savesubmission_<plugin name>====
-The '''''plugin_submissioncount''''' function returns the number of
-submissions for this plugin that are awaiting moderation.  This value is used to indicate the number of waiting submissions in the admin block.  A DB_count() on the plugin submission table is usually sufficient for this.
+The '''''plugin_savesubmission''''' function takes data entered into
 <pre>
@@ Line 158: / Line 166: @@
 ====plugin_moderationvalues_<plugin name>====
-The '''''plugin_savesubmission''''' function takes data entered into
-the submission form and saves it to the submission table.  Optionally, this function can use different logic for an admin or power user as seen in the Mailing Lists Plugin.
+The '''''plugin_moderationvalues''''' function returns important information used by the Plugin API to handle plugin submissions.  It must return an array consisting of the main column id (ml_id), the main table name ($_TABLES['lists']), a comma separated list of columns that will be copied from the plugin submission table to the main table (ml_id, ml_name, ml_descr), and the name of the submission table ($_TABLE['listssubmission']).  This information is used to automatically
-In addition to saving the information to the plugin's submission table, it must also check data entered for validity.   Upon failure the function should return false or redirect to the submission form.  If successful, the function should redirect to a relevant page, or return true.  In Geeklog 1.3.7 the plugin API expects the function to do a redirect (COM_refresh()).  If it does not, a successful return from the function
+copy information from the plugin submission table to the plugin main table when a submission is approved.
 <pre>
@@ Line 173: / Line 180: @@
 ====plugin_itemlist_<plugin name>====
-The '''''plugin_moderationvalues''''' function returns important information used by the Plugin API to handle plugin submissions.  It must return an array consisting of the main column id (ml_id), the main table name ($_TABLES['lists']), a comma separated list of columns that will be copied from the plugin submission table to the main table (ml_id, ml_name, ml_descr), and the name of the submission table ($_TABLE['listssubmission']).  This information is used to automatically
-copy information from the plugin submission table to the plugin main table when a submission is approved.
+The function '''''plugin_itemlist''''' returns a Plugin() class containing information that will displayed on the moderation.php page.  The following member variables of the Plugin class must be filled out:
 <pre>
@@ Line 195: / Line 206: @@
 ====plugin_submit_<plugin name>====
-* '''submissionlabel:''' The title that indicate the plugin submission section.
+The function '''''plugin_submit''''' creates HTML that contains the submission form for the plugin.  It is recommended to use the Geeklog template functionality as shown here to create the form.  See the section of this manual [[Using Templates and Language Files|on templates]] for more information.  When creating the form, be sure to include fields for each variable you would like the user to fill along with preview and submit buttons.
 <pre>
@@ Line 233: / Line 241: @@
 ====plugin_moderationapprove_<plugin name> ====
-The function '''''plugin_submit''''' creates HTML that contains the submission form for the plugin.  It is recommended to use the Geeklog template functionality as shown here to create the form.  See the section of this manual [[Using Templates and Language Files|on templates]] for more information.  When creating the form, be sure to include fields for each variable you would like the user to fill along with preview and submit buttons.
 <pre>
@@ Line 263: / Line 272: @@
 ====plugin_moderationdelete_<plugin name>====
-Although the moderation.php script takes care of the work of actually moving data from the plugin submission table to the main plugin table, often times a plugin requires more to be done to the plugin tables or for other information to be updated.  Geeklog provides the function '''''plugin_moderationapprove''''' for these tasks.  In the case of the lists plugin, the main plugin table is updated with additional data that it is not desirable for a user to enter.  Instead this function takes care of placing that information into the table.  As of now the return value for this function is ignored.
 <pre>
@@ Line 278: / Line 288: @@
 </pre>
-Although the moderation.php script takes care of the work of actually removing data from the plugin submission table for a submission deletion, often times a plugin requires more to be done to the plugin tables or for other information to be updated.  Geeklog provides the function '''''plugin_moderationdelete''''' for these tasks.  In the case of the lists plugin, tables are checked for extraneous data (that should not exist in most cases) and that data is removed if found.  As of now the return value for this function is ignored.
 [[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

@@ Line 52: / Line 52: @@
 |7
 |[[#plugin_moderationapprove_<plugin name>|plugin_moderationapprove_<plugin name>]]
-|This optional function supplements moderation.php.  While moderation.php actually moves data from the <plugin name>submission table to the main <plugin name> table, this function executes all other submission approval tasks including any other database updates required by your plugin.
+|This optional function supplements moderation.php.  While moderation.php actually moves data from the <plugin name> submission table to the main <plugin name> table, this function executes all other submission approval tasks including any other database updates required by your plugin.
 |-
 |8
 |[[#plugin_moderationdelete_<plugin name>|plugin_moderationdelete_<plugin name>]]
-|This optional function supplements moderation.php.  While moderation.php actually removes data from the <plugin name>submission table, this function executes all other submission removal tasks including any other database updates required by your plugin.
+|This optional function supplements moderation.php.  While moderation.php actually removes data from the <plugin name> submission table, this function executes all other submission removal tasks including any other database updates required by your plugin.
 |}
@@ Line 74: / Line 74: @@
 === Plugin database changes ===
-The table <plugin name>submission must be the name of your submission
+The table <plugin name> submission must be the name of your submission
 table.  This table can only contain a proper subset of the columns from the main <plugin name> table.  This allows the moderation.php script to
 automatically copy those columns from the submission to the main table upon

@@ Line 32: / Line 32: @@
 |3
 |[[#plugin_savesubmission_<plugin name>|plugin_savesubmission_<plugin name>]]
-|Takes the data input by the plugin submission form and populates the <plugin name>submission table with that data.
+|Takes the data input by the plugin submission form and populates the <plugin name> submission table with that data.
 |-

← Older revision		Revision as of 20:18, 10 May 2008
Line 314:		Line 314:
	if found. As of now the return value for this function is ignored.		if found. As of now the return value for this function is ignored.

−	[[Category:~~Plugin_Developers_Handbook~~]]	+	[[Category:Plugin Development]]

← Older revision		Revision as of 14:00, 1 July 2004
Line 313:		Line 313:
	extraneous data (that should not exist in most cases) and that data is removed		extraneous data (that should not exist in most cases) and that data is removed
	if found. As of now the return value for this function is ignored.		if found. As of now the return value for this function is ignored.
		+
		+	[[Category:Plugin_Developers_Handbook]]