:: View topic - HOW-TO : Plugin for the pncUserPoints

Tutorials and programming - HOW-TO : Plugin for the pncUserPoints

Chestnut - Jan 28, 2004 - 11:41 AM
Post subject: HOW-TO : Plugin for the pncUserPoints

Here are the basics for creating a plugin

1 - The plugin file should be named like the last part of the plugin function
Example :

Code:

function pncUserPoints_userapi_NAMEOFPLUGIN($args)
{

// Ratata

}

File : NAMEOFPLUGIN.php

2 - Parameters that the function will receive :

$up : This var contains what is already counted.

Code:

$up[$uname]['pluginfunction'] = number of items;
$up[$uname]['TOTAL'] = $up[$uname]['TOTAL'] + (nb of items * value);
// optional
$up[$username]['uid'] = $uid;

$sqlexclude : This contains the usernames that we don't want to count.

Code:

$sql = "SELECT $ucolumn[uid],
$ucolumn[uname],
count(*) as ncount
FROM $pntable[stories],
$pntable[users]
WHERE $scolumn[informant] = $ucolumn[uname]
-----> $sqlexclude
AND $scolumn[time] > '".pnVarPrepForStore($vardate)."'
GROUP BY $scolumn[informant]
ORDER BY ncount DESC, $ucolumn[uname] ASC";

$value : The value in points for the item

Code:

$points = $ncount * $value; // $ncount in this case is the total of items
//...
$up[$uname]['TOTAL'] = $up[$uname]['TOTAL'] + $points;

$lastupdate : The UNIX timestamp of last update.
This is to calculate from when the items should be counted.

Code:

$vardate = date("Y-m-d H:i:s", $lastupdate);

At the moment, this part is OK :

Code:

AND $scolumn[time] > '".pnVarPrepForStore($vardate)."'

But in BETA, a new variable will be sended to the function :
$dateoveride (true/false)

What I suggest is that you do this :

Code:

if (isset($dateoveride) && $dateoveride == true) {
$datesql = "";
} else {
$vardate = date("Y-m-d H:i:s", $lastupdate);
$datesql = "AND $scolumn[time] > '".pnVarPrepForStore($vardate)."'";
}

then :

Code:

$sql = "SELECT $ucolumn[uid],
$ucolumn[uname],
count(*) as ncount
FROM $pntable[stories],
$pntable[users]
WHERE $scolumn[informant] = $ucolumn[uname]
$sqlexclude
-----> $datesql
GROUP BY $scolumn[informant]
ORDER BY ncount DESC, $ucolumn[uname] ASC";

3 - The less sql queries the better.

See the pncUserPoints_userapi_stories function in pnuserapi.php
I use only one query to fetch the count of item for each user.

Code:

$sql = "SELECT $ucolumn[uid],
$ucolumn[uname],
count(*) as ncount
FROM $pntable[stories],
$pntable[users]
WHERE $scolumn[informant] = $ucolumn[uname]
$sqlexclude
AND $scolumn[time] > '".pnVarPrepForStore($vardate)."'
GROUP BY $scolumn[informant]
ORDER BY ncount DESC, $ucolumn[uname] ASC";

Then I insert in $up the result

Code:

if (!$result->EOF) {

for( ; !$result->EOF; $result->MoveNext()) {

list($uid, $uname, $ncount) = $result->fields;

$points = $ncount * $value;

$up[$uname]['stories'] = $ncount;
$up[$uname]['uid'] = $uid;
$up[$uname]['TOTAL'] = $up[$uname]['TOTAL'] + $points;
}

}

That is the big difference with the old userpoints wich was doing one query for each user. This method use one query for all we need.

If you look at the xforum plugin, I used 2 queries because there was data in 2 tables. But that doesn't change much the method ---> one query for each table.

The old method was too ressources consuming and that is why it wasn't updating evrything if the action was too long or too big.

4 - Then, we return to the module what we just did (don't forget to close your $result) :

Code:

$result->Close();

return $up;

-----

Here is the whole stories function for example... (the dateoveride is not include in it yet).

Code:

// Points for Stories
function pncUserPoints_userapi_stories($args)
{

extract($args);

list($dbconn) = pnDBGetConn();
$pntable = pnDBGetTables();

$scolumn = &$pntable['stories_column'];
$ucolumn = &$pntable['users_column'];

$vardate = date("Y-m-d H:i:s", $lastupdate);

$sql = "SELECT $ucolumn[uid],
$ucolumn[uname],
count(*) as ncount
FROM $pntable[stories],
$pntable[users]
WHERE $scolumn[informant] = $ucolumn[uname]
$sqlexclude
AND $scolumn[time] > '".pnVarPrepForStore($vardate)."'
GROUP BY $scolumn[informant]
ORDER BY ncount DESC, $ucolumn[uname] ASC";

$result = $dbconn->Execute($sql);

if (!$result->EOF) {

for( ; !$result->EOF; $result->MoveNext()) {

list($uid, $uname, $ncount) = $result->fields;

$points = $ncount * $value;

$up[$uname]['stories'] = $ncount;
$up[$uname]['uid'] = $uid;
$up[$uname]['TOTAL'] = $up[$uname]['TOTAL'] + $points;

}

}

$result->Close();

return $up;

}

Note : YOU MUST use the $up var as the recipient of the data... the $up that the function receives may already contain the data from other plugins and if you don't use $up, the total won't be incremented.

Note 2 :

The plugin will be in modules/pncUserPoints/plugins/YOURPLUGIN.php

The language file for the plugin must be in :

modules/pncUserPoints/pnlang/YOURLANG/YOURPLUGIN.php

Chestnut - Jan 28, 2004 - 01:30 PM
Post subject: How to tell the module about the New Plugin

After you have made your plugin and that the files are in place

modules/pncUserPoints/plugins/YOURPLUGIN.php for the function

modules/pncUserPoints/pnlang/YOURLANG/YOURPLUGIN.php for the language file

You need to add it to the module.

In the pncUserPoints administration, go to the Plugins Admin Page.
At the bottom, you have a form with these fields :

Plugin Name
Function
Lang Constant
Values in Points
Active.

The plugin name doesn't matter much, it is for your convenience in the list above.
The function is the exact name of the filename WITHOUT the extension.

example : xforum

It is also the name of the function

example : function pncUserPoints_userapi_xforum($args)

The lang Constant is the constant the module will load in the modules/pncUserPoints/pnlang/YOURLANG/YOURPLUGIN.php file.

example : _PNCUPXFORUM
In modules/pncUserPoints/pnlang/eng/xforum.php, I have :

Code:

define('_PNCUPXFORUM', 'XForum Posts');

The value in points is ... well... you know, the value of each item
And active or not... is active or not.

Wink