Difference between revisions of "Adding Moderation Capability"

From GeeklogWiki
Jump to: navigation, search
(Move explanations into the right paragraphs)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This section will describe and document how to enable your plugin to use the
+
This section will describe and document how to enable your plugin to use the Geeklog moderation engine.
Geeklog moderation engine. This set of functions is optional when creating your
+
 
plugin, but should be used when your plugin has functionality that includes  
+
==Note==
submitting of an item that needs to be reviewed by a site admin or plugin admin  
+
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  
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.
 
core programs.
  
 
+
===Version note===
'''NOTE: '''You will need to be using Geeklog version 1.3.7 or apply the  
+
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
+
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.
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.
 
Refer to the appendix if you have a previous release and want to review the needed changes.
  
 +
==The functions==
 +
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. 
  
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:
 
The following table summarizes the functions:
  
 +
{|cellPadding="2" width="100%" border="1"
 +
!width=4%|
 +
!Function
 +
!Description of Function
 +
|-
 +
|1
 +
|[[#plugin_ismoderator_<plugin name>|plugin_ismoderator_<plugin name>]]
 +
|Checks if the current user has rights to moderate for the plugin and returns true if this is the case, false otherwise.
 +
 +
|-
 +
|2
 +
|[[#plugin_submissioncount_<plugin name>|plugin_submissioncount_<plugin name>]]
 +
|Calculates the current number of submissions awaiting moderation and returns that number.
 +
 +
|-
 +
|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.
 +
 +
|-
 +
|4
 +
|[[#plugin_moderationvalues_<plugin name>|plugin_moderationvalues_<plugin name>]]
 +
|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.
 +
 +
|-
 +
|5
 +
|[[#plugin_itemlist_<plugin name>|plugin_itemlist_<plugin name>]]
 +
|Uses the plugin class to return data required by moderation.php to list plugin objects that need to be moderated.
  
<table cellPadding="2" width="100%" border="1">
+
|-
    <tr>
+
|6
      <th width="4%"> </th>
+
|[[#plugin_submit_<plugin name>|plugin_submit_<plugin name>]]
      <th width="32%">Function</th>
+
|Returns a string containing the HTML to display the plugin submission form.
      <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 ===
+
|-
 +
|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.
  
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.
+
|8
This can be done by adding a link or button which redirects the user to submit.php
+
|[[#plugin_moderationdelete_<plugin name>|plugin_moderationdelete_<plugin name>]]
or moderate.php with the necessary parameters from 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.
 +
|}
  
 +
=== How to call the Moderation Engine ===
  
The example below was used by the Mailing Lists plugin to link to the 'submit
+
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.
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.
 
  
 +
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>"
+
<pre>$retval = "<a href='" . $_CONF['site_url'] . "/submit.php?type=lists'>" . $LANG_LISTS['SUBMITLIST'] . "</a>";</pre>
  
 
'''Admin interaction with the Moderation Engine:''' Once all the moderation
 
'''Admin interaction with the Moderation Engine:''' Once all the moderation
functions are implemented, the 'Submissions' link in the admin block will include
+
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 your 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.
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 ===
 
=== 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  
+
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  
<plugin name> table.  This allows the moderation.php script to  
 
 
automatically copy those columns from the submission to the main table upon
 
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
+
approval.  All data in columns of the submission table that are not in the main table will be lost.
table will be lost.
 
  
 +
=== Function details and examples ===
  
=== 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.
  
This explanation of the plugin moderation API functions will use the Mailing
+
====plugin_ismoderator_<plugin name>====
Lists plugin for examples and give a detailed description of each function.
 
  
 +
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.
  
plugin_ismoderator_lists() {
+
<pre>
 +
function plugin_ismoderator_lists()
 +
{
 
     global $_USER, $_TABLES;
 
     global $_USER, $_TABLES;
 +
 
     return SEC_hasRights('lists.admin');
 
     return SEC_hasRights('lists.admin');
 
}
 
}
 +
</pre>
  
1) The '''''plugin_ismoderator''''' function simply returns TRUE if
+
====plugin_submissioncount_<plugin name>====
the current user has moderation privileges for the plugin.  In the example
+
 
to the right, The mailing lists plugin simply uses the security function
+
The '''''plugin_submissioncount''''' function returns the number of
SEC_hasRights to determine if a user has the required rightsThe lists.admin
+
submissions for this plugin that are awaiting moderationThis value is used to indicate the number of waiting submissions in the admin blockA DB_count() on the plugin submission table is usually sufficient for this.
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() {
+
<pre>
 +
function plugin_submissioncount_lists()
 +
{
 
     global $_TABLES;
 
     global $_TABLES;
 +
 
     return DB_count($_TABLES['listssubmission']);
 
     return DB_count($_TABLES['listssubmission']);
 
}
 
}
 +
</pre>
  
2) The''''' plugin_submissioncount''''' function returns the number of
+
====plugin_savesubmission_<plugin name>====
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
 +
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 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
 +
will redirect the user back to the Geeklog home page.
  
function plugin_savesubmission_lists($A) {
+
<pre>
 +
function plugin_savesubmission_lists($A)
 +
{
 
     global $_TABLES, $_USER, $_CONF;
 
     global $_TABLES, $_USER, $_CONF;
  
Line 174: Line 163:
 
     return true;
 
     return true;
 
}
 
}
 +
</pre>
  
 +
====plugin_moderationvalues_<plugin name>====
  
3) The '''''plugin_savesubmission''''' function takes data entered into
+
The '''''plugin_moderationvalues''''' function returns important information used by the Plugin API to handle plugin submissionsIt 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
the submission form and saves it to the submission tableOptionally, this function
+
copy information from the plugin submission table to the plugin main table when a submission is approved.
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() {
+
<pre>
 +
function plugin_moderationvalues_lists()
 +
{
 
     global $_TABLES;
 
     global $_TABLES;
 +
 
     return array('ml_id', $_TABLES['lists'], 'ml_id, ml_name, ml_descr', $_TABLES['listssubmission']);
 
     return array('ml_id', $_TABLES['lists'], 'ml_id, ml_name, ml_descr', $_TABLES['listssubmission']);
 
}
 
}
 +
</pre>
  
 +
====plugin_itemlist_<plugin name>====
  
4) This '''''plugin_moderationvalues''''' function returns important information used by the
+
The function '''''plugin_itemlist''''' returns a Plugin() class containing information that will displayed on the moderation.php pageThe following member variables of the Plugin class must be filled out:
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() {
+
* '''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.
 +
 
 +
<pre>
 +
function plugin_itemlist_lists()
 +
{
 
     global $_TABLES;
 
     global $_TABLES;
  
Line 215: Line 203:
 
     }
 
     }
 
}
 
}
 +
</pre>
  
 +
====plugin_submit_<plugin name>====
  
5) The function '''''plugin_itemlist''''' returns a Plugin() class containing information
+
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 formSee 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.
that will displayed on the moderation.php pageThe following member variables
 
of the Plugin class must be filled out:
 
  
*'''submissionlabel:''' The title that indicate the plugin submission section.
+
<pre>
*'''getsubmissionsql:''' An SQL query that will select all the data that will
+
function plugin_submit_lists()
        be displayed in the plugin submission section.  NOTE: one item (the unique
+
{
        id column) must be labeled id ('as id').
+
     global $_CONF, $LANG12;
*'''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 &amp;&amp; !SEC_hasRights('lists.admin')) {
 
     if ($_CONF['listssubmission'] == 0 &amp;&amp; !SEC_hasRights('lists.admin')) {
Line 236: Line 218:
 
     }
 
     }
  
     if ($HTTP_POST_VARS['mode'] == $LANG12[32]) { // preview
+
     if ($_POST['mode'] == $LANG12[32]) { // preview
         $A = $HTTP_POST_VARS;
+
         $A = $_POST;
    $ml_id = $A['ml_id'];
+
        $ml_id = $A['ml_id'];
 
     } else {
 
     } else {
 
         $ml_id = COM_makesid();
 
         $ml_id = COM_makesid();
Line 256: Line 238:
 
     return $template->parse('output', 'form');
 
     return $template->parse('output', 'form');
 
}
 
}
 +
</pre>
  
6) The function '''''plugin_submit''''' creates HTML that contains the submission
+
====plugin_moderationapprove_<plugin name> ====
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) {
+
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>
 +
function plugin_moderationapprove_lists($id)
 +
{
 
     global $_TABLES, $_USER, $_CONF;
 
     global $_TABLES, $_USER, $_CONF;
  
Line 286: Line 269:
 
     return '';
 
     return '';
 
}
 
}
 +
</pre>
  
7) Although the moderation.php script takes care of the work
+
====plugin_moderationdelete_<plugin name>====
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) {
+
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.
 +
 
 +
<pre>
 +
function plugin_moderationdelete_lists($id)
 +
{
 
     global $_TABLES;
 
     global $_TABLES;
  
Line 305: Line 286:
 
     DB_delete($_TABLES['listpermissions'], 'ml_id', $id);
 
     DB_delete($_TABLES['listpermissions'], 'ml_id', $id);
 
}
 
}
 +
</pre>
 +
  
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.
 
  
[[Category:Plugin_Developers_Handbook]]
+
[[Category:Plugin Developers Handbook]] [[Category:Plugin Development]]

Latest revision as of 17:28, 31 March 2010

This section will describe and document how to enable your plugin to use the Geeklog moderation engine.

Note

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.

Version 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.

The functions

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:

Function Description of Function
1 plugin_ismoderator_<plugin name> Checks if the current user has rights to moderate for the plugin and returns true if this is the case, false otherwise.
2 plugin_submissioncount_<plugin name> Calculates the current number of submissions awaiting moderation and returns that number.
3 plugin_savesubmission_<plugin name> Takes the data input by the plugin submission form and populates the <plugin name> submission table with that data.
4 plugin_moderationvalues_<plugin name> 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.
5 plugin_itemlist_<plugin name> Uses the plugin class to return data required by moderation.php to list plugin objects that need to be moderated.
6 plugin_submit_<plugin name> Returns a string containing the HTML to display the plugin submission form.
7 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.
8 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.

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 your 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_<plugin name>

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_ismoderator_lists()
{
    global $_USER, $_TABLES;

    return SEC_hasRights('lists.admin');
}

plugin_submissioncount_<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.

function plugin_submissioncount_lists()
{
    global $_TABLES;

    return DB_count($_TABLES['listssubmission']);
}

plugin_savesubmission_<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. 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 will redirect the user back to the Geeklog home page.

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;
}

plugin_moderationvalues_<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.

function plugin_moderationvalues_lists()
{
    global $_TABLES;

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

plugin_itemlist_<plugin name>

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_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;
    }
}

plugin_submit_<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 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_submit_lists()
{
    global $_CONF, $LANG12;

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

    if ($_POST['mode'] == $LANG12[32]) { // preview
        $A = $_POST;
        $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');
}

plugin_moderationapprove_<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.

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 '';
}

plugin_moderationdelete_<plugin name>

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.

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);
}