glFusion Wiki

Site Tools


glfusion:development:pluginapi:moderation

Moderation Functions

This section will describe how to enable your plugin to use the glFusion 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 glFusion developers have made the implementation of this API very straight forward and enabled the API calls into the moderation related core programs.

There are conventions used in the current glFusion code base that will force you to name your plugin tables used for submission in a specific manner. All moderated glFusion items such as stories and links are comprised of two tables. The first is a main table where all visible items are stored. The second is a submission table where submitted user items sit until an administrator approves them. When approved, the item is moved from the submission table to the main table.

For example, if you are writing a book review plugin that allows users to submit book reviews then you will pick bookreviews for your main table name (this MUST also be your plugin name you pick), and then your submission table MUST be named bookreviewssubmission. Why force the names? Because in the glFusion code the submission table for all stories is coded as <main name>submission. So since we picked bookreviews for our main table (and plugin name) the submission table must be named bookreviewssubmission.

In glFusion 1.1.0, a change to plugin_itemlist_<pluginname> removes all of these restrictions at the cost of requiring the plugin author handle all the approve process coding. See plugin_itemlist_<pluginname> below for more details.

If you want your plugin to be moderated like glFusiom stories and links then you must implement these functions.

How to Call the Moderation Engine

After you implement the moderation functions in your plugin, you will need to call the glFusion 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 public_html/submit.php or public_html/admin/moderation.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 public_html/admin/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 moderation.php 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.

plugin_ismoderator_<plugin name>

This function checks if the current user has rights to moderate for the plugin and returns true if this is the case, false otherwise. If this function does not return true for a given user, that user will not be able to access the moderation screen.

Arguments

Code Example

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. Sincce 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() {
 
   global $_USER, $_TABLES;
   return SEC_hasRights('lists.admin');
 
}

plugin_submissioncount_<plugin name>

This function calculates the current number of submissions awaiting moderation and returns that number. 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.

Arguments

Code Example

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

plugin_itemlist_<plugin name>

This function uses the plugin class to return data required by moderation.php to list plugin objects that need to be moderated.

Arguments

($token)

This is a CSRF token for the moderation.php page. It is only needed if you are implementing your own moderation using a string return from this function.

Code Example

The function plugin_itemlist returns a Plugin() class or an string of valid HTML containing information that will displayed on the moderation.php page.

Built-in Method

Returning the Plugin class object requires less coding and gives you access to the built-in infrastructure for submission approval. The following member variables of the Plugin class must be filled out:

  • submissionlabel: The title that indicate the plugin submission section.
  • getsubmissionsql: A SQL query that will select all the data that will be displayed in the plugin submission section.
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;
   }
 
}

Self-Coded Method

If this function returns a string, the string is added straight to the moderation screen as is. In this case, it is assumed the plugin has provided an HTML form containing the list of submissions awaiting approval. The plugin is responsible for all aspects of this form and only this function, plugin_submissioncount_<> and plugin_ismoderator_<> will ever be called by glFusion for your plugin.

Use the $token argument in your forms to protect against CSRF as described in the SEC_checkToken() documentation.

plugin_savesubmission_<plugin name>

This function takes the data input by the plugin submission form and populates the <plugin name>submission table with that data. Optionally, this function can use different logic for an admin 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.

Arguments

Code Example

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>

This function 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. This information is used to automatically copy information from the plugin submission table to the plugin main table when a submission is approved.

Arguments

Code Example

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

plugin_submit_<plugin name>

This function returns a string containing the HTML to display the plugin submission form. It is recommended to use the GL template functionality 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.

Arguments

Code Example

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

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.

In the case of the Mailing 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.

Arguments

Code Example

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>

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.

In the case of the Mailing 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.

Arguments

Code Example

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);
 
}
glfusion/development/pluginapi/moderation.txt · Last modified: 2017/04/12 21:13 (external edit)

Page Tools