Difference between revisions of "Adding Moderation Capability"

Revision as of 09:02, 5 May 2009

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:

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.

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 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_moderationvalues_lists()
{
    global $_TABLES;

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

4) 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_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;

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

6) 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_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. 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_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. 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.