Differences

This shows you the differences between two versions of the page.

--- userpoints:developer [2023/05/02 14:05] – created admin
+++ userpoints:developer [2024/04/02 18:39] (current) – admin
@@ Line 1: / Line 1: @@
-====== BetaUserPoints API documentation ======
+====== UserPoints Integrations and API ======
-Introduction BetaUserPoints - API integration in a Third party component (advanced)
+This is an introduction to UserPoints integrations with Joomla or third party extensions. It is dedicated to developers and anyone with a sufficient knowledge of the PHP language and Joomla 4/5 extension development. There is a UserPoints API which has recently been simplified.
-This documentation is dedicated to developers and anyone with a sufficient knowledge of the PHP language and Joomla 4 component development.
+Licence: UserPoints is released under license GNU/GPL License. Author: Bernard Gilly – Adrien Roussel - Martin Brampton. This project started as AlphaUserPoints back in 2008.
-Licence: BetaUserPoints is released under license GNU/GPL License. Author: Bernard Gilly – Adrien Roussel - Martin Brampton. This project started as AlphaUserPoints back in 2008.
-===== Plugin/Rule creation =====
+===== Basic Operation of UserPoints =====
-A plugin creation (new rule creation for a 3rd party component) is done in 2 steps
+UserPoints provides a way to award users points for specific actions on a Joomla based web site. Points can also be "spent" in order to permit other actions. The actions involved are specific to whatever applications are appropriate for the site. It is possible, but not necessary, to equate points to monetary value.
+The handling of points is determined by what are called **rules** in UserPoints. A rule is triggered by something happening as a result of user action. The rule determines what happens in the way of awarding or deducting points. UserPoints automatically installs some plugins and rules that support actions triggered by standard Joomla extensions. These include actions to do with content (articles) and to do with user registration.
-=== Step1 - API insertion in a component ===
+Unfortunately, for historic reasons, rules are identified by a plugin name. It is often not necessary for there to be an actual plugin corresponding to the name. The term plugin name should be understood as being the rule name.
-Just insert the following API in the component code where needed. The best way is to make it follow a user action that could give the users some points or take some. For example : in a comment system component or in a forum, just add the API after the comment or topic INSERT query in the database.
+===== Ways to Connect Software to UserPoints =====
+The approach is different, depending on whether the author of the software to be connected is implementing code to help the integration. If this is the case, then any rules needed for the integration can be specified by an XML file in the root of the component involved. The software then uses the API described below to interact with UserPoints. No new plugin is needed for this kind of integration.
+Alternatively, it may be possible to achieve integration without modifying the relevant software. If it provides plugin hooks, then a plugin can be written that will be triggered by events in the third party software. The plugin can use the API. The administrator UI of UserPoints provides the ability to create and modify rules to manage the integration.
 === Basic API ===
+The UserPoints code has been fully namespaced and will autoload when used correctly. In addition, for Joomla 3.x, UserPoints automatically installs and enables a plugin that will establish the namespacing. This is not necessary with Joomla 4+ which takes account of the namespace in the UserPoints packaging XML.
+Given the above, use of the API becomes in its simplest form:
 <code php>
-    $api_BUP = JPATH_SITE.'/components/com_betauserpoints/helper.php';
+    use BlackSheepResearch\Component\UserPoints\Site\UserPoints;
-    if ( file_exists($api_BUP))
+    if (class_exists(UserPoints::class) {
-    {
+        UserPoints::newpoints('rule_name');
-        require_once $api_BUP; BetaUserPointsHelper::newpoints( 'function_name' );
     }
 </code>
-function_name is the name of the rule that will be used to attribute points to the current user (if logged in). For each BetaUserPoints integrated rule (system rules), names syntax is as follows:
+rule_name is the name of the rule that will be used to attribute points to the current user (if logged in). For each UserPoints integrated rule (system rules), names syntax is as follows:
 example: sysplgbup_newregistered for new users points attribution
-It is convenient to keep the same name syntax for third party components plugin as follows:
+You should select names for rules that are unlikely to conflict with other integrations.
-plgbup_functionname
-Example: plgbup_newcomment or plgbup_newtopic for a comment system or forum API integration. To name a rule that would give points when adding a new topic in Kunena: plgbup_kunena_topic_create.
 Keep in mind that this method only gives points to the current user logged in. This is the Basic API.
@@ Line 42: / Line 44: @@
 === Attribute points to another user than the current user ===
-To give points to anothe user than the one connected, only the user id is required. To get his BetaUserPoints (BUPID) Identity, we just need to use the getAnyUserReferreID(). This method is the one used to give points to an article author when the article is being read by someone on the site.
+To give points to another user than the one connected, only the rule and user ID is required. To get his UserPoints (BUPID) Identity, we just need to use the getAnyUserReferreID(). This method is the one used to give points to an article author when the article is being read by someone on the site.
 <code php>
-    $api_BUP = JPATH_SITE.'/components/com_betauserpoints/helper.php';
+    use BlackSheepResearch\Component\UserPoints\Site\UserPoints;
-    if ( file_exists($api_BUP))
+    if (class_exists(UserPoints::class) {
-    {
+        $upid = UserPoints::getAnyUserReferreID( $userID );
-        require_once $api_BUP;
+        if ( $bupid ) UserPoints::newpoints( 'rule_name', $upid );
-        $bupid = BetaUserPointsHelper::getAnyUserReferreID( $userID );
-        if ( $bupid ) BetaUserPointsHelper::newpoints( 'function_name', $bupid );
     }
 </code>
@@ Line 56: / Line 56: @@
 === Avoid attributing points more than once for the same action ===
-To avoid a user getting points many times for something already done, we can add a reference key. When calling the BetaUserPointsHelper::newpoints function, a precheck is done on this reference key. This method is used in the rule where a user reading an article would give points to the author.
+To avoid a user getting points many times for something already done, we can add a reference key. When calling the UserPoints::newpoints function, a precheck is done on this reference key. This method is used in the rule where a user reading an article would give points to the author.
 <code php>
-    $api_BUP = JPATH_SITE.'/components/com_betauserpoints/helper.php';
+    use BlackSheepResearch\Component\UserPoints\Site\UserPoints;
-    if ( file_exists($api_BUP))
+    if (class_exists(UserPoints::class) {
-    {
+        $keyreference = UserPoints::buildKeyreference('rule_name', 'item id' );
-        require_once $api_BUP;
+        UserPoints::newpoints( 'rule_name', '', $keyreference);
-        $keyreference = BetaUserPointsHelper::buildKeyreference('function_name', 'item id' );
-        BetaUserPointsHelper::newpoints( 'function_name', '', $keyreference);
     }
 </code>
-=== Adding information datas ===
+=== Adding information data ===
-To add information datas to be displayed in the action details, just add a new parameter as follows:
+To add information data to be displayed in the action details, just add a new parameter as follows:
 <code php>
-    $api_BUP = JPATH_SITE.'/components/com_betauserpoints/helper.php';
+    use BlackSheepResearch\Component\UserPoints\Site\UserPoints;
-    if ( file_exists($api_BUP))
+    if (class_exists(UserPoints::class) {
-    {
+        $keyreference = UserPoints::buildKeyreference('rule_name', 'item id' );
-        require_once $api_BUP;
+        UserPoints::newpoints( rule_name','', $keyreference,'information_data');
-        $keyreference = BetaUserPointsHelper::buildKeyreference('function_name', 'item id' );
-        BetaUserPointsHelper::newpoints( function_name','', $keyreference,'information_datas');
     }
 </code>
@@ Line 84: / Line 80: @@
 === Using different amounts of points on the same rule ===
-A component might also need to add or to take points for different amounts. For example, when buying goods with points. Products have different prices, a fixed amount in the rule would'nt make it. The API $randompoints parameter comes instead of the amount of points set in the rule. It can be negative in case of purchases or penalities.
+A component might also need to add or to take points for different amounts. For example, when buying goods with points. Products have different prices, a fixed amount in the rule would not work. The API $randompoints parameter comes instead of the amount of points set in the rule. It can be negative in case of purchases or penalities.
 <code php>
-    $api_BUP = JPATH_SITE.'/components/com_betauserpoints/helper.php';
+    use BlackSheepResearch\Component\UserPoints\Site\UserPoints;
-    if ( file_exists($api_BUP))
+    if (class_exists(UserPoints::class) {
-    {
+        $keyreference = UserPoints::buildKeyreference('rule_name', 'item id' );
-        require_once $api_BUP;
+        UserPoints::newpoints( 'rule_name','', $keyreference,'',-1450);
-        $keyreference = BetaUserPointsHelper::buildKeyreference('function_name', 'item id' );
-        BetaUserPointsHelper::newpoints( function_name','', $keyreference,'',-1450);
     }
 </code>
@@ Line 98: / Line 92: @@
 === Get the result from a successful operation ===
-In a more advanced code, if the component routine needs to know if the operation has been successful or not, (enough amount of points for a purchase in a user account), we can add a 'feedback' parameter. It has a Boolean type value. Code example:
+In more advanced code, if the new software needs to know if the operation has been successful or not, (enough amount of points for a purchase in a user account), we can add a 'feedback' parameter. It has a Boolean type value. Code example:
 <code php>
-    $api_BUP = JPATH_SITE.'/components/com_betauserpoints/helper.php';
+    use BlackSheepResearch\Component\UserPoints\Site\UserPoints;
-    if ( file_exists($api_BUP))
+    if (class_exists(UserPoints::class) {
-    {
+        $keyreference=UserPoints::buildKeyreference('up_purchasewithvirtuemart', $transactionID );
-        require_once $api_BUP;
+        if (UserPoints::newpoints( 'up_purchasewithvirtuemart', '', $keyreference, 'Product reference: AM-5245', -1290, true))
-        $keyreference=BetaUserPointsHelper::buildKeyreference('plgbup_purchasewithvirtuemart', $transactionID );
-        if (BetaUserPointsHelper::newpoints( 'plgbup_purchasewithvirtuemart', '', $keyreference, 'Product reference: AM-5245', -1290, true))
         {
-            [... code continued ...]
+            [... code for successful operation ...]
         }
     }
@@ Line 117: / Line 109: @@
 In a customized code component, you can force and remove the constraint on a rule to the user level by adding the parameter _force = 1_. The existing rule will be available now for _guest, registered_ and _special_.
-=== Display an additional system message on frontend ===
+=== Display an additional system message to the user ===
-you can display a specific message on frontend by adding the parameter frontmessage=”You custom message”. API full implementation
+you can display a specific message to the user by adding the parameter frontmessage=”You custom message”. API full implementation
 <code php>
-    BetaUserPointsHelper::newpoints(
+    use BlackSheepResearch\Component\UserPoints\Site\UserPoints;
-        string$pluginfunction,
+    if (class_exists(UserPoints::class) {
-        [string$BUPIDotheruser = ''],
+      UserPoints::newpoints(
-        [string$keyreference = ''],
+        string $pluginfunction,
-        [string$data = ''],
+        [string $BUPIDotheruser = ''],
-        [integer$randompoints = 0],
+        [string $keyreference = ''],
-        [boolean$feedback = false],
+        [string $data = ''],
-        [integer$force=0],
+        [integer $randompoints = 0],
-        [string$frontmessage='']
+        [boolean $feedback = false],
-    );
+        [integer $force=0],
+        [string $frontmessage='']
+      );
+    }
 </code>
-Note: If the operation is a points substraction, the account has to have at least the same amount of points. If not, a notice warns the user that he doe'snt have enough points to complete the action (by default). You can set up general parameter in the configuration of BetaUserPoints, in backend administrator to allows your users to have a negative account.
+Note: If the operation is a points substraction, the account has to have at least the same amount of points. If not, a notice warns the user that he does not have enough points to complete the action (by default). You can set up an option in the configuration of UserPoints, as administrator to allow your users to have a negative account.
 ==== Step 2 - XML file creation ====
-Then developers have to create an xml file to make easier the installation process in the BetaUserPoints component. This xml file has to be utf-8 encoded (required). All developers of third party extensions for Joomla! can add directly at the root of their frontend component a unique xml file containing all the rules for a single component. Deveoper has to respect the ordering and tags: structure example: [betauserpoints_rule.xml](images/stories/documentation/betauserpoints/betauserpoints_rule.xml) Tag “component” is the name of the third component like “com_kunena” or other. As it is the same component, it is worth repeating for each rule in the tag “rule”.
+Then developers have to create an xml file to make easier the installation process in the UserPoints component. This xml file has to be utf-8 encoded (required). All developers of third party extensions for Joomla! can add directly at the root of their frontend component a unique xml file containing all the rules for a single component. Deveoper has to respect the ordering and tags: structure example: [betauserpoints_rule.xml](images/stories/documentation/betauserpoints/betauserpoints_rule.xml) Tag “component” is the name of the third component like “com_kunena” or other. As it is the same component, it is worth repeating for each rule in the tag “rule”.
-Administrator of the website which install a third component with this xml file can autodetect directly from the button “auto-detect plugins” in control panel of BetaUserPoints.
+Administrator of the website which install a third component with this xml file can autodetect directly from the button “auto-detect plugins” in control panel of UserPoints.
 This xml file has to be utf-8 encoded (required) but not be zipped! Just put this file at the root of frontend component folder or plugin or module and include this file in your installer extension. This file must be named exactly as follows: betauserpoints_rule.xml
@@ Line 168: / Line 163: @@
 - auto-detect xml file at the root of frontend component:
-Click on the button “Auto-detect plugins” in the control panel of BetaUserPoints after installation of third component, plugin or module. Check regularly or periodically by clicking on this button.
+Click on the button “Auto-detect plugins” in the control panel of UserPoints after installation of third component, plugin or module. Check regularly or periodically by clicking on this button.
-==== Using BetaUserPoints information in a third party component ====
+==== Using UserPoints information in a third party component ====
 You can use easily the profil informations of a user directly in a third component.
@@ Line 176: / Line 171: @@
 <code php>
-$api_BUP = JPATH_SITE.'/components/com_betauserpoints/helper.php'; if ( file_exists($api_BUP)) { require_once $api_BUP; }
+$api_UP = JPATH_SITE.'/components/com_userpoints/helper.php'; if ( file_exists($api_UP)) { require_once $api_UP; }
 </code>
@@ Line 182: / Line 177: @@
 To get the entire profil information, just use the function getUserInfo();
-Just use the referreid of BetaUserPoints user or the joomla ID of the user (Id of Joomla users table).
+Just use the referreid of UserPoints user or the joomla ID of the user (Id of Joomla users table).
 Use the first method with the referreid to get user Information profile like this :
 <code php>
-BetaUserPointsHelper::getUserInfo($referrerid );
+UserPoints::getUserInfo($referrerid );
 </code>
@@ Line 193: / Line 188: @@
 <code php>
-$user = JFactory::getUser(); $userid = $user->id ; $profil = BetaUserPointsHelper::getUserInfo ( '', $user->id );
+$user = JFactory::getUser(); $userid = $user->id ; $profil = UserPoints::getUserInfo ( '', $user->id );
 </code>
@@ Line 241: / Line 236: @@
 === Get BUP avatar of user ===
-Display the image of avatar from BetaUserPoints.
+Display the image of avatar from UserPoints.
 <code php>
-$avatar = BetaUserPointsHelper:: getAupAvatar( $userid, [$linktoprofil=0], [ $width=48], [$height=48], [$class=''], [$otherprofileurl=''] ) echo $avatar ;
+$avatar = UserPoints:: getAupAvatar( $userid, [$linktoprofil=0], [ $width=48], [$height=48], [$class=''], [$otherprofileurl=''] ) echo $avatar ;
 </code>
@@ Line 255: / Line 250: @@
 <code php>
-$linktoBUPprofil = BetaUserPointsHelper::getAupLinkToProfil($userid);
+$linktoBUPprofil = UserPoints::getAupLinkToProfil($userid);
 </code>
@@ Line 263: / Line 258: @@
 <code php>
-$linktoBUPusersList = BetaUserPointsHelper:: getAupUsersURL();
+$linktoBUPusersList = UserPoints:: getAupUsersURL();
 </code>
@@ Line 272: / Line 267: @@
 <code php>
-$avatarPath = BetaUserPointsHelper:: getAvatarPath( $userid );
+$avatarPath = UserPoints:: getAvatarPath( $userid );
 </code>
@@ Line 281: / Line 276: @@
 <code php>
-$avatarLivePath = BetaUserPointsHelper:: getAvatarLivePath( $userid );
+$avatarLivePath = UserPoints:: getAvatarLivePath( $userid );
 </code>
@@ Line 307: / Line 302: @@
     if(!defined("_BUP_MEDALS_PATH"))
     {
-        define('_BUP_MEDALS_PATH', JURI::root() . 'components/com_betauserpoints/assets/images/awards/large/');
+        define('_BUP_MEDALS_PATH', JURI::root() . 'components/com_userpoints/assets/images/awards/large/');
     }
     if(!defined("_BUP_MEDALS_LIVE_PATH"))
     {
-        define('_BUP_ MEDALS _LIVE_PATH', JURI::base(true) . '/components/com_betauserpoints/assets/images/awards /large/');
+        define('_BUP_ MEDALS _LIVE_PATH', JURI::base(true) . '/components/com_userpoints/assets/images/awards /large/');
     }
-    $medalslistuser = BetaUserPointsHelper::getUserMedals( '', $userid );
+    $medalslistuser = UserPoints::getUserMedals( '', $userid );
     for each ( $medalslistuser as $medallistuser )
     {
@@ Line 323: / Line 318: @@
 <code php>
-$referreid = BetaUserPointsHelper::getAnyUserReferreID( $userID );
+$referreid = UserPoints::getAnyUserReferreID( $userID );
 </code>
@@ Line 334: / Line 329: @@
 <code php>
-$totalPoints = BetaUserPointsHelper::getCurrentTotalPoints( $referrerid );
+$totalPoints = UserPoints::getCurrentTotalPoints( $referrerid );
 </code>
@@ Line 340: / Line 335: @@
 <code php>
-$user = JFactory::getUser(); $userid = $user->id ; $totalPoints = BetaUserPointsHelper::getCurrentTotalPoints( '', $userid );
+$user = JFactory::getUser(); $userid = $user->id ; $totalPoints = UserPoints::getCurrentTotalPoints( '', $userid );
 </code>
@@ Line 346: / Line 341: @@
 <code php>
-$listActivities = BetaUserPointsHelper::getListActivity($type='all', $userid='all', $numrows=0);
+$listActivities = UserPoints::getListActivity($type='all', $userid='all', $numrows=0);
 </code>
@@ Line 354: / Line 349: @@
 $params $limit = int (0 by default)
 example-1 -> -------------------------------------------------------------------------
-example-1 -> $listActivities = BetaUserPointsHelper::getListActivity('all', 'all');
+example-1 -> $listActivities = UserPoints::getListActivity('all', 'all');
-example-1 SAME AS -> $listActivities = BetaUserPointsHelper::getListActivity();
+example-1 SAME AS -> $listActivities = UserPoints::getListActivity();
 example-1 -> show all activities with pagination, positive and negative points of activity for all users
 -----------------------------------------------------------------------------------
@@ Line 361: / Line 356: @@
 example-2 -> $user = JFactory::getUser();
 example-2 -> $userID = $user->id;
-example-2 -> $listActivities = BetaUserPointsHelper::getListActivity('positive',$userID,20);
+example-2 -> $listActivities = UserPoints::getListActivity('positive',$userID,20);
 example-2 -> show only positive points of activity for the current user logged in and show only 20 rows of recent activities
 </code>
@@ Line 382: / Line 377: @@
 <code php>
-$nextrankinfo = BetaUserPointsHelper::getNextUserRank($referrerid='', $userid='0', currentrank);
+$nextrankinfo = UserPoints::getNextUserRank($referrerid='', $userid='0', currentrank);
 </code>
@@ Line 398: / Line 393: @@
 <code php>
-$num_bup_version = BetaUserPointsHelper::getBupVersion();
+$num_bup_version = UserPoints::getBupVersion();
 </code>
-Returns the current version of BetaUserPoints like -> 4.0.0
+Returns the current version of UserPoints like -> 4.0.0
-==== BetaUserPoints is open for third component ====
+==== UserPoints is open for third component ====
-Create your own plugin for BetaUserPoints !
+Create your own plugin for UserPoints !
 Plugins provide functions which are associated with trigger events.
-Available events in BetaUserPoints:
+Available events in UserPoints:
 <code>
-- onBeforeInsertUserActivityBetaUserPoints - onUpdateBetaUserPoints
+- onBeforeInsertUserActivityUserPoints - onUpdateUserPoints
-- onAfterUpdateBetaUserPoints
+- onAfterUpdateUserPoints
-- onChangeLevelBetaUserPoints
+- onChangeLevelUserPoints
-- onUnlockMedalBetaUserPoints
+- onUnlockMedalUserPoints
-- onGetNewRankBetaUserPoints
+- onGetNewRankUserPoints
-- onResetGeneralPointsBetaUserPoints
+- onResetGeneralPointsUserPoints
-- onBeforeDeleteUserActivityBetaUserPoints
+- onBeforeDeleteUserActivityUserPoints
-- onAfterDeleteUserActivityBetaUserPoints
+- onAfterDeleteUserActivityUserPoints
-- onBeforeDeleteAllUserActivitiesBetaUserPoints
+- onBeforeDeleteAllUserActivitiesUserPoints
-- onAfterDeleteAllUserActivitiesBetaUserPoints
+- onAfterDeleteAllUserActivitiesUserPoints
-- onBeforeMakeRaffleBetaUserPoints
+- onBeforeMakeRaffleUserPoints
-- onAfterMakeRaffleBetaUserPoints
+- onAfterMakeRaffleUserPoints
 </code>
@@ Line 433: / Line 428: @@
 * Created on 15 January 2016.
-* Last updated on 05 April 2023.
+* Last updated on 7 February 2024.