View source for Adding Moderation Capability

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:

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

|-
|6
|[[#plugin_submit_<plugin name>|plugin_submit_<plugin name>]]
|Returns a string containing the HTML to display the plugin submission form.

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

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

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

<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
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>====
<pre>
function plugin_ismoderator_lists()
{
    global $_USER, $_TABLES;

    return SEC_hasRights('lists.admin');
}
</pre>

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

<pre>
function plugin_submissioncount_lists()
{
    global $_TABLES;

    return DB_count($_TABLES['listssubmission']);
}
</pre>

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

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

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

<pre>
function plugin_moderationvalues_lists()
{
    global $_TABLES;

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

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

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

====plugin_submit_<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.

<pre>
function plugin_submit_lists()
{
    global $_CONF, $LANG12;

    if ($_CONF['listssubmission'] == 0 &amp;&amp; !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');
}
</pre>

====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>
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 '';
}
</pre>

====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>
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);
}
</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]]